@aragon-agent/cli 0.6.4 → 0.6.8

package/dist/agent/reducer.js

@@ -11,11 +11,25 @@
  *     synthesizes a generic error notice (a swallowed throw is never a no-op).
  */
 import process from 'node:process';
-import { occupiedTokens } from '../compaction/pressure.js';
-import { computeCost } from './usage.js';
+import { emptyContextUsage } from '../compaction/meter.js';
+import { addUsage, computeCost } from './usage.js';
 import { ENTRY_LIMITS, appendBounded, entryRetain, trimEntries } from './entry-limits.js';
 /** Default auto-dismiss window for a toast. */
 export const DEFAULT_TOAST_TTL_MS = 2500;
+/**
+ * The zero session total.
+ *
+ * ONE LITERAL FOR TWO SITES (`initialViewState` and `resetConversation`). They
+ * used to spell the object out twice, which is how `cacheReadTokens` would have
+ * been added to one of them and not the other.
+ */
+const EMPTY_USAGE_TOTAL = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costUsd: 0,
+};
 /**
  * The initial view state, optionally seeded from config.
  *
@@ -33,8 +47,8 @@ export function initialViewState(seed = {}) {
     return {
         entries: [],
         status: 'idle',
-        usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
-        contextTokens: 0,
+        usageTotal: EMPTY_USAGE_TOTAL,
+        context: emptyContextUsage(),
         overlay: null,
         thinkingVisible: seed.thinkingVisible ?? false,
         toasts: [],
@@ -48,7 +62,6 @@ export function initialViewState(seed = {}) {
         retry: null,
         fast: null,
         compaction: null,
-        contextTokensEstimated: false,
         seq: 0,
         teamEntryId: undefined,
         todoEntryId: undefined,
@@ -610,22 +623,12 @@ export function viewReducer(state, action) {
                 ...state,
                 streamingId: undefined,
                 turnProduced: true,
-                // ONE FUNCTION, SHARED WITH THE COMPACTION TRIGGER (§3.4.1 / R-11 /
-                // AC-3). The old expression — `inputTokens + outputTokens` — silently
-                // UNDER-reports for anyone behind a caching gateway, because Anthropic
-                // reports `input_tokens` EXCLUDING cached tokens and puts them in two
-                // separate fields. That was a live defect in the number this gauge shows;
-                // it becomes a much worse one the moment a trigger fires on a different
-                // number from the one the user is watching.
-                contextTokens: occupiedTokens(action.usage),
-                // A MEASUREMENT SUPERSEDES A DERIVATION (§6.2). `compactionEnd` writes an
-                // estimate so the bar falls immediately; this is where it stops being one.
-                contextTokensEstimated: false,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
+                // `contextTokens` IS NOT WRITTEN HERE ANY MORE (I-1). The occupancy this
+                // turn produced reaches the view through `ContextMeter`, which subscribes
+                // to the same `turn_end` and publishes the measured pressure - window,
+                // percentage and approximation markers included, none of which this
+                // branch ever had. Two branches writing one number is what P0-1 was.
+                usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta),
                 // The turn produced an answer, so whatever it had to retry, it recovered.
                 ...settleRetryCard(state, entries, 'recovered'),
             };
@@ -763,8 +766,13 @@ export function viewReducer(state, action) {
                 droppedEntries: 0,
                 streamingId: undefined,
                 expandedToolIds: {},
-                contextTokens: 0,
-                usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
+                // `context` IS DELIBERATELY UNTOUCHED (I-1). `builtins.ts` calls
+                // `controller.clearMessages()` BEFORE dispatching this, and that marks
+                // the meter dirty and schedules a publication; zeroing here would make
+                // the final state `0` rather than the meter's real answer - which for an
+                // emptied conversation is the system prompt's own couple of percent, not
+                // nothing. `usageTotal` DOES reset: that is session spend, not occupancy.
+                usageTotal: EMPTY_USAGE_TOTAL,
                 teamEntryId: undefined,
                 // `/reset` clears `messages`, so the belief is gone and the list goes
                 // with it — the other half of I-2. `controller.clearMessages()` clears
@@ -774,10 +782,6 @@ export function viewReducer(state, action) {
                 retryEntryId: undefined,
                 retry: null,
                 compactionEntryId: undefined,
-                // `contextTokens` is zeroed above, so the flag that says it is a
-                // DERIVATION has to go with it — otherwise a fresh conversation renders
-                // `~0%` and the tilde is a lie about a number that is simply zero.
-                contextTokensEstimated: false,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
@@ -860,18 +864,11 @@ export function viewReducer(state, action) {
         }
         case 'teamUsage':
             // `usageTotal` AND NOTHING ELSE (§3.9 / AC-15). In particular NOT
-            // `contextTokens`: that gauge shows the LEAD's context occupancy against
+            // `context`: that gauge shows the LEAD's context occupancy against
             // the model's window, and folding five children into it would read 180%
             // on a perfectly healthy session. Child spend is real money and has to
             // appear in the cost readout; it is not the lead's context.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'teamEnd': {
             const { outcome } = action;
             const entries = state.teamEntryId
@@ -991,17 +988,10 @@ export function viewReducer(state, action) {
         }
         case 'fastUsage':
             // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` (§3.6 / AC-18). In
-            // particular NOT `contextTokens`: that gauge shows the LEAD's context
+            // particular NOT `context`: that gauge shows the LEAD's context
             // occupancy against the lead model's window, and a review is a separate
             // conversation with a different model entirely.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'fastTier':
             return { ...state, fast: action.snapshot };
         // --- Context compaction (context-auto-compaction §5.5) ----------------
@@ -1128,40 +1118,41 @@ export function viewReducer(state, action) {
         }
         case 'compactionUsage':
             // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` and `fastUsage`. In
-            // particular NOT `contextTokens`: that gauge shows the LEAD's context
+            // particular NOT `context`: that gauge shows the LEAD's context
             // occupancy against the lead model's window, and a summarization is a
             // separate conversation with a possibly different model entirely.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'compactionSnapshot':
             return { ...state, compaction: action.snapshot };
         /**
-         * THE GAUGE MUST FALL IMMEDIATELY (§6.2 / AC-5).
+         * THE ONE WRITER OF `state.context` (I-1).
          *
-         * `contextTokens` is otherwise only written at `turnEnd`, so a compaction
-         * that took the session from 92 % to 24 % would leave the bar at 92 % until
-         * the next turn completes — and the user would reasonably conclude that
-         * nothing happened. This is a small change and it is the difference between
-         * the feature feeling real and feeling broken.
+         * THE IDENTITY SHORT-CIRCUIT BELOW IS LOAD-BEARING, NOT A MICRO-OPTIMISATION
+         * (§5.2 / R-3). The meter publishes on a 400 ms tick throughout a turn and
+         * most of those ticks measure the same number - the history did not change
+         * between two tool calls of the same size, or the percentage rounded to the
+         * same integer. Returning the SAME state object lets React skip the whole
+         * subtree; returning a fresh one would make a permanently visible row into a
+         * 2.5 Hz re-render source and walk the render governor up its ladder for no
+         * visible change at all.
          *
-         * The value arrives ALREADY CALIBRATED from `App` (§6.2 / P1-11): it replaces
-         * a MEASUREMENT that included the tool schemas, and core's raw estimator
-         * never counts them, so writing the raw figure would make the bar fall too
-         * far and then visibly climb again on the next `turn_end` for no reason the
-         * user can see.
+         * `ContextUsageSnapshot` carries no timestamp for exactly this reason: a
+         * field that moves every tick would make this comparison never hold.
          */
-        case 'contextTokensEstimated':
-            return {
-                ...state,
-                contextTokens: Math.max(0, Math.round(action.tokens)),
-                contextTokensEstimated: true,
-            };
+        case 'contextUsage': {
+            const prev = state.context;
+            const next = action.snapshot;
+            if (prev.occupied === next.occupied &&
+                prev.window === next.window &&
+                prev.pct === next.pct &&
+                prev.source === next.source &&
+                prev.deltaTokens === next.deltaTokens &&
+                prev.windowKnown === next.windowKnown &&
+                prev.windowOverridden === next.windowOverridden) {
+                return state;
+            }
+            return { ...state, context: next };
+        }
         // --- API retry (llm-api-retry-backoff §6.4) ---------------------------
         case 'retryScheduled': {
             const snapshot = {

package/dist/agent/usage.d.ts

@@ -3,8 +3,42 @@
  * (which is expressed in USD per 1M tokens). See spec §6.2 status bar.
  */
 import type { ModelCost, TokenUsage } from '@aragon-agent/core';
+import type { UsageTotal } from './reducer.js';
 /** Compute the USD cost of a single `TokenUsage` given a model's cost table. */
 export declare function computeCost(usage: TokenUsage, cost?: ModelCost): number;
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export declare function addUsage(total: UsageTotal, usage: TokenUsage, costDelta: number): UsageTotal;
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export declare function promptTokensOf(total: UsageTotal): number;
 /** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
 export declare function formatCost(usd: number): string;
 /** Format a token count compactly (`1.2k`, `3.4M`). */

package/dist/agent/usage.js

@@ -12,6 +12,49 @@ export function computeCost(usage, cost) {
         perM(usage.cacheReadTokens ?? 0, cost.cacheRead) +
         perM(usage.cacheWriteTokens ?? 0, cost.cacheWrite));
 }
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export function addUsage(total, usage, costDelta) {
+    return {
+        inputTokens: total.inputTokens + usage.inputTokens,
+        outputTokens: total.outputTokens + usage.outputTokens,
+        cacheReadTokens: total.cacheReadTokens + (usage.cacheReadTokens ?? 0),
+        cacheWriteTokens: total.cacheWriteTokens + (usage.cacheWriteTokens ?? 0),
+        costUsd: total.costUsd + costDelta,
+    };
+}
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export function promptTokensOf(total) {
+    return total.inputTokens + total.cacheReadTokens + total.cacheWriteTokens;
+}
 /** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
 export function formatCost(usd) {
     if (usd <= 0)

package/dist/cli.js

@@ -27,7 +27,7 @@ import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS,
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampContextWindow, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, isAutoToken, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -45,6 +45,9 @@ import { createFrameDiffer } from './ui/frame-differ.js';
 import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
 import { setFrameStatsProvider } from './commands/perf.js';
 import { tryCreateStdinFilter } from './input/stdin-filter.js';
+import { createScrollbarBridge } from './ui/scrollbar-controller.js';
+import { createPointerRouter } from './input/pointer-router.js';
+import { createFrameObserver } from './ui/frame-observer.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { supportsWindowsVtInput } from './ui/win-vt-input.js';
 import { forceWindowsVtInput } from './ui/win-vt-force.js';
@@ -153,6 +156,11 @@ function toFlags(opts) {
         fastModel: opts.fastModel,
         fastProvider: opts.fastProvider,
         fastReview: opts.fastReview,
+        // …and again for `--fast-delegate` / `--no-fast-delegate`, one feature
+        // later — NINE features, one trap. It is `fast.delegate`'s only channel:
+        // there is no `ARAGON_FAST_DELEGATE`, so missing this line leaves a wrapper
+        // with no way at all to say "do not delegate on this run".
+        fastDelegate: opts.fastDelegate,
         // `--verbose` is just a shorthand for `--log-level debug`; an explicit
         // `--log-level` still wins, so the two can be combined without surprise.
         logLevel: opts.logLevel ?? (opts.verbose ? 'debug' : undefined),
@@ -471,13 +479,14 @@ function runInteractive(flags, extras = {}) {
     const disposeStdinFilter = () => filter?.dispose();
     // --- Drag-select (tui-selection-and-scroll-follow §4.4). ------------------
     //
-    // ONE EXPRESSION, READ BY FOUR THINGS, and that is the same discipline
-    // `wantMouse` above follows for the same reason: the `?1002h` write, the
-    // controller, the differ's `decorate` hook and the startup notice must never
-    // disagree about whether drag-select is running. With it false the session is
-    // byte-identical to a pre-feature build — no extra escape on the wire (AC-8),
-    // no controller, no `decorate`, no mirror.
+    // Selection owns its controller, decoration and notice. Button motion follows
+    // mouseOn independently so --no-mouse-select still permits scrollbar dragging.
     const wantSelect = mouseOn && config.mouseSelect;
+    let mouseCaptured = mouseOn;
+    const scrollbar = createScrollbarBridge(() => mouseCaptured);
+    const pointerRouter = mouseOn && filter ? createPointerRouter({
+        source: filter.source, handle: (event) => scrollbar.controller?.handle(event) ?? false,
+    }) : null;
     const selectionBridge = {
         controller: null,
         onCopied: null,
@@ -530,7 +539,13 @@ function runInteractive(flags, extras = {}) {
     // than printing zeroes that read like a writer doing nothing (§5.4).
     if (frameWriter)
         setFrameStatsProvider(frameWriter.stats);
+    const frameObserver = mode === 'fullscreen' ? createFrameObserver({
+        stdout: frameWriter?.stdout ?? process.stdout, terminal: process.stdout, scrollbar,
+    }) : null;
     const disposeFrameWriter = () => {
+        frameObserver?.dispose();
+        pointerRouter?.dispose();
+        scrollbar.controller?.dispose();
         if (!frameWriter)
             return;
         setFrameStatsProvider(null);
@@ -569,7 +584,7 @@ function runInteractive(flags, extras = {}) {
         // keep their terminal's own selection.
         screen = enterAltScreen(process.stdout, {
             mouse: mouseOn,
-            motion: wantSelect,
+            motion: mouseOn,
             bracketedPaste: pasteOn && mode === 'fullscreen',
         });
         const restore = () => screen?.restore();
@@ -632,7 +647,7 @@ function runInteractive(flags, extras = {}) {
     // attempted. Naming the mechanism honestly is the entire reason that return
     // value exists (R-7), and a door that lies is worse than no door.
     const writeForeign = frameWriter
-        ? (text) => frameWriter.writeForeign(text)
+        ? (text) => { frameObserver?.invalidate(); frameWriter.writeForeign(text); }
         : process.stdout.isTTY
             ? (text) => {
                 try {
@@ -654,10 +669,9 @@ function runInteractive(flags, extras = {}) {
     // than inside `screen.ts`'s closure because `App` needs to READ it and the
     // handle's own flag is private (it has to be — `restore()` reads it, and
     // exposing a setter would be a second way to get the two out of step).
-    let mouseCaptured = mouseOn;
     if (wantSelect && filter) {
         selectionBridge.controller = createSelectionController({
-            source: filter.source,
+            source: pointerRouter?.selectionSource ?? filter.source,
             // The frame writer is absent under `--no-diff-render`, where there is no
             // cache to repaint from at all; the controller then falls back to asking
             // `App` for a React redraw on every drag flush, which is slower and
@@ -697,11 +711,14 @@ function runInteractive(flags, extras = {}) {
     const terminalBridge = mode === 'fullscreen' || writeForeign
         ? {
             mouseSelect: wantSelect,
+            ...(mode === 'fullscreen' ? { scrollbar } : {}),
             ...(mouseOn
                 ? {
                     setMouseCapture: (on) => {
                         screen?.setMouseCapture(on);
                         mouseCaptured = on;
+                        if (!on)
+                            scrollbar.controller?.cancel();
                         // A released mouse cannot be dragging, and a selection left
                         // painted over a screen the terminal is now selecting on its
                         // own would be two highlights claiming the same rows.
@@ -719,41 +736,67 @@ function runInteractive(flags, extras = {}) {
         : undefined;
     const updateBridge = { service: null, onAttach: null };
     let updateService = null;
+    let interactiveClosed = false;
+    const failInteractive = (error) => {
+        // Ink consumes render exceptions; retain failure even if a disposer throws.
+        process.exitCode = 1;
+        interactiveClosed = true;
+        logger.error('cli', 'render_failed', { error: String(error) });
+        for (const cleanup of [
+            () => screen?.restore(), disposeSelection, disposeStdinFilter, disposeFrameWriter,
+            () => controller.abort(), () => controller.dispose(), () => updateService?.dispose(),
+            () => { process.stdin.pause(); process.stdin.unref?.(); },
+        ]) {
+            try {
+                cleanup();
+            }
+            catch (cleanupError) {
+                logger.error('cli', 'render_cleanup_failed', { error: String(cleanupError) });
+            }
+        }
+    };
     const updateEligible = !!process.stdout.isTTY &&
         !!process.stdin.isTTY &&
         !process.env.CI &&
         config.update.mode !== 'off';
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, 
-        // `mouseOn`, NOT the handle (I-11). `App.tsx:186-188` documents this
-        // prop's contract as "absent under `--no-mouse`, inline, or non-TTY", and
-        // it feeds `enabled: !!mouseSource` on a wheel subscription that would
-        // otherwise be a channel no event can ever arrive on.
-        mouseSource: mouseOn && filter ? filter.source : undefined, 
-        // Present ONLY when this console swallows `CSI Z` and mouse reports.
-        // Passed in rather than probed inside `App` so that every test renders
-        // the same tree on every machine — reading `process.versions.node` from
-        // a component would make the notice appear or vanish according to which
-        // Node the developer happened to have installed.
-        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, 
-        // Absent when nothing can refuse a paste, so a `--no-paste` tree is
-        // byte-identical to a build without this feature.
-        pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge }), 
-    // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
-    // straight to stdout and permanently shifts the fixed frame's accounting.
-    {
-        exitOnCtrlC: false,
-        patchConsole: mode === 'inline',
-        // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
-        // every existing path is provably unchanged.
-        stdin: filter?.stdin ?? process.stdin,
-        // SPREAD, not `frameWriter?.stdout ?? process.stdout`. This call passed no
-        // `stdout` at all before, and Ink defaults it to `process.stdout`; omitting
-        // the key entirely when the writer is off keeps the options object the same
-        // SHAPE it has always had, which is what makes AC-5 / AC-6 ("byte-identical
-        // with --no-diff-render, inline mode and `aragon -p`") a statement about
-        // the code rather than about Ink's defaulting.
-        ...(frameWriter ? { stdout: frameWriter.stdout } : {}),
-    });
+    let instance;
+    try {
+        instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, 
+            // `mouseOn`, NOT the handle (I-11). `App.tsx:186-188` documents this
+            // prop's contract as "absent under `--no-mouse`, inline, or non-TTY", and
+            // it feeds `enabled: !!mouseSource` on a wheel subscription that would
+            // otherwise be a channel no event can ever arrive on.
+            mouseSource: mouseOn && filter ? filter.source : undefined, 
+            // Present ONLY when this console swallows `CSI Z` and mouse reports.
+            // Passed in rather than probed inside `App` so that every test renders
+            // the same tree on every machine — reading `process.versions.node` from
+            // a component would make the notice appear or vanish according to which
+            // Node the developer happened to have installed.
+            vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, 
+            // Absent when nothing can refuse a paste, so a `--no-paste` tree is
+            // byte-identical to a build without this feature.
+            pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge }), 
+        // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
+        // straight to stdout and permanently shifts the fixed frame's accounting.
+        {
+            exitOnCtrlC: false,
+            patchConsole: mode === 'inline',
+            // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
+            // every existing path is provably unchanged.
+            stdin: filter?.stdin ?? process.stdin,
+            // SPREAD, not `frameWriter?.stdout ?? process.stdout`. This call passed no
+            // `stdout` at all before, and Ink defaults it to `process.stdout`; omitting
+            // the key entirely when the writer is off keeps the options object the same
+            // SHAPE it has always had, which is what makes AC-5 / AC-6 ("byte-identical
+            // with --no-diff-render, inline mode and `aragon -p`") a statement about
+            // the code rather than about Ink's defaulting.
+            ...(frameObserver ? { stdout: frameObserver.stdout } : {}),
+        });
+    }
+    catch (error) {
+        failInteractive(error);
+        throw error;
+    }
     // H1's primary disarm, and this is the earliest moment at which "this build
     // STARTS" is proven: the module graph loaded, config resolved, Ink mounted
     // (cli-auto-update-hardening section 5.1.4). It is what makes a long session
@@ -775,6 +818,8 @@ function runInteractive(flags, extras = {}) {
         // must degrade to "no updater", never to a crashed TUI.
         void import('./update/service.js')
             .then(({ UpdateService }) => {
+            if (interactiveClosed)
+                return;
             const service = new UpdateService({ config: config.update, currentVersion: VERSION });
             updateService = service;
             updateBridge.service = service;
@@ -805,6 +850,7 @@ function runInteractive(flags, extras = {}) {
     void instance
         .waitUntilExit()
         .then(() => {
+        interactiveClosed = true;
         screen?.restore();
         // BEFORE `disposeStdinFilter()`, which clears the listener set it subscribed to,
         // and after `restore()` for the reason that call records: the terminal must
@@ -833,18 +879,7 @@ function runInteractive(flags, extras = {}) {
         updateService?.dispose();
         replayTranscript();
     })
-        .catch(() => {
-        screen?.restore();
-        // BEFORE `disposeStdinFilter()`, which clears the listener set it subscribed to,
-        // and after `restore()` for the reason that call records: the terminal must
-        // stop reporting first, and anything already in flight is still consumed by
-        // a live filter.
-        disposeSelection();
-        disposeStdinFilter();
-        disposeFrameWriter();
-        controller.dispose();
-        updateService?.dispose();
-    });
+        .catch(failInteractive);
 }
 async function runOneShot(flags, prompt, quiet) {
     // Headless: no App is ever rendered, so there is no human to approve a skill
@@ -924,6 +959,11 @@ const CONFIG_SET_KEYS = new Set([
     'baseUrl',
     'thinkingLevel',
     'maxTokens',
+    // context-usage-gauge-accuracy §3.6. Listed here AND given its own branch in
+    // `runConfigSet` below - a key present here but absent there falls through
+    // every case, writes nothing, and still prints `Set contextWindow = 1000000`
+    // (P1-2).
+    'contextWindow',
     'theme',
     'confirmTools',
     'toolTimeoutMs',
@@ -1020,6 +1060,30 @@ function runConfigSetMaxTokens(value) {
     const merged = updatePersistedConfig({ maxTokens: stored });
     process.stdout.write(`Set maxTokens = ${merged.maxTokens ?? 'auto'}\n`);
 }
+/**
+ * `aragon config set contextWindow <n|auto>`.
+ *
+ * ITS OWN BRANCH, AHEAD OF THE SWITCH, for the reason `maxTokens` has one: it
+ * must echo the STORED value rather than the typed one, so
+ * `config set contextWindow 99999999` reports the clamped 5000000 instead of a
+ * number that was never written. It also REJECTS nonsense rather than clamping
+ * it - a non-numeric argument here is almost always a typo for a number, and
+ * storing AUTO for `20O000` would quietly discard the user's intent.
+ */
+function runConfigSetContextWindow(value) {
+    const trimmed = value.trim();
+    const auto = isAutoToken(trimmed);
+    if (!auto && !/^\d+$/.test(trimmed)) {
+        process.stderr.write(`Invalid contextWindow "${value}". Use a number of tokens or "auto".\n`);
+        process.exitCode = 2;
+        return;
+    }
+    // `null` GOES IN UNCLAMPED (RV-12). Running AUTO through the clamp yields
+    // 8000 and removes "auto" from the config permanently.
+    const stored = auto ? null : clampContextWindow(trimmed, null);
+    const merged = updatePersistedConfig({ contextWindow: stored });
+    process.stdout.write(`Set contextWindow = ${merged.contextWindow ?? 'auto'}\n`);
+}
 function runConfigSet(key, value) {
     if (!CONFIG_SET_KEYS.has(key)) {
         process.stderr.write(`Unknown config key "${key}". Known keys: ${[...CONFIG_SET_KEYS].join(', ')}.\n`);
@@ -1040,6 +1104,11 @@ function runConfigSet(key, value) {
         runConfigSetMaxTokens(value);
         return;
     }
+    // The second tri-state key, and it needs its own branch for the same reason.
+    if (key === 'contextWindow') {
+        runConfigSetContextWindow(value);
+        return;
+    }
     const teamPatch = applyTeamConfigSet(key, value);
     if (teamPatch) {
         // The written value is echoed from the CLAMPED result rather than from the
@@ -1491,6 +1560,14 @@ function buildProgram() {
         .option('--fast-model <id>', 'The fast model id (implies nothing about --fast)')
         .option('--fast-provider <id>', 'Provider for the fast model (default: the main provider)')
         .option('--fast-review <n|off>', 'Turns between automatic fast reviews, or "off"')
+        // BOTH FORMS, POSITIVE FIRST, and here it matters more than anywhere above:
+        // `fast.delegate` is PERSISTED and defaults to TRUE, so declaring only
+        // `--no-fast-delegate` would make commander default `opts.fastDelegate` to
+        // `true` and force `delegate: true` on EVERY run that passed no flag at all
+        // — silently overwriting a user's stored `false`. Same polarity, same trap
+        // and same fix as `--update` / `--compaction`.
+        .option('--fast-delegate', 'Let the fast tier take mechanical sub-steps (the default)')
+        .option('--no-fast-delegate', 'Run every sub-step on the main model')
         // BOTH FORMS, positive first, for the reason recorded seven times above —
         // and this is the pair whose omission would be worst. `update.mode` is
         // PERSISTED and defaults to `'auto'`, so a lone `--no-update` would make