Cookbook

This page collects operational scenarios and guidance for interpreting Session Watcher output. For formal definitions of all terms below, see the Concepts page. For behavioral guarantees, see the Guarantees page.

Scope and Limits

Lamp / bp Interpretation

Scenario: bp stuck at red or amber for many turns. The session has been running beyond the efficient operating zone for an extended period. bp is read from the path the session actually travelled, not from a snapshot of the current L and B: the normalized position behind it only moves forward, so loading more files no longer pulls the session back toward the sweet spot. What can still lower bp is the movable fraction shrinking as the carry grows, or a change of selected files or provider, which re-folds the whole segment under the new economics. If bp stays elevated for many turns, the session is persistently in an inefficient region. Consider preparing a handoff and restarting. If the task is nearly complete, finishing may cost less than the overhead of a fresh context rebuild.

Scenario: White lamp displays throughout the session. White indicates one of three states. (1) no_transcript — the watcher cannot locate or open the transcript file; verify the path configuration. (2) insufficient_data — the transcript exists but no usage rows have been ingested yet (the first API call has not been folded). Since the system overhead floor is set from the very first usage row, this state resolves on the first model interaction — no file reads are required. (3) Healthy low-pressure zone — measurement is reliable, but the normalized position is still short of the sweet spot and below the mirrored amber boundary, which is the pair of conditions the lamp whitens on. This is a normal, efficient state (the session has not yet grown enough for the penalty function to engage). To distinguish these causes, check the reason or reliability field in the status output rather than interpreting white solely as a data-quality problem.

Scenario: mf seems low. The movable fraction is the share of the context bill that restart timing can reach. The AM-GM bound caps it at 1/(1+√2), and a value well below that cap means most of the cost is fixed overhead — timing optimization has limited leverage. Handoff value is reduced but not zero: the reminder still comes, only at a longer interval, because the wallet clock's unit grows as mf shrinks. A persistently low mf means the session is carry-heavy (large B relative to growth), which is normal for sessions that loaded many files early.

Scenario: Understanding the two progress bars. The dashboard shows two bars. The cycle bar shows how far through the current billing cycle you are. It fills with the per-call rent increment; when full it wraps to zero and increments the cycle count. A fast-filling bar means rent is accruing quickly. It is purely diagnostic — it does not trigger anything.

The reminder bar is the decision reminder, and it is the only bar the statusline carries. It fills with the same rent increment, divided by the reminder interval (which adapts to mf — shorter when restart value is high). It is running from the first measured call rather than waiting for a threshold: the call whose increment fills the bar raises a reminder stamped with the lap count reached and wraps the bar, and the magazine beside it spends one tick per completed lap up to its visible slots and then counts the rest in an overflow label — so a call that fills the bar more than once leaves the laps ahead of the reminders raised. The reminder bar tells you "you have paid enough carry rent to be worth a decision," and because it reads accumulated rent alone, adjusting the baseline or the file selection cannot take back a reminder already given.

Scenario: bp seems wrong for what you are doing. bp is only as good as B_default. If B_default does not reflect the files you actually need for the current task, bp will be miscalibrated. Common cases: (1) the session loaded many large files early that are no longer relevant — B_default is inflated, bp appears lower than reality. (2) Critical working files are gitignored or outside the project — B_default understates the real carry, bp appears higher than warranted. Before trusting an amber/red signal (or an unexpectedly green one), sanity-check the bucket panel: does B_default match what you would actually carry into a new session? If not, adjust includes/excludes first.

Scenario: Provider switch causes a bp jump. Switching models mid-session changes cRatio (the cache-write-to-cache-read price ratio). Since bp depends on cRatio through mf and dhat, a ratio change recalculates the cost geometry instantly. The jump is not an error — it reflects genuine repricing of the session under new economics. If the new model has a lower cache-write/cache-read ratio, the sweet spot moves inward and the session may enter amber sooner; if higher, the session gets more room before penalty engages.

When to Restart

Scenario: bp crosses amber (the first threshold). Amber signals that the timing-sensitive cost premium at the position travelled has reached a noticeable level. This is a suggestion, not a command. If a natural stopping point exists (task boundary, topic shift), this is a good time to prepare a handoff. If mid-task, weigh the cost of context rebuilding against the ongoing overspend.

Scenario: bp crosses red (the higher threshold). Red means the overspend fraction is substantially higher. However, red does not mean "restart immediately." If the current task will complete in a few more turns, finishing is usually cheaper than the disruption cost of a handoff plus the tokens spent rebuilding context in a new session. Red is most actionable at natural task boundaries.

Scenario: Mid-task bp is red but work is nearly done. Finish the task. The marginal cost of a few more turns at elevated bp is typically less than the fixed cost of preparing a handoff, starting a new session, loading context, and re-orienting. Use bp red as a signal to avoid starting additional unrelated tasks in this session.

Scenario: The session sits in a flat valley just past sweet. When u (the normalized position) is only moderately above 1, the overspend grows slowly. The cost function is quadratic near the sweet spot, so a 2x deviation in u from sweet costs only about 25% additional bill on the timing-sensitive fraction. Flat valleys are efficient enough to continue working through.

Scenario: Applying a fixed token policy ("restart at 200k tokens"). Fixed-token restart policies ignore the session's actual economics. A session with high g (rapid growth) reaches amber at a higher L than one with low g — higher g increases dhat (the characteristic scale), which pushes the sweet spot and amber threshold further out, giving more room before the premium engages. A session with low mf (mostly dead weight) may never benefit from restart regardless of total size. Use bp directly — it already integrates L, B, g, and cRatio into a single actionable signal.

Measurement Bias and Conservative Assumptions

Scenario: B_default excludes gitignored files, but the session works with them. B_default reflects only the files that pass the inclusion filter (not gitignored, not user-excluded). If your session heavily relies on files that are excluded from baseline, B_default understates the true required carry. The session will appear to have a higher premium than it actually deserves. Use the include override mechanism to add critical paths so the measurement accounts for them.

Scenario: Residual is large — is it all waste? The residual bucket (context stock minus B) captures everything not attributed to tracked file paths: reasoning history, tool output, conversation structure, and ephemeral working memory. (System prompts and tool definitions are part of the system overhead floor, which is already included in B — they do not appear in the residual.) Much of this is productive context, not waste. A large residual is normal for tool-heavy sessions. The metric does not judge the value of residual content — only that it exists and contributes to cost.

Scenario: g is climbing but the session feels productive. The growth rate g measures how fast new content arrives relative to the baseline. It does not distinguish productive growth (new files being explored, code being written) from thrashing (repeated failed attempts generating tool output). A high g means cost is accumulating quickly regardless of cause. If the growth is productive, the session is efficiently using expensive context; bp still applies as the cost signal.

Scenario: mf seems capped below 50%. The movable fraction has a theoretical ceiling of 1/(1+√2) (the AM-GM bound). This is by construction: even in the worst case, timing optimization can affect at most this fraction of total bill. However, bp itself is NOT bounded by this ceiling. Since bp equals mf multiplied by the positional penalty pp, and pp is unbounded (it grows without limit as u deviates from 1), bp can exceed any fixed value in a sufficiently extended session. The mf bound limits only the movable-fraction component, not the overall bill premium.

Scenario: Detected cache miss during the session. When a cache miss is detected (cacheRead drops while total context stock is preserved), L is reconstructed as the whole context stock — it does not drop to near zero. The miss classifier recognizes this pattern and applies that reconstruction, so the metrics see a continuous L rather than a transient cliff. Segmentation is a separate question with a single answer: a topology change (a root UUID that is not the file's first, which is what /compact and /continue produce). A cache miss is not one, a falling token total is not one, and new files entering the B bucket are not one. Undetected misses (patterns that do not match the miss classifier) are not explicitly handled, but are rare in practice.

Scenario: "Metric says amber but the session feels fine" / "Metric says green but output quality dropped." Session Watcher measures cost geometry, not output quality. Amber/red means you are paying more than optimal timing would require — the model may still be performing well. Conversely, green means cost is efficient — but the model could be producing poor output due to task difficulty, prompt issues, or capability limits. Never use lamp state as a quality proxy.

Handoff Operations

Shortest path: /sw-handoff → /clear → /sw-load.

Scenario: Verifying carry quality after loading a handoff. After load_handoff, the agent receives the handoff package: a list of kept paths (projected to path, symbol names with current line numbers, and stale/missing markers) and a summary. The response does NOT include actual file content — the agent must read kept paths itself. To verify carry quality, read the kept paths and confirm they still exist and contain the expected content. Hash validation exists internally (the server stamps content hashes at load time for telemetry) but is not exposed in the agent-visible response. B_default recovery depends on which kept files are still readable when the agent accesses them in the new session.

Scenario: Handoff completed but new session B is lower than expected. load_handoff retrieves the handoff package but does not validate file existence or fail on missing files. Files that have been deleted, renamed, or moved since prepare time will still appear in the returned paths list — the shortfall surfaces only when the agent (or the fold stream) attempts to read those files and finds them absent. This is expected: B reflects actual current file state, not the historical snapshot from prepare time. To diagnose, compare the paths in the loaded package against what exists on disk.

Scenario: Choosing which paths to keep during prepare. The prepare_handoff tool accepts a paths_to_keep list. Focus on files that are central to the next task — files you will read or edit in the continuation. The server auto-populates token weights from B_rebuild data. Carrying too many paths inflates B without proportional value; carrying too few means the new session must rediscover context. Aim for the minimal set that lets the next session avoid re-reading core files.

Scenario: Understanding the load token. The load token is a human-readable semantic identifier (two content words plus a random suffix, e.g., refactor-baseline-elk) generated from the handoff's next_task field. Use it to retrieve a specific handoff with load_handoff. Tokens are unique within a project's handoff store. If you lose the token, use the free-text query parameter to search by summary content.

Configuration and Operations

Scenario: Reading the statusline fields. The statusline displays (left to right): lamp emoji (white/green/yellow/red), the reminder bar as a bar and a percentage (progress toward the next reminder, wrapping on each one), bp percentage, u value (normalized position), delta (growth rate g), L/B ratio, and model tag. When the rate lamp is not yet reliable, a neutral "measuring..." line appears instead; when measurement is reliable but no ledger has been matched to the segment, the bar is drawn empty with its percentage slot blank rather than showing a stale value. A reminder appears as a second line.

Scenario: Excluding or including specific files. User overrides control which files count toward B_default. Excluding a file removes it from the baseline denominator — the session appears to be carrying less, and bp may increase (same L, lower B). Including a gitignored or previously-excluded file adds it to the baseline — bp may decrease. Overrides propagate to sibling files in the same directory through inference when the directory shows unanimous inclusion or exclusion state.

Scenario: How long until metrics become reliable after session start. Metrics become reliable once B_default and cRatio are both positive. Since the system overhead floor is set from the very first usage row (as max(cacheRead, cacheCreation, input)) and is itself part of B_default, B_default becomes positive immediately on the first model interaction — no file reads are required. The transition from white (measuring) to a computed lamp can therefore happen on the very first usage row. Before that first usage, the system shows white with reason insufficient_data. Sessions with no transcript at all show white with reason no_transcript.

Scenario: Dashboard vs statusline — same data source? Yes. Both the browser dashboard (served via the built-in HTTP server) and the CLI statusline (rendered by the hook into the terminal status area) read from the same getStatus() output on the watcher instance. The dashboard uses SSE for event notification (tick and scan messages), then fetches full snapshots via REST (/api/status, /api/history, /api/buckets) on each scan event; polling is the fallback trigger when SSE is unavailable. The statusline formats a compact single-line summary of the same fields. They always reflect the same underlying state, though the dashboard may show historical chart data that the statusline cannot.