@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/agent/controller.js

@@ -20,9 +20,15 @@ import { TeamHumanQueue } from '../team/human-queue.js';
 import { createTaskTool } from '../team/task-tool.js';
 import { buildTeamBlock } from '../team/prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
+import { ProcSupervisor } from '../proc/supervisor.js';
+import { buildBackgroundServicesBlock } from '../proc/prompt.js';
+import { PROC_LIMITS } from '../proc/limits.js';
+import { makeBashKill, makeBashOutput } from '../tools/proc-tools.js';
+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';
@@ -33,6 +39,15 @@ import { createNodeSkillHost } from '../skills/node-host.js';
 import { SkillService } from '../skills/service.js';
 import { createSkillTools } from '../skills/tools.js';
 import { buildSystemPrompt } from './system-prompt.js';
+/**
+ * Extra budget, on top of `PROC_LIMITS.killGraceMs`, that `prompt()` allows a
+ * force-stopped engine to unwind in before it starts a new run anyway (I-8).
+ *
+ * `bash`'s own kill grace is what a wedged foreground command costs; this covers
+ * the loop's own unwinding on top of it. Waiting FOREVER is not an option - a
+ * tool that never settles is exactly why rung two exists.
+ */
+const ENGINE_UNWIND_GRACE_MS = 3000;
 /** Approval gate used whenever there is provably no human to ask (headless). */
 export const DENY_ALL_APPROVAL = {
     canPrompt: () => false,
@@ -172,6 +187,65 @@ export class AgentController {
     // to subscribe to the Agent, and this class cannot do both in one step.
     // -----------------------------------------------------------------------
     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
+    // is easy to get wrong (P1-6 / D-9). `cfg.bash.background` gates the SERVICE
+    // half - the `background` tool param, `bash_output`/`bash_kill`, the prompt
+    // block, the status chip - and NEVER the foreground half, because G2 ("bash
+    // always settles") and G3 ("Esc, Esc always works, and the session stays
+    // usable") are promised unconditionally. Gating the whole supervisor on the
+    // flag would make rung two of the Esc ladder a silent no-op for every user who
+    // turned background services off.
+    //
+    // With the flag off it holds foreground pids, nothing else, and allocates no
+    // timers.
+    // -----------------------------------------------------------------------
+    procs;
+    /**
+     * The host's notice channel, kept so `prompt()`'s totality has somewhere to
+     * report to (I-8). Every other consumer reads `deps.notify` through a closure
+     * built in the constructor; this one is called from a method, which is why it
+     * needs a field.
+     */
+    notifyHostFn;
+    /** Whether the SERVICE half is on: tools, prompt block, `background` param. */
+    bashBackgroundRegistered;
+    /** Release the exit reaper. Called by `dispose()`. */
+    releaseSignalHook;
+    /**
+     * Bumped by `forceStop()`; captured by `App` when it subscribes to a run.
+     *
+     * THE VIEW AND THE ENGINE DELIBERATELY DISAGREE AFTER A FORCE-STOP (D-10 /
+     * I-7). Rung two dispatches `runEnd` locally so the composer is usable
+     * immediately, but the engine keeps unwinding and keeps EMITTING -
+     * `turn_start`, `tool_call_start`, `turn_end`, `agent_end` - and
+     * `runStart`/`turnStart` would set `status: 'running'` again, bouncing the
+     * view straight back out of the `idle` the user was just given and appending
+     * entries to a transcript they believe is finished. `App` drops every event
+     * whose generation is stale, which is the same shape as `abortRequested`
+     * above and exists for the same reason: the loop legitimately emits after an
+     * abort lands.
+     */
+    runGen = 0;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -290,6 +364,19 @@ export class AgentController {
         // reason the field's own comment gives: the binding below is spread
         // conditionally on it (§3.1.3 / P1-6).
         this.toolOutputs = config.liveToolOutput ? createToolOutputStore() : null;
+        // ALSO ABOVE `createBuiltinTools`, and UNCONDITIONAL - see the field's own
+        // comment. `readyTimeoutMs` is read through a closure rather than captured,
+        // so a live config change reaches the next service rather than the next
+        // launch of the CLI.
+        this.procs = new ProcSupervisor({ readyTimeoutMs: () => this.config.bash.readyTimeoutMs });
+        this.notifyHostFn = deps.notify;
+        this.bashBackgroundRegistered = config.bash.background;
+        // THE EXIT REAPER (G5 / P1-2 / R-10). An APPEND-ONLY hook rather than a
+        // second `setSignalTerminator`: that is a single slot `cli.tsx` already owns
+        // for the alternate-screen restore, and replacing it is the documented bug
+        // that leaves the user staring at a blank alternate screen. `reapSync` is
+        // the only entry point it calls, and it is synchronous end to end (I-9).
+        this.releaseSignalHook = addSignalHook(() => this.procs.reapSync());
         this.tools = createBuiltinTools({
             getCwd: () => this.cwd,
             // OWNED HERE, NOT IN `cli.tsx` (D-18): `createBuiltinTools` is called from
@@ -306,6 +393,28 @@ export class AgentController {
             ...(this.toolOutputs
                 ? { recordOutput: (id, chunk) => this.emitToolOutput('lead', id, chunk) }
                 : {}),
+            // THE SERVICE HALF, AND ONLY THE SERVICE HALF (P1-6 / I-2). With
+            // `bash.background: false` the options bag has no `procs` key at all, so
+            // `createBuiltinTools` adds no property to `deps`, `bash` gets its default
+            // `{}` second argument, and the tool is the pre-feature one: no
+            // `background` in its schema, the pre-feature description string, no
+            // supervisor call. The FOREGROUND half of `this.procs` is still live, and
+            // `forceStop()` still reaches it.
+            ...(this.bashBackgroundRegistered
+                ? {
+                    procs: this.procs,
+                    // Read LIVE for the reason every other closure in this bag is:
+                    // `aragon config set bash.autoBackground false` must take effect in
+                    // the running session.
+                    autoBackground: () => this.config.bash.autoBackground,
+                    startupSettleMs: () => this.config.bash.startupSettleMs,
+                    // D-15 / P1-8. `planInteractive` is the SAME signal `planTools`
+                    // already uses to decide that no overlay can be rendered, which is
+                    // exactly the question being asked here: can a card be drawn, and is
+                    // there a user who could keep a service alive?
+                    interactive: this.planInteractive,
+                }
+                : {}),
             confirmTools: config.confirmTools,
             // Routed through the same watchdog pause as the plan tools. This is a
             // pre-existing bug being fixed in passing: a `--confirm` user who took
@@ -345,6 +454,12 @@ export class AgentController {
                     }),
                 ]
                 : [],
+            // THROUGH THE FACTORY for the reason `teamTools` records below (P0-2), and
+            // empty when background services were off at construction - which leaves
+            // the array byte-identical to the pre-feature build (I-2).
+            procTools: this.bashBackgroundRegistered
+                ? [makeBashOutput({ supervisor: this.procs }), makeBashKill({ supervisor: this.procs })]
+                : [],
             // THROUGH THE FACTORY, NEVER APPENDED AFTERWARDS (D-15 / P0-1).
             // `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what
             // `createBuiltinTools` produces, so appending `task` here would turn that
@@ -403,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
@@ -420,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({
@@ -470,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
@@ -612,6 +761,12 @@ export class AgentController {
                     review: this.config.fast.review,
                 })
                 : '',
+            // ONE FLAG, unlike team/todo's two: there is no live on/off switch for
+            // background services - `bash.background` is read once at construction,
+            // and the tools it registers cannot be unregistered (the `team.enabled` /
+            // `todo.enabled` rule). So the block is present exactly when the tools are,
+            // and can never advertise a capability the model does not have.
+            backgroundBlock: this.bashBackgroundRegistered ? buildBackgroundServicesBlock() : '',
             // Read from the FIELD on every rebuild, for the reason the field's own
             // comment gives. Empty everywhere but `aragon exec`, and `buildSystemPrompt`
             // splices it conditionally, so every existing prompt is byte-identical.
@@ -700,7 +855,64 @@ export class AgentController {
      * underlying promise so headless mode can await completion. `agent.prompt()`
      * never rejects, so callers must not treat resolution as success.
      */
-    prompt(text) {
+    async prompt(text) {
+        // I-8 - THIS METHOD NEVER REJECTS, AND THAT HAS TO BE A PROPERTY OF THE
+        // METHOD RATHER THAN A COMMENT ABOVE IT (P0-1).
+        //
+        // `App` calls this as `void controller.prompt(...)`, and
+        // `logging/install.ts` routes an `unhandledRejection` into `handleFatal`,
+        // which EXITS THE PROCESS. `Agent.prompt()` throws SYNCHRONOUSLY while
+        // `Agent.running` is true - so before the force-stop ladder existed this was
+        // merely nearly-true (the view was only ever idle when the engine was), and
+        // rung two makes the view idle while the engine is still unwinding. Without
+        // the wait and the guard below, "Esc, Esc, then type" would kill the CLI on
+        // the very screen this feature exists to rescue.
+        //
+        // TWO PARTS, BOTH REQUIRED. First WAIT the engine out, bounded, so the
+        // common case (the engine unwinds in a few hundred ms) starts a real run
+        // rather than reporting a failure. Then swallow anything that still escapes
+        // and surface it through the existing notify channel, because a message that
+        // cannot be started must produce a visible sentence - never a crash, and
+        // never silence.
+        if (this.agent.state.isRunning) {
+            this.abort();
+            await this.waitForEngineIdle();
+        }
+        try {
+            await this.startPrompt(text);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            getLogger().warn('agent', 'prompt_failed', { reason });
+            this.notifyHostFn?.('error', `Could not start the run: ${reason}`);
+        }
+    }
+    /**
+     * Wait for the engine to unwind, bounded.
+     *
+     * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
+     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * alone would hang here for as long as it hangs there. The budget is the two
+     * graces a wedged `bash` can legitimately spend, plus the executor's own.
+     */
+    waitForEngineIdle() {
+        const budget = PROC_LIMITS.killGraceMs + ENGINE_UNWIND_GRACE_MS;
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(finish, budget);
+            timer.unref?.();
+            void this.agent.waitForIdle().then(finish, finish);
+        });
+    }
+    /** The pre-round body of `prompt`, unchanged apart from being private. */
+    startPrompt(text) {
         // A new user message is a new intent, so the previous turn's tool ceiling
         // expires here and anything a slash command queued is promoted (D-G1 / D-G2).
         // This and `steer()` below are the ONLY two places a user message enters the
@@ -746,6 +958,115 @@ export class AgentController {
         // `App.tsx` records for `cancelPendingHuman()` on `agent_end`.
         this.teamRuntime?.abortAll();
     }
+    /**
+     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * (§3.6 / G3).
+     *
+     * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
+     *
+     *   1. `abort()` - everything it does today, unchanged.
+     *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
+     *      child. THIS is what actually unblocks a wedged `await tool.execute`;
+     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      precisely the tools that ignore it.
+     *   3. `runGen += 1` - so `App` can drop the events the engine will keep
+     *      emitting while it unwinds (I-7). Without it the view bounces straight
+     *      back out of the `idle` the user was just given.
+     *   4. IT DOES NOT TOUCH BACKGROUND SERVICES. `Esc` interrupts the AGENT;
+     *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
+     *      sentences and it is exactly the kind of thing a later reader will
+     *      "fix" by making this kill everything - which would mean a user who
+     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      had been working against for an hour. It is invariant I-4.
+     *
+     * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always
+     * constructed; with services off its foreground registry is all there is, and
+     * that is the half this method uses.
+     */
+    forceStop() {
+        this.abort();
+        const killed = this.procs.killForeground('force');
+        this.runGen += 1;
+        getLogger().info('agent', 'force_stop', { generation: this.runGen, killed });
+    }
+    /**
+     * The current run generation (I-7).
+     *
+     * `App` captures it when it subscribes to a run and drops every engine event
+     * whose generation is stale. Same shape as the `abortRequested` guard the fast
+     * reviewer already uses, and for the same reason: the loop legitimately emits
+     * after an abort lands.
+     */
+    get runGeneration() {
+        return this.runGen;
+    }
+    // -----------------------------------------------------------------------
+    // Background services (background-service-supervision §3.5 / §3.6)
+    // -----------------------------------------------------------------------
+    /** Whether `bash_output` / `bash_kill` are in `this.tools`. Fixed at construction. */
+    isBackgroundRegistered() {
+        return this.bashBackgroundRegistered;
+    }
+    /**
+     * Subscribe to the CLI-local `ProcEvent` stream.
+     *
+     * Returns a live unsubscribe even when services are off, because the
+     * supervisor exists either way - the contract `subscribeTeam` /
+     * `subscribeTodos` / `subscribeFast` / `subscribeToolOutput` already set. With
+     * services off nothing is ever emitted, so an unconditional subscription in
+     * `App` costs one `Set` entry.
+     */
+    subscribeProc(listener) {
+        return this.procs.subscribe(listener);
+    }
+    getServiceSnapshot(id) {
+        return this.procs.get(id);
+    }
+    listServices() {
+        return this.procs.list();
+    }
+    /** `starting | ready | running`. Drives the status chip and the Ctrl+C rung. */
+    liveServiceCount() {
+        return this.procs.liveCount();
+    }
+    readServiceLog(id, since) {
+        return this.procs.read(id, since);
+    }
+    /**
+     * Stop one service, or every service when `id` is `'all'`.
+     *
+     * The GRACEFUL ladder (`SIGTERM` -> `SIGKILL` after `stopGraceMs`), because
+     * this path has a live event loop to run it on. `reapServicesSync` is the
+     * other one, and it is the only one an exit path may use.
+     */
+    stopService(id) {
+        return this.procs.stop(id);
+    }
+    /**
+     * Rung one of `Ctrl+C`: stop every live service (§3.6 / G4).
+     *
+     * `force: true` means `reapSync()` SEMANTICS - immediate `SIGKILL`, no
+     * `stopGraceMs` - and is what `doExit` uses, because `doExit` awaits nothing
+     * and must not start (§3.6 step 3). The graceful ladder belongs to `Ctrl+C`,
+     * `bash_kill` and `/bg stop`.
+     */
+    stopAllServices(opts = {}) {
+        if (opts.force) {
+            this.procs.reapSync();
+            return Promise.resolve(this.procs.list());
+        }
+        return this.procs.stop('all');
+    }
+    /**
+     * The synchronous reaper (I-9).
+     *
+     * Exposed so `doExit` can call it without awaiting anything. It is also what
+     * the signal hook registered in the constructor calls, and it is idempotent -
+     * which it has to be, since a normal quit reaches it twice.
+     */
+    reapServicesSync() {
+        this.procs.reapSync();
+    }
     steer(text) {
         // Mid-run interjection: promote the queue, keep what is already in force
         // (D-G3). Clearing here would make "ask a follow-up" the way around the
@@ -938,6 +1259,12 @@ 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();
+        this.releaseSignalHook();
+        this.procs.dispose();
     }
     // -----------------------------------------------------------------------
     // Todo planning (todo-plan-execution §3.6a)
@@ -1063,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 };
@@ -1161,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();
@@ -1181,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;
@@ -1297,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
     // -----------------------------------------------------------------------