@aragon-agent/cli 0.6.4 → 0.6.7

package/CHANGELOG.md

@@ -9,6 +9,20 @@ were written.
 
 ### Added
 
+- **`system/init` now lists what this build can do.** A new optional
+  `capabilities: string[]` field, carrying `["interrupt"]` for this release.
+
+  A wrapper cannot tell by observation whether an interrupt will settle
+  gracefully or kill the process outright, and guessing wrong costs the user
+  their conversation. Rather than have callers compare version numbers — which
+  breaks on forks, prereleases, and version shapes nobody anticipated — the
+  build now says so itself, in an event that already arrives on every start.
+  Absent on older builds, and absence should be read as "no", never as
+  "probably".
+
+  Additive, so `schemaVersion` does not move. Consumers that do not know the
+  field ignore it, exactly as the schema contract asks.
+
 - **The composer understands pasting.** Until now it did not have the concept at
   all: every byte the terminal delivered on stdin was a keystroke, and a
   clipboard block is thousands of bytes arriving in an unpredictable number of
@@ -58,6 +72,29 @@ were written.
 
 ### Fixed
 
+- **`{"type":"interrupt"}` now really does settle the run — on every platform.**
+  The stdin interrupt frame used to raise a SIGINT at our own process. On POSIX
+  that reaches the runner's terminator and the run winds down properly: it
+  breaks out of the loop, persists the session, and emits `result` with the
+  usage and cost. On Windows, Node does not deliver a self-directed SIGINT to
+  its own handlers — the process simply terminated with exit code 1, having run
+  none of it.
+
+  For anyone using `aragon exec` interactively that difference was invisible,
+  because an interrupt there is usually the last thing that happens. It is not
+  invisible to a **wrapper** that interrupts a turn and then respawns on the same
+  `--session-id` to keep the conversation going: on Windows it silently got back
+  a session missing everything since the previous save. `exec/index.ts` has
+  carried a comment about that caller for some time ("PERSIST FIRST, ANNOUNCE
+  SECOND … a caller that reads `result` and immediately respawns with the same
+  `--session-id` must not race the writer"), so the intent was there; the path
+  just could not be reached on Windows.
+
+  The frame now calls the runner directly instead of going through a signal.
+  POSIX behaviour is byte-for-byte unchanged — the same code runs, with the same
+  `stopReason`, the same exit code 130, and the same two-second window in which a
+  second signal still forces an immediate exit.
+
 - **A pasted API key is stored correctly again.** Ink broadcasts each stdin chunk
   to every mounted input handler, so the settings screen, the question overlay
   and the plan-review feedback field all see what the composer sees. Without

package/README.md

@@ -413,6 +413,7 @@ signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 | `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
 | `/fast [on\|off\|model <id>\|provider <id>\|same\|review <n\|off>\|delegate on\|off]` | Fast model tier: status and this session's totals, the on/off switch, which model, the review cadence |
 | `/compact [status\|on\|off\|threshold <n>\|keep <n>\|history\|show <n>\|<instructions>]` | Context compaction: occupancy and this session's totals, the on/off switch, when it fires, how much it keeps. With free text, compacts now and tells the summarizer what to pay attention to |
+| `/context` | What the context gauge is showing: occupancy split into measured and estimated, the window and **where it came from**, how stale the measurement is, compaction's actual state, and what the session-spend readout includes |
 | `/bg [list\|logs <id> [n]\|stop <id\|all>\|status]` | Background services: what is running, its log tail, and how to stop it. `list` is the default |
 | `/update [status\|now\|skip\|off]` | Auto-update: what is running, what is available, where it came from, when it looks again. `now` forces a check past the throttle; `skip` declines the offered version until a newer one appears |
 | `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
@@ -799,7 +800,8 @@ ask — and the agent writes the finished plan as its final message in markdown.
 For work with three or more distinct steps the agent keeps a **visible plan**:
 it writes a checklist with the `todo_write` tool, marks exactly one item as in
 progress, and ticks it off before starting the next. In full-screen mode that
-list is rendered as a right-hand rail, about a fifth of the terminal wide.
+list is rendered as a right-hand rail, targeting 15% of the terminal width
+(14–36 columns, including its separator and padding).
 
 ```
   transcript ...                            | TODO             2/7
@@ -807,8 +809,7 @@ list is rendered as a right-hand rail, about a fifth of the terminal wide.
                                             |
                                             | v  1 Read the reducer
                                             | v  2 Design the store
-                                            | >  3 Wiring the rail into
-                                            |      AppShell
+                                            | >  3 Wiring the rail...
                                             | o  4 Add the panel-rows test
                                             | o  5 Update the README
                                             |      +2 more
@@ -832,7 +833,7 @@ not also tell the model may change it — except you, saying so:
   conversation has just been replaced.
 - A finished plan is dropped at the START of your next message, so you still get
   to see `7/7 done`. An unfinished one survives "continue" / "now do the rest",
-  and is dropped after three unrelated turns rather than holding a fifth of the
+  and is dropped after three unrelated turns rather than holding part of the
   screen for the rest of the session.
 
 ### When a run ends with steps left
@@ -888,11 +889,19 @@ planning discipline and hides the column — which is what you want with a scree
 reader, and what `--no-todo-panel` does for a whole session. Under `-p` the plan
 is written to stderr as `[todo] 3/7 <step>` lines, suppressed by `--quiet`.
 
-The rail is not mounted below 80 columns, while an overlay is open, in inline
-mode, or when the viewport is too short to say anything useful; the transcript
-keeps at least 62 columns at every width. In those cases the counter appears in
-the status bar instead, and the checklist is still written into the transcript
-as one card per turn.
+右栏从 76 列开始显示，正文至少保留 62 列；100 列终端使用 15 列右栏。
+已有任务时，团队面板按实际行数占用空间，补全菜单的边框和提示也计入预算。
+例如 100×20、团队占 8 行时，TODO 仍以 4 行紧凑视图显示。
+
+剩余 3–5 行时保留标题、完成计数、当前任务与合并提示 `-A +B`：
+`-9 +10` 表示上方隐藏 9 项、下方隐藏 10 项。6 行起使用常规视图；
+所有任务各占一行，全文仍可在正文任务卡片中查看。进度条需要至少 20 列、8 行。
+输入增长导致空间不足时团队先折叠为摘要；菜单不足 3 行时隐藏，其候选不会拦截输入。
+
+低于 76 列、共享区域不足 3 行、打开 overlay、显式关闭面板、没有任务或
+inline 模式时不显示右栏。低于 12 行使用原有小终端提示；扩大窗口后自动恢复。
+inline 仍使用上文的单行任务条。`/todo status` 中的 `Panel: on` 仅表示配置开启，
+实际可见性还取决于数据和窗口空间；可以通过该命令区分未生成计划与暂时隐藏。
 
 ## Built-in tools
 
@@ -1211,6 +1220,84 @@ it for a background advisory is how an unrequested call ends up competing with
 you for a rate-limited provider's quota. The review's own wall-clock bound is
 20 s.
 
+## The context gauge
+
+The right end of the status bar answers one question: **how full is the context,
+out of how much.**
+
+```
+[####----] 43%  86.0k/200.0k   total 1.2M^ 48.0k v   $3.21   12 tok/s  1m02s
+            ^        ^         ^
+            |        |         +-- session spend, prompt side / output side
+            |        +-- occupied / window
+            +-- the two together, as a percentage
+```
+
+The readouts drop as the terminal narrows, in that order of priority:
+
+| Columns | Right cluster |
+|---|---|
+| >= 96 | `[####----] 43%  86.0k/200.0k  total 1.2M^ 48.0k v  $3.21` |
+| 72-95 | `[####----] 43%  86.0k/200.0k  $3.21` |
+| 60-71 | `[####----] 43%  $3.21` |
+| < 60 | `43%  $3.21` |
+
+**Two different markers, because there are two different things to doubt.**
+
+- `~` sits on the **percentage** and means the *numerator* is partly a guess:
+  either no completed turn has reported usage yet (right after `/resume`, or
+  right after a compaction), or tool results have been appended since the last
+  measurement and their size is estimated.
+- `?` sits on the **window** and means the *denominator* is a guess: the model is
+  not in the built-in table, so a flat 128 000 was substituted. See
+  `contextWindow` below.
+
+**The percentage keeps moving during a turn.** Every tool result nudges it,
+whether or not compaction is enabled — it is not a compaction feature, and a
+session started with `--no-compaction` gets the same live reading. After
+`/resume` the gauge shows the restored session's real occupancy immediately,
+without sending anything.
+
+### `/context`
+
+The gauge is a bar and a rounded percentage; `/context` is the full answer, at
+any width, in any mode:
+
+```
+Context
+  Occupancy      43%   86.2k of 200.0k   [measured 85.1k + 1.1k estimated]
+  Window         200000   from the model table
+  Since measured 1.1k estimated tokens appended since the last provider-reported usage
+  Compaction     on - triggers at 90% (amber at 75%), 2 this session, 118.0k reclaimed
+  Session spend  1.2M in (incl. 940.0k cache read, 12.0k cache write) / 48.2k out, $3.21
+                 includes subagent, fast-tier and compaction spend,
+                 not just this conversation
+```
+
+Two lines are worth reading closely. **`Window`** always names where the number
+came from — the model table, your own `contextWindow`, or the invented
+placeholder — because those are indistinguishable everywhere else. And
+**`Compaction`** reports what is actually true of this session, including
+`off - not registered for this session (started with --no-compaction)`; it never
+promises a threshold that nothing will act on.
+
+### `contextWindow`
+
+When the model is not in the built-in table — a custom `baseUrl`, a self-hosted
+id, something released last week — the denominator is a **fabricated** 128 000
+and the percentage is meaningless. Correct it:
+
+```bash
+aragon config set contextWindow 1000000   # persisted; prints "Set contextWindow = 1000000"
+aragon config set contextWindow auto      # back to the model table / placeholder
+ARAGON_CONTEXT_WINDOW=1000000 aragon      # one session
+```
+
+Values are clamped to `[8000, 5000000]`; `auto` (the default) is stored as
+`null`. Setting it removes the `?` marker, because you have asserted the number —
+and `/context` still shows that it came from you, which is what makes a wrong
+value findable.
+
 ## Context compaction
 
 A long agentic run fills the model's context window. Before this existed, the
@@ -1307,7 +1394,10 @@ Three surfaces, each answering something the others cannot:
 - **As state** — a `compacting` chip in the status bar, and the context gauge's
   colours aligned to your own thresholds. The gauge **falls immediately** after a
   compaction rather than waiting for the next turn, with a `~` while the value is
-  derived rather than measured.
+  derived rather than measured. The colours follow your configured thresholds
+  whenever compaction is **enabled**, even if no summarizer model currently
+  resolves; after `/compact off` they fall back to the generic 60 / 85, because
+  colouring by a rescue that is not coming is worse than not colouring at all.
 - **As a record** — a transcript card with the before/after message and token
   counts, the summarizer, the duration, and the summary itself. `Ctrl+O` expands
   it.
@@ -1320,7 +1410,9 @@ self-disabled, or the ladder ran out.
 
 `/compact status` is the guaranteed surface: the chip drops on a narrow terminal
 and the card scrolls away, but the command answers at any width, in any mode,
-after the fact.
+after the fact. For the gauge specifically, [`/context`](#the-context-gauge) is
+the equivalent — and it works in a session that never registered compaction at
+all.
 
 ### When the RECENT turns are what does not fit
 
@@ -1701,6 +1793,8 @@ env / `.env` → CLI flags**.
   reasoning blocks), `ARAGON_LIVE_TOOL_OUTPUT` (`0` keeps a running tool card to
   one line),
   `ARAGON_MAX_TOKENS` (a number, or `auto` / `0` for the per-model ceiling),
+  `ARAGON_CONTEXT_WINDOW` (a number, or `auto`; the denominator the context
+  gauge measures against),
   `ARAGON_THEME`,
   `ARAGON_FULLSCREEN`, `ARAGON_PLAN` (`1` starts in plan mode),
   `ARAGON_TEAM` (`0` disables team subagents), `ARAGON_TEAM_MAX` (fan-out width),
@@ -1728,6 +1822,7 @@ env / `.env` → CLI flags**.
 | Config key | Default | Meaning |
 | --- | --- | --- |
 | `maxTokens` | `64000` | Output token cap, clamped to `[256, 200000]`. `null` means **auto** — use each model's own ceiling, never above 64000. Absent means the default. See [Output token limits](#output-token-limits). |
+| `contextWindow` | `null` | The window the context gauge measures against, clamped to `[8000, 5000000]`. `null` means **auto** — the built-in model table, or a fabricated 128000 for a model it has never seen. Set it when the gauge shows `?` on the denominator. See [The context gauge](#the-context-gauge). |
 | `showThinking` | `false` | Draw the reasoning the model returns. `thinkingLevel` is the effort the provider is asked to **spend**; this is whether the terminal **shows** it. Off by default: a settled turn that thought leaves one muted `thought for 12s` row in its place, so nothing is hidden silently. |
 | `liveToolOutput` | `true` | Draw up to eight sanitised rows of a **running** tool's output on its card, plus a `no output for Ns` row when the child goes quiet. On by default, unlike `showThinking`: this ADDS the information a long `bash` call otherwise hides, and its cost is bounded by construction — eight rows per call, sixteen calls, whatever the command emits. Turn it off and the card is a single `running` row again, with no store allocated and no recorder attached. |
 | `fullscreen` | `true` | Use the full-screen TUI (still subject to the automatic downgrades). Setting it to `false` opts out permanently; leaving it `true` is *not* a force — only `--fullscreen` / `ARAGON_FULLSCREEN=1` override the heuristics. |
@@ -1805,6 +1900,8 @@ ARAGON_MAX_TOKENS=32000 aragon       # env layer, between the flag and the file
 aragon config set maxTokens 32000    # persisted; prints "Set maxTokens = 32000"
 aragon config set maxTokens auto     # persisted as null
 aragon config set maxTokens default  # back to 64000
+aragon config set contextWindow 1000000  # the gauge's denominator
+aragon config set contextWindow auto     # back to the model table
 aragon config get maxTokens          # "64000" | "auto"
 ```
 

package/dist/agent/controller.d.ts

@@ -18,8 +18,9 @@ import type { TeamEvent, TeamSnapshot } from '../team/types.js';
 import { ProcSupervisor } from '../proc/supervisor.js';
 import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
 import { type FastStatus } from '../fast/wiring.js';
-import type { FastEventListener } from '../fast/types.js';
-import type { CompactionEventListener, CompactionSnapshot } from '../compaction/types.js';
+import type { FastEventListener, FastSnapshot } from '../fast/types.js';
+import { ContextMeter, type ContextUsageListener } from '../compaction/meter.js';
+import type { CompactionEventListener, CompactionSnapshot, ContextUsageSnapshot } from '../compaction/types.js';
 import type { TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
@@ -178,6 +179,7 @@ export declare class AgentController {
     private readonly outputListeners;
     private readonly fast;
     private readonly compaction;
+    private readonly contextMeter;
     private readonly procs;
     /**
      * The host's notice channel, kept so `prompt()`'s totality has somewhere to
@@ -612,6 +614,41 @@ export declare class AgentController {
      * `subscribeTodos` already set.
      */
     subscribeFast(listener: FastEventListener): () => void;
+    /**
+     * The FIFTH thin forwarder: the current fast-tier snapshot, or `null` when
+     * this session never registered a tier at all
+     * (web-use-tier-cooperation-and-control-closure §4.2.1).
+     *
+     * `null` and "a snapshot with `live: false`" are different answers and callers
+     * depend on the difference: the first means "there is no tier here", the
+     * second means "there is one and it is not usable right now".
+     *
+     * Deliberately NOT folded into the existing `review_end` event: that shape is
+     * consumed by `App` too, and this round promised to be purely additive.
+     */
+    fastSnapshot(): FastSnapshot | null;
+    /**
+     * Subscribe to occupancy publications. Returns an unsubscribe function.
+     *
+     * THE SOLE UPSTREAM OF `ViewState.context` (I-1). The gauge used to have two
+     * writers - `turnEnd` and a `contextTokensEstimated` dispatch fired from two
+     * places in `App` - which is the entire cause of P0-1: both wrote in the same
+     * synchronous fan-out and the second one won, restoring the pre-compaction
+     * figure one statement after the bar had correctly fallen. One writer makes
+     * that class of bug unrepresentable rather than merely fixed.
+     */
+    subscribeContextUsage(listener: ContextUsageListener): () => void;
+    /**
+     * Occupancy right now, re-measuring if the history has moved.
+     *
+     * `/context` READS THIS AND NOT `getCompactionSnapshot().pressure` (RV-8). The
+     * latter returns `offCompactionSnapshot()`'s hardcoded zero pressure when
+     * compaction was never registered, so a report built on it would read 0 % for
+     * precisely the sessions this feature exists to fix.
+     */
+    getContextUsage(): ContextUsageSnapshot;
+    /** The meter itself, for the wiring's single-instance assertion and tests. */
+    getContextMeter(): ContextMeter;
     /** Whether a `ContextManager` exists at all. Fixed at construction. */
     isCompactionRegistered(): boolean;
     /** Whether it will actually fire. Flipped live by `/compact on|off`. */

package/dist/agent/controller.js

@@ -28,6 +28,7 @@ import { addSignalHook } from '../logging/install.js';
 import { describeFastTierProblem, fastProviderOf, resolveFastTier } from '../fast/resolve.js';
 import { FastWiring, offFastStatus } from '../fast/wiring.js';
 import { CompactionWiring, offCompactionSnapshot } from '../compaction/wiring.js';
+import { ContextMeter } from '../compaction/meter.js';
 import { TodoStore } from '../todo/store.js';
 import { createTodoTool } from '../todo/todo-tool.js';
 import { buildTodoBlock } from '../todo/prompt.js';
@@ -187,6 +188,23 @@ export class AgentController {
     // -----------------------------------------------------------------------
     compaction;
     // -----------------------------------------------------------------------
+    // Context occupancy (context-usage-gauge-accuracy §3.2 / W1)
+    //
+    // CONSTRUCTED UNCONDITIONALLY, unlike its neighbour, and that asymmetry IS the
+    // feature. `compaction` above is `null` for a session started with
+    // `--no-compaction` - and before this field existed, that took the only
+    // measuring code in the process with it: such a session's gauge had exactly
+    // one sample per turn (the provider's `turn_end` usage) and read `0 %` after a
+    // `/resume`. Occupancy is not a compaction concern; it is what compaction
+    // READS.
+    //
+    // IT COSTS A HEADLESS HOST NOTHING (I-11). `aragon exec` builds an
+    // `AgentController` too, and nothing there reads this number; the meter arms
+    // no timer while it has no subscribers, so the extra object is a few scalars
+    // and a `Set`.
+    // -----------------------------------------------------------------------
+    contextMeter;
+    // -----------------------------------------------------------------------
     // Background services (background-service-supervision §3.3 / §3.6)
     //
     // CONSTRUCTED UNCONDITIONALLY, and that is the one thing about this field that
@@ -500,6 +518,28 @@ export class AgentController {
             modelId: config.model,
             ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
         };
+        // --- Context occupancy, part 1: BEFORE the Agent, UNCONDITIONALLY ------
+        //
+        // Built here for the same C-12 reason the wiring is - lazy `getMessages` /
+        // `getSystemPrompt` closures, `attach` after `new Agent` - and built for
+        // EVERY session, including one with compaction off, because that is the one
+        // whose gauge was broken (P1-4 / P0-2).
+        this.contextMeter = new ContextMeter({
+            getMessages: () => this.agent.state.messages,
+            getSystemPrompt: () => this.agent.state.systemPrompt,
+            getModelInfo: () => this.getModelInfo(),
+            // ONE PREDICATE FOR "IS THE DENOMINATOR REAL". `isPricedModel` is
+            // `modelRegistry.getModel(...) !== undefined`, and `getModelInfoFor` falls
+            // back to `buildRuntimeModel` - a 128k placeholder AND a zero cost table -
+            // for exactly the models it answers `false` for. The two are the same
+            // question about the same static table, not a coincidence.
+            isWindowKnown: () => this.isPricedModel({
+                providerId: this.config.provider,
+                modelId: this.config.model,
+            }),
+            // LIVE, so a settings-screen edit moves the denominator without a relaunch.
+            getWindowOverride: () => this.config.contextWindow,
+        });
         // --- Context compaction, part 1: BEFORE the Agent ----------------------
         //
         // It needs no agent reference to EXIST — only live config, the key
@@ -517,6 +557,9 @@ export class AgentController {
                 getMessages: () => this.agent.state.messages,
                 getSystemPrompt: () => this.agent.state.systemPrompt,
                 notify: (level, text) => deps.notify?.(level, text),
+                // ONE METER PER PROCESS (R-1). The wiring forwards it to the compactor,
+                // so the trigger and the gauge cannot read two different numbers.
+                meter: this.contextMeter,
             })
             : null;
         this.agent = new Agent({
@@ -567,6 +610,15 @@ export class AgentController {
         // subscribed could not run before `new Agent(...)`, and the port has to be
         // inside its constructor argument (C-12 / P0-2).
         this.compaction?.attach((listener) => this.agent.subscribe(listener));
+        // --- Context occupancy, part 2: after the Agent exists -----------------
+        //
+        // ORDER RELATIVE TO THE LINE ABOVE IS DELIBERATELY IRRELEVANT (I-9 / T7).
+        // The append direction is order-free because the meter marks itself dirty
+        // and re-measures on read; the replace direction is order-free because the
+        // splice is announced from `settlePending`'s own synchronous code rather
+        // than from a listener. If a future change makes this ordering matter, the
+        // fix is at those two sites, not here.
+        this.contextMeter.attach((listener) => this.agent.subscribe(listener));
         // --- Fast tier, part 2: after the Agent exists --------------------------
         //
         // `FastWiring` subscribes to the lead's event stream, so it cannot be built
@@ -1207,6 +1259,7 @@ export class AgentController {
         this.teamRuntime?.dispose();
         this.fast?.dispose();
         this.compaction?.dispose();
+        this.contextMeter.dispose();
         // REAP BEFORE RELEASING THE HOOK, in that order: disposal is a teardown, and
         // a service that outlives it has nothing left that could ever stop it.
         this.procs.reapSync();
@@ -1337,6 +1390,13 @@ export class AgentController {
         // so the snapshot the chip and `/compact status` read has to be refreshed
         // for the same reason and at the same moments (the RV-3 lesson).
         this.compaction?.onConfigChanged();
+        // THE DENOMINATOR MOVED, NOT THE HISTORY (context-usage-gauge-accuracy §3.4).
+        // A re-measure, deliberately NOT a reset: the measured base is still a true
+        // statement about the messages, and throwing it away would swap a correct
+        // numerator for a whole-history estimate on a common operation. The
+        // numerator's calibration is one turn stale until the next `turn_end`
+        // (RV-13), which is the trade this call names.
+        this.contextMeter.onWindowChanged();
     }
     setThinkingLevel(level) {
         this.config = { ...this.config, thinkingLevel: level };
@@ -1435,7 +1495,14 @@ export class AgentController {
         // INVALIDATION SITE 3 (context-auto-compaction-hardening §3.2.3). The history
         // was CLEARED, not appended to, so the prefix length the last measurement
         // covered indexes an array that no longer exists.
+        //
+        // BOTH LINES, AND THE SECOND IS NOT REDUNDANT (context-usage-gauge-accuracy
+        // I-9). The wiring is `null` for a `--no-compaction` session, so it is the
+        // meter call that guarantees a re-measure - deleting it "to de-duplicate"
+        // reintroduces P0-2 for exactly the sessions this feature was written for. A
+        // deep reset is idempotent, so both firing costs nothing.
         this.compaction?.onHistoryReplaced();
+        this.contextMeter.onHistoryReplaced();
         // A new conversation has no loaded skills, so the "already loaded earlier
         // in this conversation" hint would otherwise start lying (P2-9).
         this.skills.getRegistry().clearActive();
@@ -1455,7 +1522,15 @@ export class AgentController {
         // INVALIDATION SITE 4 (§3.2.3) - `/resume`, and any future host-side rewrite.
         // `estimateAppendedTokens` bounds-checks as well, so a MISSED site costs
         // accuracy and never correctness; that belt does not make this call optional.
+        //
+        // THE SECOND LINE IS THE P0-2 FIX. Before it, `/resume` of a 180k-token
+        // session left the gauge and `/compact status` reading 0 %: nothing
+        // re-measured and nothing published, so the mount-time "empty history"
+        // reading stood until the next completed turn. The DEEP reset also drops
+        // `estimateOffset`, because `/resume` can change the model in the same
+        // breath (I-8).
         this.compaction?.onHistoryReplaced();
+        this.contextMeter.onHistoryReplaced();
     }
     getMessages() {
         return this.agent.state.messages;
@@ -1571,6 +1646,56 @@ export class AgentController {
             return () => { };
         return this.fast.subscribe(listener);
     }
+    /**
+     * The FIFTH thin forwarder: the current fast-tier snapshot, or `null` when
+     * this session never registered a tier at all
+     * (web-use-tier-cooperation-and-control-closure §4.2.1).
+     *
+     * `null` and "a snapshot with `live: false`" are different answers and callers
+     * depend on the difference: the first means "there is no tier here", the
+     * second means "there is one and it is not usable right now".
+     *
+     * Deliberately NOT folded into the existing `review_end` event: that shape is
+     * consumed by `App` too, and this round promised to be purely additive.
+     */
+    fastSnapshot() {
+        return this.fast?.snapshot() ?? null;
+    }
+    // -----------------------------------------------------------------------
+    // Context occupancy (context-usage-gauge-accuracy §4.2) — THREE FORWARDERS
+    //
+    // ALL THREE ARE AVAILABLE UNCONDITIONALLY, which is the whole difference
+    // between this block and the compaction one below it: there is no
+    // `?? offSomething()` fallback here, because the meter always exists.
+    // -----------------------------------------------------------------------
+    /**
+     * Subscribe to occupancy publications. Returns an unsubscribe function.
+     *
+     * THE SOLE UPSTREAM OF `ViewState.context` (I-1). The gauge used to have two
+     * writers - `turnEnd` and a `contextTokensEstimated` dispatch fired from two
+     * places in `App` - which is the entire cause of P0-1: both wrote in the same
+     * synchronous fan-out and the second one won, restoring the pre-compaction
+     * figure one statement after the bar had correctly fallen. One writer makes
+     * that class of bug unrepresentable rather than merely fixed.
+     */
+    subscribeContextUsage(listener) {
+        return this.contextMeter.subscribe(listener);
+    }
+    /**
+     * Occupancy right now, re-measuring if the history has moved.
+     *
+     * `/context` READS THIS AND NOT `getCompactionSnapshot().pressure` (RV-8). The
+     * latter returns `offCompactionSnapshot()`'s hardcoded zero pressure when
+     * compaction was never registered, so a report built on it would read 0 % for
+     * precisely the sessions this feature exists to fix.
+     */
+    getContextUsage() {
+        return this.contextMeter.currentUsage();
+    }
+    /** The meter itself, for the wiring's single-instance assertion and tests. */
+    getContextMeter() {
+        return this.contextMeter;
+    }
     // -----------------------------------------------------------------------
     // Context compaction (context-auto-compaction §3.2.1) — THIN FORWARDERS
     // -----------------------------------------------------------------------

package/dist/agent/reducer.d.ts

@@ -14,7 +14,7 @@ import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agen
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
 import type { FastReview, FastSnapshot } from '../fast/types.js';
-import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger } from '../compaction/types.js';
+import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger, ContextUsageSnapshot } from '../compaction/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
 import type { ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
@@ -329,6 +329,16 @@ export type Entry = {
 export interface UsageTotal {
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Cache read hits (context-usage-gauge-accuracy §3.6 / P1-3).
+     *
+     * `occupiedTokens` counts them and `computeCost` PRICES them, so a session
+     * total that omits them makes the status bar's `^` read lower than the `$`
+     * next to it - on the same row, from the same turns. That was three units on
+     * one line, and this field plus its sibling are what collapse them to one.
+     */
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
     costUsd: number;
 }
 /**
@@ -349,8 +359,20 @@ export interface ViewState {
     entries: Entry[];
     status: 'idle' | 'running';
     usageTotal: UsageTotal;
-    /** Running input size of the most recent turn vs. the model context window. */
-    contextTokens: number;
+    /**
+     * Context occupancy, as published by `AgentController`'s `ContextMeter`.
+     *
+     * ITS ONLY WRITER IS `case 'contextUsage'` (I-1), and that is the structural
+     * half of the P0-1 fix. It replaced `contextTokens` + `contextTokensEstimated`,
+     * which between them had THREE writing branches (`turnEnd`,
+     * `contextTokensEstimated`, `resetConversation`) fed by two competing
+     * upstreams. Two writers in one synchronous fan-out means the later one wins,
+     * and the later one was the stale `snapshot` carrying the PRE-compaction
+     * figure - so the bar fell and bounced straight back, every time, with nothing
+     * logging a fault. `context-one-writer.test.ts` scans this file to keep it
+     * that way.
+     */
+    context: ContextUsageSnapshot;
     overlay: Overlay;
     thinkingVisible: boolean;
     /** Ephemeral acks; auto-dismissed by App (spec §3.9). */
@@ -408,16 +430,6 @@ export interface ViewState {
      * totals. `null` is what leaves an ordinary session's status bar unchanged.
      */
     compaction: CompactionSnapshot | null;
-    /**
-     * Whether `contextTokens` is currently a DERIVED figure rather than a measured
-     * one (§6.2 / P1-11).
-     *
-     * Set by `compactionEnd`, cleared by the next `turnEnd`. The status bar widens
-     * its leading `~` to cover it: today `~` means "the window is a guess", and
-     * this makes it also mean "the occupancy is a guess". Honesty about a guess is
-     * cheaper than a support thread about a wrong percentage.
-     */
-    contextTokensEstimated: boolean;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
@@ -648,15 +660,17 @@ export type ViewAction = {
     snapshot: CompactionSnapshot;
 }
 /**
- * Overwrite the gauge with a DERIVED occupancy (§6.2).
+ * The occupancy reading, from `AgentController.subscribeContextUsage`.
  *
- * Separate from `compactionEnd` because the value is not always available at
- * the same instant, and because the flag it sets — `contextTokensEstimated` —
- * has to be clearable by the next `turnEnd` independently.
+ * THE ONLY ACTION THAT WRITES `state.context`, AND IT IS DISPATCHED FROM
+ * EXACTLY ONE PLACE (I-1 / T11). It replaced `contextTokensEstimated`, which
+ * `App` fired from two branches of the compaction stream while `turnEnd` wrote
+ * the same field from the agent stream - three writers, two upstreams, one
+ * number, and the P0-1 bounce as the result.
  */
  | {
-    type: 'contextTokensEstimated';
-    tokens: number;
+    type: 'contextUsage';
+    snapshot: ContextUsageSnapshot;
 } | {
     type: 'serviceStart';
     service: ServiceSnapshot;