@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/agent/controller.js

@@ -9,19 +9,25 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
-import { clampTeamConfig, clampTodoConfig, isAdapterProvider } from '../config/schema.js';
+import { clampFastConfig, clampRetryConfig, clampTeamConfig, clampTodoConfig, isAdapterProvider, toRetryPolicy, } from '../config/schema.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { createBuiltinTools } from '../tools/index.js';
+import { createFileChangeStore } from '../tools/file-change-store.js';
+import { createToolOutputStore, } from '../tools/tool-output-store.js';
 import { TeamRuntime } from '../team/runtime.js';
 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 { describeFastTierProblem, fastProviderOf, resolveFastTier } from '../fast/resolve.js';
+import { FastWiring, offFastStatus } from '../fast/wiring.js';
 import { TodoStore } from '../todo/store.js';
 import { createTodoTool } from '../todo/todo-tool.js';
 import { buildTodoBlock } from '../todo/prompt.js';
 import { createPlanTools } from '../tools/plan-tools.js';
 import { DENY_ALL_HUMAN_INPUT } from '../tools/human-input.js';
+import { getLogger } from '../logging/logger.js';
 import { createNodeSkillHost } from '../skills/node-host.js';
 import { SkillService } from '../skills/service.js';
 import { createSkillTools } from '../skills/tools.js';
@@ -94,13 +100,67 @@ export class AgentController {
     todos;
     /** Static: whether this session could ever render the rail. See the dep. */
     todoPanelCapable;
+    /**
+     * Structured file diffs on their way to the UI (agent-activity-presentation
+     * §3.3.5). A bounded, take-once ring; see `file-change-store.ts` for why each
+     * of those three words is load-bearing.
+     *
+     * DECLARED WITH AN INITIALIZER, so it exists before `createBuiltinTools` runs
+     * in the constructor body and the recorder closure it hands over is valid from
+     * the first tool call.
+     */
+    fileChanges = createFileChangeStore();
+    /**
+     * A running tool's output on its way to the UI
+     * (agent-activity-presentation-live §3.1.3).
+     *
+     * NULL WHEN THE FEATURE IS OFF (P1-6). `fileChanges` next door is declared
+     * with an initializer because it is unconditional; this one cannot be, since a
+     * field initializer cannot read a constructor parameter -- and an
+     * unconditional initializer would allocate on every construction and make
+     * AC-31's "no store is allocated" false by construction. `private readonly
+     * fast: FastWiring | null` below is the same declaration shape in the same
+     * class.
+     *
+     * ASSIGNED IN THE CONSTRUCTOR BODY, ABOVE THE `createBuiltinTools` CALL, not
+     * near `this.fast` which runs after it. The binding there is spread
+     * CONDITIONALLY on this field, so an assignment placed after the call would
+     * read `undefined`, add no property, and produce a build in which the feature
+     * is silently off with the key on.
+     */
+    toolOutputs;
+    outputListeners = new Set();
+    // -----------------------------------------------------------------------
+    // Fast model tier (fast-model-tier §3.1 / §3.3)
+    //
+    // ONE FIELD AND FOUR THIN FORWARDERS. The flag pair, the tier cache, the
+    // reviewer's lifetime and the `resolveTier` closure all live in
+    // `fast/wiring.ts`, which is a BUDGET decision rather than an aesthetic one
+    // (C-12 / RV-5): `CLAUDE.md` caps a source file at 1000 lines and this one had
+    // 40 to spare when the design was written.
+    //
+    // `null` when the tier could not be resolved at construction, which is the
+    // byte-identity branch: no reviewer is subscribed, `task` carries no `model`
+    // property, and `<fast_tier>` is never spliced (I-2).
+    // -----------------------------------------------------------------------
+    fast;
+    /**
+     * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
+     * Cleared at the next `agent_start`.
+     */
+    abortRequested = false;
+    /** User messages queued since the last `turn_start` (§3.5.4a guard 2). */
+    userSteerCount = 0;
     constructor(config, deps = {}) {
         this.config = config;
         this.cwd = config.cwd;
         const humanInput = deps.humanInput ?? DENY_ALL_HUMAN_INPUT;
         this.planInteractive = humanInput.neverPrompts !== true;
         this.effectiveMode = config.startInPlanMode ? 'plan' : 'build';
-        this.providerRegistry = initProviders();
+        // The retry policy is installed HERE and replaced live by `setRetryConfig`
+        // (llm-api-retry-backoff §6.3). Subagents inherit it for free: `TeamRuntime`
+        // reuses this very registry instance.
+        this.providerRegistry = initProviders({ retryPolicy: toRetryPolicy(config.retry) });
         this.modelRegistry = new ModelRegistry(this.providerRegistry);
         this.skillsEnabled = config.skills.enabled;
         this.onSkillsChanged = deps.onSkillsChanged;
@@ -132,12 +192,33 @@ export class AgentController {
         this.todoEnabled = config.todo.enabled;
         this.todoPanelCapable = deps.todoPanelCapable === true;
         this.todos = this.todoRegistered ? new TodoStore() : null;
+        // --- Fast model tier ---------------------------------------------------
+        //
+        // RESOLVED BEFORE THE TOOL ARRAY, because `fastRegistered` decides whether
+        // `task`'s schema carries a `model` property at all and the array is built
+        // ONCE (C-2). `FastWiring` re-runs the same pure function in its own
+        // constructor; the two agree by construction because they read the same
+        // config through the same resolver.
+        const fastTier = resolveFastTier(config, (id) => this.hasApiKey(id));
+        const fastRegistered = fastTier.ok;
         // --- Team mode ---------------------------------------------------------
         this.teamRegistered = config.team.enabled;
         this.teamEnabled = config.team.enabled;
         this.teamRuntime = this.teamRegistered
             ? new TeamRuntime({
                 getConfig: () => this.config,
+                // Read LIVE through the wiring, which does not exist yet — the closure
+                // is only ever called from inside a dispatch, long after construction.
+                resolveTier: (tier) => this.fast
+                    ? this.fast.resolveTier(tier)
+                    : {
+                        ref: {
+                            providerId: this.config.provider,
+                            modelId: this.config.model,
+                            ...(this.config.baseUrl ? { baseUrl: this.config.baseUrl } : {}),
+                        },
+                        thinkingLevel: this.config.thinkingLevel,
+                    },
                 providerRegistry: this.providerRegistry,
                 getCwd: () => this.cwd,
                 getMode: () => this.effectiveMode,
@@ -166,8 +247,26 @@ export class AgentController {
                 ...(confirm ? { humanQueue: new TeamHumanQueue(confirm) } : {}),
             })
             : null;
+        // ABOVE `createBuiltinTools`, and the ordering is load-bearing for the
+        // 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;
         this.tools = createBuiltinTools({
             getCwd: () => this.cwd,
+            // OWNED HERE, NOT IN `cli.tsx` (D-18): `createBuiltinTools` is called from
+            // this constructor and from `team/subagent.ts`, never from `cli.tsx`, so
+            // this is the one place a recorder can be bound to the toolset that will
+            // use it. Pre-bound to `'lead'`, so `fs-tools.ts` never learns what an
+            // owner is; subagents get no recorder this round (D-13).
+            recordChange: (id, patch) => this.fileChanges.record('lead', id, patch),
+            // The live-output recorder, at the identical site and for the identical
+            // reason, and spread ONLY WHEN THE STORE EXISTS: with `liveToolOutput` off
+            // the options bag has no `recordOutput` property at all, so
+            // `createBuiltinTools`'s conditional spread yields today's `deps` byte for
+            // byte and `bash` is the pre-round tool (AC-31).
+            ...(this.toolOutputs
+                ? { recordOutput: (id, chunk) => this.emitToolOutput('lead', id, chunk) }
+                : {}),
             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
@@ -220,10 +319,23 @@ export class AgentController {
                         runtime: this.teamRuntime,
                         // Read LIVE: `/team off` flips the flag, it cannot unregister.
                         isTeamEnabled: () => this.teamEnabled,
+                        // FROZEN AT CONSTRUCTION (C-2). `/fast on` in a session launched
+                        // without the tier cannot add a schema property, and it says so
+                        // rather than advertising one that is not there.
+                        fastRegistered,
+                        // Read LIVE at dispatch time (RV-3): the tier can stop resolving
+                        // mid-session, and the normalizer and the subagent factory must
+                        // agree about that at the same instant.
+                        fastAvailable: () => this.fast?.delegationAvailable() === true,
                         maxSubagents: () => this.config.team.maxSubagents,
                         hasApiKey: () => this.hasApiKey(),
                         activeProvider: () => this.config.provider,
                         modelCost: () => this.getModelInfo().cost,
+                        fastModelCost: () => {
+                            const ref = this.fast?.fastRef();
+                            return ref ? this.getModelInfoFor(ref).cost : undefined;
+                        },
+                        fastPricingUnknown: () => this.fast?.snapshot().pricingUnknown === true,
                         withPausedWatchdog: (fn) => this.withPausedWatchdog(fn),
                     }),
                 ]
@@ -275,6 +387,71 @@ export class AgentController {
                 },
             },
         });
+        // --- Fast tier, part 2: after the Agent exists --------------------------
+        //
+        // `FastWiring` subscribes to the lead's event stream, so it cannot be built
+        // before the `Agent`. The prompt is therefore composed twice at startup:
+        // once above without `<fast_tier>` (the wiring is still null) and once here.
+        // That is one extra string build at construction and no live path.
+        this.fast = fastRegistered
+            ? new FastWiring({
+                getConfig: () => this.config,
+                hasKey: (id) => this.hasApiKey(id),
+                getApiKey: (id) => this.resolveKey(id),
+                isPricedModel: (ref) => this.isPricedModel(ref),
+                subscribe: (listener) => this.agent.subscribe(listener),
+                complete: (providerId, request) => this.providerRegistry.complete(providerId, request),
+                // THE REVIEWER GOES THROUGH THIS METHOD, NOT `agent.steer()` DIRECTLY,
+                // so its own block is counted alongside the user's — which is what
+                // `userSteerCount` would otherwise mis-report and what would make
+                // guard 2 clear a queue it does not own (D-21).
+                //
+                // It is decremented back out below: the counter must answer "did the
+                // USER queue anything", and the reviewer's own message is not that.
+                steer: (text) => {
+                    this.steer(text);
+                    this.userSteerCount -= 1;
+                },
+                isRunning: () => this.isRunning(),
+                isAbortRequested: () => this.abortRequested,
+                userSteerCount: () => this.userSteerCount,
+                clearAllQueues: () => this.clearAllQueues(),
+                notify: (level, text) => deps.notify?.(level, text),
+                onPromptChanged: () => this.rebuildSystemPrompt(),
+            })
+            : null;
+        // The two guards' bookkeeping, and the only reason this class subscribes to
+        // its own agent. `turn_start` is where a user steer stops being pending;
+        // `agent_start` is where a requested abort stops being in force.
+        this.agent.subscribe((event) => {
+            if (event.type === 'agent_start')
+                this.abortRequested = false;
+            if (event.type === 'turn_start')
+                this.userSteerCount = 0;
+            // The authoritative result arrives with this event, so from this instant
+            // the tail is superseded and its slot must be released (§3.1.1). Clearing
+            // HERE rather than on read is what keeps the store's size a function of
+            // CONCURRENT calls instead of total calls.
+            if (event.type === 'tool_execution_end') {
+                this.toolOutputs?.clear('lead', event.toolCallId);
+            }
+        });
+        if (this.fast) {
+            this.rebuildSystemPrompt();
+            // Fast-tier children are counted from the outcome rather than from the
+            // specs, so a downgraded child is not miscounted as a saving (§3.6).
+            this.teamRuntime?.subscribe((event) => {
+                if (event.type !== 'dispatch_end')
+                    return;
+                this.fast?.noteDelegated(event.outcome.runs.filter((r) => r.tier === 'fast').length);
+            });
+        }
+        // ONE LINE FOR THE TWO CONFIGURATION MISTAKES THAT ARE OTHERWISE INVISIBLE
+        // (§3.3): the tier is on but unnamed, or named against a provider with no
+        // key. Nothing else in the session would ever mention either.
+        const problem = describeFastTierProblem(fastTier, fastProviderOf(config));
+        if (problem)
+            deps.notify?.('warn', problem);
     }
     resolveKey(providerId) {
         return makeGetApiKey(this.config)(providerId);
@@ -324,6 +501,11 @@ export class AgentController {
                 ? buildTeamBlock({
                     maxSubagents: this.config.team.maxSubagents,
                     maxConcurrent: this.config.team.maxConcurrent,
+                    // One cross-reference sentence, present only when the capability
+                    // is (§3.8). `this.fast` is null during the FIRST compose (the
+                    // wiring needs the Agent), which is why the constructor composes
+                    // again once it exists.
+                    fastDelegation: this.fast?.delegationAvailable() === true,
                 })
                 : '',
             // BOTH FLAGS, exactly as team mode uses both, and for the identical
@@ -336,6 +518,17 @@ export class AgentController {
                     panelVisible: this.todoPanelCapable && this.config.todo.panel,
                 })
                 : '',
+            // The SAME two flags one more time, plus the live resolution — all three
+            // live inside `FastWiring.available()` (§3.3). `buildFastBlock` itself
+            // returns `''` when neither capability is on, so a user who turned both
+            // off pays nothing for the tier being technically live.
+            fastBlock: this.fast && this.fast.available()
+                ? buildFastBlock({
+                    model: this.fast.fastRef()?.modelId ?? '',
+                    delegate: this.config.fast.delegate,
+                    review: this.config.fast.review,
+                })
+                : '',
         });
     }
     rebuildSystemPrompt() {
@@ -437,9 +630,21 @@ export class AgentController {
         // an unfinished one survives "continue" / "now do the rest" but not four
         // unrelated turns.
         this.todos?.beginUserTurn();
+        // The fast reviewer is asked whether the run is on track FOR THIS (§3.5.2).
+        // Without it the reviewer judges progress without being told the goal, which
+        // is the one input it cannot reconstruct from the event stream.
+        this.fast?.setGoal(text);
         return this.agent.prompt(text);
     }
     abort() {
+        // SET BEFORE `agent.abort()`, SYNCHRONOUSLY — guard 1 of §3.5.4a. The loop
+        // still emits the batch's final `tool_execution_end` (`agent-loop.ts:249`)
+        // after an Esc lands inside the last tool's `await`, and the reviewer's
+        // listener runs synchronously inside that emit; without this flag it would
+        // see `isRunning() === true`, steer, and strand a critique in a queue
+        // nothing ever clears (RV-1).
+        this.abortRequested = true;
+        this.fast?.abort();
         this.agent.abort();
         // DELIBERATE REDUNDANCY (§3.8). Aborting the lead already aborts the
         // in-flight `task` call's `ctx.signal`, which the runtime listens to — that
@@ -456,6 +661,13 @@ export class AgentController {
         // routes through `steer` whenever the agent happens to be running.
         if (this.skillsEnabled)
             this.skills.absorbPendingFrames();
+        // COUNTED so the reviewer can prove it owns the queue before clearing it
+        // (§3.5.4a guard 2 / D-21). This method is the only other writer of
+        // `steeringQueue` in the package, and `Agent` exposes no way to remove ONE
+        // message — so `userSteerCount === 0` is the only sound licence for
+        // `clearAllQueues()`, and with a user message in there the reviewer must
+        // leave its own residue rather than destroy something the user typed.
+        this.userSteerCount += 1;
         this.agent.steer(text);
     }
     followUp(text) {
@@ -632,6 +844,7 @@ export class AgentController {
     /** Abort every child and clear timers. Idempotent; safe to call twice. */
     dispose() {
         this.teamRuntime?.dispose();
+        this.fast?.dispose();
     }
     // -----------------------------------------------------------------------
     // Todo planning (todo-plan-execution §3.6a)
@@ -708,11 +921,47 @@ export class AgentController {
         this.todos?.clear('user');
     }
     // -----------------------------------------------------------------------
+    // API retry (llm-api-retry-backoff §6.3)
+    //
+    // NO `retryRegistered` TWIN of the team / todo flag pairs, and that asymmetry
+    // is the point: retry is not a tool, so nothing is decided at construction.
+    // The policy lives on the `ProviderRegistry`, which means it can be replaced
+    // for a running session — including for children, because `TeamRuntime` holds
+    // the same registry instance.
+    // -----------------------------------------------------------------------
+    getRetryConfig() {
+        return this.config.retry;
+    }
+    /**
+     * Adopt a new retry config for this session AND PUSH IT INTO THE REGISTRY.
+     *
+     * THE SECOND CALL IS REQUIRED, NOT A NICETY (§6.3). Without it `/retry off`
+     * would persist correctly and change nothing until the next launch — the
+     * precise failure `config/schema.ts` warns about twice already, and the one a
+     * user reports as "the setting does nothing".
+     *
+     * Clamped here as well as on the persist path, so a bad value can reach neither
+     * the runtime nor the file.
+     */
+    setRetryConfig(patch) {
+        const retry = clampRetryConfig({ ...this.config.retry, ...patch });
+        this.config = { ...this.config, retry };
+        this.providerRegistry.setRetryPolicy(toRetryPolicy(retry));
+        return retry;
+    }
+    // -----------------------------------------------------------------------
     // Mutators
     // -----------------------------------------------------------------------
     setModel(provider, model, baseUrl) {
         this.config = { ...this.config, provider, model, baseUrl };
         this.agent.setModel({ providerId: provider, modelId: model, ...(baseUrl ? { baseUrl } : {}) });
+        // NOT NEUTRAL TO THE FAST TIER even when the user never touched a `fast.*`
+        // key (§3.9 / RV-3): `fast.provider: ''` and `fast.baseUrl: ''` INHERIT from
+        // exactly these three fields. Switching the main provider can therefore turn
+        // a working tier into `no_key`, or silently re-point an inheriting tier at
+        // another vendor's gateway — and `<fast_tier>` would go on naming the model
+        // it used to resolve to.
+        this.fast?.onConfigChanged();
     }
     setThinkingLevel(level) {
         this.config = { ...this.config, thinkingLevel: level };
@@ -729,6 +978,9 @@ export class AgentController {
             ...this.config,
             apiKeys: { ...this.config.apiKeys, [provider]: key },
         };
+        // Rule 5 of §3.2 reads `apiKeys`, so a key edit is a tier event: this is the
+        // path that turns `no_key` back into a working tier without a relaunch.
+        this.fast?.onConfigChanged();
     }
     setCwd(cwd) {
         this.cwd = cwd;
@@ -744,6 +996,61 @@ export class AgentController {
     getCwd() {
         return this.cwd;
     }
+    /**
+     * The structured diff a file tool left behind, CONSUMED ONCE.
+     *
+     * Called by `reduceEvent` on `tool_execution_end` and nowhere else, which is
+     * what keeps the store at constant size however many files a session edits.
+     * `undefined` is an ordinary answer — a tool that records nothing, a toolset
+     * built without a recorder, or an entry the 64-write ring has already evicted
+     * — and every one of those falls back to `ToolPreview`.
+     */
+    takeFilePatch(toolCallId) {
+        return this.fileChanges.take('lead', toolCallId);
+    }
+    /**
+     * Sanitise a chunk into the store and hand the resulting tail to the view.
+     *
+     * SYNCHRONOUS, INSIDE THE CHILD-PROCESS DATA HANDLER. The alternative (queue
+     * plus timer) adds a second clock to a component that already has one, and
+     * `App` coalesces at the other end anyway (D-34).
+     *
+     * EVERY LISTENER IS WRAPPED, and that is not defensive noise (R-5 / AC-35): a
+     * throw here propagates into `child.stdout.on('data')`, which is the reason a
+     * render-side bug could otherwise kill a ten-minute build. `debug` rather than
+     * `warn` because a listener that throws once throws on every chunk.
+     */
+    emitToolOutput(owner, toolCallId, chunk) {
+        if (!this.toolOutputs)
+            return;
+        const rows = this.toolOutputs.append(owner, toolCallId, chunk);
+        for (const listener of this.outputListeners) {
+            try {
+                listener({ toolCallId, rows });
+            }
+            catch (err) {
+                getLogger().debug('tool', 'tool_output_listener_threw', {
+                    toolCallId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    /**
+     * Subscribe to the CLI-local live tool-output stream (§3.1.3).
+     *
+     * Returns a no-op unsubscribe when `liveToolOutput` was off at construction,
+     * so every caller can subscribe unconditionally -- the contract
+     * `subscribeTeam` / `subscribeTodos` / `subscribeFast` already set.
+     */
+    subscribeToolOutput(listener) {
+        if (!this.toolOutputs)
+            return () => { };
+        this.outputListeners.add(listener);
+        return () => {
+            this.outputListeners.delete(listener);
+        };
+    }
     clearMessages() {
         this.agent.clearMessages();
         // A new conversation has no loaded skills, so the "already loaded earlier
@@ -782,10 +1089,95 @@ export class AgentController {
     }
     /** Resolve `ModelInfo` for the active model, falling back to a runtime model. */
     getModelInfo() {
-        const found = this.modelRegistry.getModel(this.config.provider, this.config.model);
+        return this.getModelInfoFor({
+            providerId: this.config.provider,
+            modelId: this.config.model,
+        });
+    }
+    /**
+     * Resolve `ModelInfo` for ANY model (fast-model-tier §3.6 / RV-4).
+     *
+     * ONE RESOLUTION PATH, which is the same reason §3.2 has exactly one
+     * `resolveFastTier`: `getModelInfo()` above is now a call into this, so "the
+     * cost table for the model that actually billed" cannot drift from "the cost
+     * table for the session's model" as two separate bodies.
+     */
+    getModelInfoFor(ref) {
+        const found = this.modelRegistry.getModel(ref.providerId, ref.modelId);
         if (found)
             return found;
-        return this.modelRegistry.buildRuntimeModel(this.config.provider, this.config.model);
+        return this.modelRegistry.buildRuntimeModel(ref.providerId, ref.modelId);
+    }
+    /**
+     * Whether the STATIC table knows this model's price (C-11 / RV-4).
+     *
+     * `buildRuntimeModel` returns `cost: { input: 0, output: 0 }` for a model it
+     * has never seen — a table of zeros, not a missing one — so every consumer
+     * that renders spend needs to be able to tell "free" from "unknown". The fast
+     * tier is precisely where an unrecognised id is likely, and `$0.00` on a
+     * feature that is spending money is the same class of lie as pricing a Haiku
+     * child at Sonnet rates.
+     */
+    isPricedModel(ref) {
+        return this.modelRegistry.getModel(ref.providerId, ref.modelId) !== undefined;
+    }
+    // -----------------------------------------------------------------------
+    // Fast model tier (fast-model-tier §3.1) — FOUR THIN FORWARDERS
+    // -----------------------------------------------------------------------
+    /** Whether `task`'s schema carries `model`. Fixed at construction (C-2). */
+    isFastRegistered() {
+        return this.fast !== null;
+    }
+    /** Whether the tier will actually be used. Flipped live by `/fast on|off`. */
+    isFastEnabled() {
+        return this.fast?.isEnabled() === true;
+    }
+    /**
+     * Flip the live switch and re-render the prompt.
+     *
+     * Turning it ON in a session that started without the tier deliberately does
+     * NOT register it: the tool array is immutable (C-2), and advertising a schema
+     * field that is not there is the dead end `/team on` already documents.
+     * `/fast` reports that honestly by checking `isFastRegistered()` first.
+     */
+    setFastEnabled(enabled) {
+        this.fast?.setEnabled(enabled);
+    }
+    getFastConfig() {
+        return this.config.fast;
+    }
+    /**
+     * Adopt a new fast config for this session.
+     *
+     * THE RE-RESOLUTION IS NOT OPTIONAL (§3.2 rule 8). `App` reads
+     * `controller.getConfig()` on every render and the block interpolates the
+     * model id, so a persist without this call reports success and changes
+     * nothing until relaunch — the failure `/todo panel` records (P1-2).
+     */
+    setFastConfig(patch) {
+        const fast = clampFastConfig({ ...this.config.fast, ...patch });
+        this.config = { ...this.config, fast };
+        // `onConfigChanged` rebuilds the prompt; when there is no wiring (the tier
+        // was never registered) nothing has to be rebuilt, because no block is
+        // spliced either way.
+        this.fast?.onConfigChanged();
+        return fast;
+    }
+    /** Everything `/fast status`, the settings line and the chip read. */
+    getFastStatus() {
+        return this.fast ? this.fast.status() : offFastStatus();
+    }
+    /**
+     * Subscribe to the CLI-local fast event stream.
+     *
+     * Returns a no-op unsubscribe when the tier was off at construction, so every
+     * caller can subscribe unconditionally — the contract `subscribeTeam` and
+     * `subscribeTodos` already set.
+     */
+    subscribeFast(listener) {
+        if (!this.fast)
+            return () => { };
+        return this.fast.subscribe(listener);
     }
     /** List usable tools (name + description) for the /tools command. */
     listTools() {

package/dist/agent/headless.d.ts

@@ -8,6 +8,7 @@ import type { AgentEvent, ModelInfo } from '@aragon-agent/core';
 import type { PreflightResult } from './controller.js';
 import type { TeamEvent } from '../team/types.js';
 import type { TodoEvent, TodoSnapshot } from '../todo/types.js';
+import type { FastEvent } from '../fast/types.js';
 import { type FollowThroughMode } from '../todo/follow-through.js';
 /** The minimal controller surface headless mode needs (real or stubbed). */
 export interface HeadlessController {
@@ -35,6 +36,13 @@ export interface HeadlessController {
      * keeps a `--no-todo` headless run byte-identical to today's.
      */
     subscribeTodos?(listener: (event: TodoEvent) => void): () => void;
+    /**
+     * The CLI-local fast-tier stream — OPTIONAL, for the identical reason the two
+     * above are (fast-model-tier §3.9). A controller with no tier has no fast
+     * events, and `runHeadless` calls it with `?.`, which keeps a default `-p` run
+     * byte-identical to today's.
+     */
+    subscribeFast?(listener: (event: FastEvent) => void): () => void;
     /**
      * The current plan — OPTIONAL, for the identical reason the two subscriptions
      * above are (todo-plan-followthrough §3.6 rule 2). ABSENT MEANS THE

package/dist/agent/headless.js

@@ -21,6 +21,8 @@ export async function runHeadless(controller, prompt, options = {}) {
     let sawTurnEnd = false;
     let wroteText = false;
     const total = { inputTokens: 0, outputTokens: 0 };
+    /** Retries seen this run, so the recovery line can name a count. */
+    let retryCount = 0;
     const unsubscribe = controller.subscribe((event) => {
         switch (event.type) {
             case 'message_update': {
@@ -33,6 +35,25 @@ export async function runHeadless(controller, prompt, options = {}) {
                     errored = true;
                     err.write(`\n${formatStreamError(se.error)}\n`);
                 }
+                else if (se.type === 'retry_scheduled') {
+                    // STDERR, NEVER STDOUT (llm-api-retry-backoff §6.7). stdout is the
+                    // machine-readable answer and has to stay parseable by
+                    // `aragon -p | jq`; a retry line on it would corrupt every consumer.
+                    // Not `--quiet`-gated, unlike the tool lines: a three-minute pause with
+                    // no explanation anywhere is not a "compact" run, it is a hang.
+                    retryCount = se.attempt;
+                    // The em dash is a literal because `agent/headless.ts` is the CLI's one
+                    // documented glyph-scanner exemption: `aragon -p` does no capability
+                    // probe, so there is no `Glyphs` set to read here.
+                    err.write(`\n[retry ${se.attempt}/${se.maxRetries}] ${se.errorType} — ` +
+                        `waiting ${Math.round(se.delayMs / 1000)}s\n`);
+                }
+                else if (se.type === 'stream_restart') {
+                    // The partial answer already on stdout is about to be replayed. Saying so
+                    // is the only way a piped consumer can tell a duplicated paragraph from
+                    // a model that repeated itself.
+                    err.write(`[retry] discarding a partial response and restarting\n`);
+                }
                 break;
             }
             case 'tool_execution_start':
@@ -46,6 +67,10 @@ export async function runHeadless(controller, prompt, options = {}) {
                 break;
             case 'turn_end':
                 sawTurnEnd = true;
+                if (retryCount > 0) {
+                    err.write(`[retry] recovered after ${retryCount} ${retryCount === 1 ? 'retry' : 'retries'}\n`);
+                    retryCount = 0;
+                }
                 total.inputTokens += event.usage.inputTokens;
                 total.outputTokens += event.usage.outputTokens;
                 break;
@@ -128,6 +153,20 @@ export async function runHeadless(controller, prompt, options = {}) {
         lastActive = activeIndex;
         err.write(`[todo] ${activeIndex + 1}/${total} ${items[activeIndex]?.content ?? ''}\n`);
     });
+    // Fast-tier review spend must reach the `[usage]` footer, or `-p` under-reports
+    // by however much the reviewer consumed (§3.6).
+    //
+    // NOTHING IS WRITTEN TO STDOUT, AND NOTHING TO STDERR EITHER (D-12). stdout is
+    // the answer channel and is piped into other tools; stderr in `-p` carries the
+    // tool trace, and an unrequested second opinion is not a tool the user asked
+    // for. The reviews are in the log records either way, which is where a `-p`
+    // user goes to ask what happened.
+    const unsubscribeFast = controller.subscribeFast?.((event) => {
+        if (event.type !== 'usage')
+            return;
+        total.inputTokens += event.usage.inputTokens;
+        total.outputTokens += event.usage.outputTokens;
+    });
     // --- The bounded continuation loop (todo-plan-followthrough §3.6). --------
     //
     // THE THREE `unsubscribe` CALLS STAY OUTSIDE IT (rule 4). The loop wraps the
@@ -187,6 +226,7 @@ export async function runHeadless(controller, prompt, options = {}) {
         unsubscribe();
         unsubscribeTeam?.();
         unsubscribeTodos?.();
+        unsubscribeFast?.();
     }
     // Ensure a trailing newline so piped output is well-formed.
     if (wroteText)