@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/exec/index.js

@@ -58,7 +58,18 @@ export async function runExec(flags, raw, promptArg, ctx) {
     const plan = planSession(options, cwd, err);
     if (!plan)
         return 2;
-    const prompts = resolvePromptSource(options, promptArg, ctx, err);
+    /**
+     * Late-bound interrupt hook (see `resolvePromptSource` and `execute`).
+     *
+     * The stdin stream is built - and already reading - about eighty lines before
+     * the runner exists, so the frame handler cannot close over the runner
+     * directly. The box starts as a no-op and is filled in AFTER
+     * `runner.attach(controller)`; during that gap an interrupt does nothing at
+     * all, which is the honest outcome (the user simply presses it again). See
+     * `execute` for why "does nothing" beats "does half of it".
+     */
+    const interrupt = { fire: () => { } };
+    const prompts = resolvePromptSource(options, promptArg, ctx, err, interrupt);
     if (!prompts)
         return 2;
     const lock = plan.saving ? tryAcquireSessionLock(plan.id) : null;
@@ -68,14 +79,14 @@ export async function runExec(flags, raw, promptArg, ctx) {
         return 2;
     }
     try {
-        return await execute({ flags, options, plan, prompts, ctx, out, err, now, appended });
+        return await execute({ flags, options, plan, prompts, ctx, out, err, now, appended, interrupt });
     }
     finally {
         lock?.release();
     }
 }
 async function execute(input) {
-    const { options, plan, ctx, out, err, now } = input;
+    const { options, plan, ctx, out, err, now, interrupt } = input;
     const startedAt = now();
     const permission = resolvePermission({
         mode: options.permissionMode,
@@ -117,8 +128,29 @@ async function execute(input) {
         permissionMode: options.permissionMode,
         tools: controller.listTools().map((t) => t.name),
         resumed: plan.saved !== null,
+        // W2 - where this run's conversation lives, so a wrapper can check on disk
+        // whether it is still resumable rather than re-deriving the sessions dir.
+        //
+        // `plan.id`, NEVER `options.resume`. The flag accepts `<id|path>`, and
+        // `planSession` runs the caller's string through `resumedSessionId()` to
+        // decide what the file is actually named - so "the file the caller pointed
+        // at" and "the file this run writes" are routinely two different paths. The
+        // question a wrapper is asking ("what can I reattach to next time") is
+        // answered by the second one.
+        //
+        // `!plan.saving` is `--no-save-session`: nothing is written, so there will
+        // be nothing to reattach to, and `null` says that outright.
+        sessionFile: plan.saving ? sessionPathFor(plan.id) : null,
     });
     runner.attach(controller);
+    // AFTER `attach`, never before. The terminator closure ends on
+    // `this.controller?.abort()`, so before `attach` the controller is still
+    // `undefined` and that last statement is a silent no-op - while the SAME
+    // closure has already written `lastSignalAt` and `stopReason = 'interrupted'`.
+    // A real interrupt arriving within the next two seconds would then be judged a
+    // SECOND signal and take `signals.exit(128 + signo)`: a hard exit, no persist,
+    // no `result` - exactly the outcome the caller was trying to avoid.
+    interrupt.fire = () => runner.requestInterrupt();
     const pre = controller.preflight();
     if (!pre.ok) {
         runner.detach();
@@ -261,7 +293,7 @@ function failedResult(sessionId, config, message, code, durationMs) {
  * Returns `null` after writing the reason to stderr, so the caller can exit 2
  * without a second error vocabulary.
  */
-function resolvePromptSource(options, promptArg, ctx, err) {
+function resolvePromptSource(options, promptArg, ctx, err, interrupt) {
     const stdin = ctx.stdin ?? process.stdin;
     const opening = [];
     const positional = promptArg?.trim();
@@ -282,8 +314,13 @@ function resolvePromptSource(options, promptArg, ctx, err) {
             // line is skipped either way, which is the property AC-20 pins.
             onBadLine: (message) => err.write(`${message}\n`),
             // The runner installs the signal terminator; a caller-requested
-            // interrupt is the same intent arriving through a different channel.
-            onInterrupt: () => process.kill(process.pid, 'SIGINT'),
+            // interrupt is the same intent arriving through a different channel -
+            // so it now calls the runner DIRECTLY rather than raising a signal at
+            // ourselves. `process.kill(process.pid, 'SIGINT')` does not reach this
+            // process's own handlers on Windows: it terminates with exit code 1,
+            // skipping the settle path, `persist()` and the `result` event. See
+            // `ExecRunner.requestInterrupt`.
+            onInterrupt: () => interrupt.fire(),
         }));
     }
     if (opening.length === 0 && !stdinIsTty(stdin)) {

package/dist/exec/progress-reporter.d.ts

@@ -0,0 +1,23 @@
+import type { ExecProgressEvent } from './events.js';
+/** Request-scoped, one-shot aggregation of real semantic events. */
+export declare class ExecProgressReporter {
+    private readonly sessionId;
+    private readonly emit;
+    private readonly now;
+    private requestSeq;
+    private progressSeq;
+    private sentSeq;
+    private phase;
+    private retryDelayMs;
+    private lastSentAt;
+    private timer;
+    private enabled;
+    constructor(sessionId: string, emit: (event: ExecProgressEvent) => void, now?: () => number);
+    begin(requestSeq: number): void;
+    /** Called only after the started event has reached the emitter. */
+    started(requestSeq: number): void;
+    record(phase: ExecProgressEvent['phase'], retryDelayMs?: number): void;
+    flush(): void;
+    finish(requestSeq: number): void;
+    dispose(): void;
+}

package/dist/exec/progress-reporter.js

@@ -0,0 +1,88 @@
+const PROGRESS_INTERVAL_MS = 1_000;
+/** Request-scoped, one-shot aggregation of real semantic events. */
+export class ExecProgressReporter {
+    sessionId;
+    emit;
+    now;
+    requestSeq = null;
+    progressSeq = 0;
+    sentSeq = 0;
+    phase = 'model';
+    retryDelayMs;
+    lastSentAt = -Infinity;
+    timer = null;
+    enabled = false;
+    constructor(sessionId, emit, now = () => performance.now()) {
+        this.sessionId = sessionId;
+        this.emit = emit;
+        this.now = now;
+    }
+    begin(requestSeq) {
+        this.dispose();
+        this.requestSeq = requestSeq;
+        this.progressSeq = 0;
+        this.sentSeq = 0;
+        this.phase = 'model';
+        this.retryDelayMs = undefined;
+        this.lastSentAt = -Infinity;
+    }
+    /** Called only after the started event has reached the emitter. */
+    started(requestSeq) {
+        if (this.requestSeq === requestSeq)
+            this.enabled = true;
+    }
+    record(phase, retryDelayMs) {
+        if (!this.enabled || this.requestSeq === null)
+            return;
+        const changed = phase !== this.phase;
+        if (changed)
+            this.flush();
+        this.phase = phase;
+        this.retryDelayMs = phase === 'retry' && Number.isFinite(retryDelayMs)
+            ? Math.min(120_000, Math.max(0, retryDelayMs)) : undefined;
+        this.progressSeq += 1;
+        if (changed || this.now() - this.lastSentAt >= PROGRESS_INTERVAL_MS) {
+            this.flush();
+        }
+        else if (!this.timer) {
+            const requestSeq = this.requestSeq;
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                if (this.requestSeq === requestSeq && this.enabled)
+                    this.flush();
+            }, Math.max(0, PROGRESS_INTERVAL_MS - (this.now() - this.lastSentAt)));
+            this.timer.unref?.();
+        }
+    }
+    flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        if (!this.enabled || this.requestSeq === null || this.sentSeq === this.progressSeq)
+            return;
+        this.sentSeq = this.progressSeq;
+        this.lastSentAt = this.now();
+        this.emit({
+            type: 'execution_progress', sessionId: this.sessionId,
+            requestSeq: this.requestSeq, progressSeq: this.progressSeq, phase: this.phase,
+            ...(this.retryDelayMs !== undefined ? { retryDelayMs: this.retryDelayMs } : {}),
+        });
+    }
+    finish(requestSeq) {
+        if (this.requestSeq !== requestSeq)
+            return;
+        try {
+            this.flush();
+        }
+        finally {
+            this.dispose();
+        }
+    }
+    dispose() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.requestSeq = null;
+        this.enabled = false;
+    }
+}

package/dist/exec/runner.d.ts

@@ -18,6 +18,7 @@ import type { TokenUsage } from '@aragon-agent/core';
 import type { HeadlessController } from '../agent/headless.js';
 import { type FollowThroughMode } from '../todo/follow-through.js';
 import type { ExecEmitter } from './emitter.js';
+import type { FastSnapshot } from '../fast/types.js';
 import type { ExecStopReason } from './events.js';
 /**
  * The controller surface the runner needs.
@@ -34,6 +35,16 @@ export interface ExecRunnerController extends HeadlessController {
         providerId: string;
         modelId: string;
     }): boolean;
+    /**
+     * The fast tier's current snapshot, or `null` when this session has no tier
+     * (web-use-tier-cooperation-and-control-closure §4.2.1).
+     *
+     * OPTIONAL, for the identical reason `subscribeFast` is: this interface is
+     * minimal so a test can satisfy it with an object literal, and a controller
+     * with no tier has nothing to report. Called with `?.()`, so a stub that omits
+     * it simply emits no `fast_tier` events.
+     */
+    fastSnapshot?(): FastSnapshot | null;
 }
 /** Where the caller's messages come from. One turn, or an NDJSON stdin stream. */
 export interface ExecPromptSource {
@@ -77,6 +88,7 @@ export declare class ExecRunner {
     private readonly opts;
     private readonly signals;
     private readonly now;
+    private readonly progress;
     private controller;
     private unsubscribers;
     private turns;
@@ -131,6 +143,9 @@ export declare class ExecRunner {
      * the two faces cannot drift about what "unfinished" means.
      */
     run(source: ExecPromptSource): Promise<void>;
+    private requestSeq;
+    private requestHadError;
+    private isRequestCancelled;
     /** One caller message plus every auto-continuation it produces. */
     private runFollowThroughChain;
     /**
@@ -192,6 +207,25 @@ export declare class ExecRunner {
      * this and add the getter.
      */
     private installTerminator;
+    /**
+     * Exactly synonymous with a SIGINT, only it does not travel through a signal.
+     *
+     * The stdin `{"type":"interrupt"}` frame routes here. It used to route through
+     * `process.kill(process.pid, 'SIGINT')`, which is fine on POSIX and WRONG on
+     * Windows: Node does not deliver a self-directed SIGINT to its own handlers
+     * there, so the process terminates with exit code 1 having run neither the
+     * terminator below, nor the settle path, nor `persist()`, nor the `result`
+     * event. A wrapper that interrupts a turn and respawns on the same
+     * `--session-id` would silently get a conversation missing everything since the
+     * last save - and `exec/index.ts` was already designed for exactly that caller
+     * ("PERSIST FIRST, ANNOUNCE SECOND").
+     *
+     * POSIX behaviour is byte-for-byte unchanged: the same closure runs, with
+     * `signalNumber = 2`, `exitCode() = 130`, and the two-second second-signal
+     * escape hatch intact.
+     */
+    requestInterrupt(): void;
+    private onSignal;
     private emit;
     /** Caller-facing prose. STDERR ALWAYS - stdout carries nothing but the schema. */
     private note;

package/dist/exec/runner.js

@@ -17,6 +17,7 @@
 import { formatStreamError } from '../agent/reducer.js';
 import { setSignalTerminator } from '../logging/install.js';
 import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
+import { ExecProgressReporter } from './progress-reporter.js';
 export function singlePrompt(text) {
     let served = false;
     return {
@@ -40,6 +41,7 @@ export class ExecRunner {
     opts;
     signals;
     now;
+    progress;
     controller = null;
     unsubscribers = [];
     turns = 0;
@@ -62,6 +64,7 @@ export class ExecRunner {
         this.opts = options;
         this.signals = options.signals ?? DEFAULT_SIGNAL_PORT;
         this.now = options.now ?? Date.now;
+        this.progress = new ExecProgressReporter(this.sessionId, (event) => this.emit(event));
     }
     // -----------------------------------------------------------------------
     // Attach / detach
@@ -103,20 +106,65 @@ export class ExecRunner {
         });
         if (todos)
             this.unsubscribers.push(todos);
+        // FOUR BRANCHES, and the split is the whole of W2
+        // (web-use-tier-cooperation-and-control-closure §4.2.1):
+        //
+        //  · `usage`         — folded into the run's totals (unchanged).
+        //  · `review_end`    — the EXISTING `fast_review` still fires only when the
+        //                      critique has text, byte-for-byte as before; a
+        //                      `fast_tier` now fires UNCONDITIONALLY beside it, so a
+        //                      failed / empty / dropped review is finally visible.
+        //  · `tier_changed`  — a `fast_tier` with no `review` sub-object. This is the
+        //                      one that carries `selfDisabled: true`, because the
+        //                      reviewer emits it right after switching itself off.
+        //  · `review_start`  — DROPPED. `inFlight` on the snapshot already says it,
+        //                      and once every N turns it is pure noise.
         const fast = controller.subscribeFast?.((event) => {
             if (event.type === 'usage') {
                 this.usage.inputTokens += event.usage.inputTokens;
                 this.usage.outputTokens += event.usage.outputTokens;
                 return;
             }
-            if (event.type !== 'review_end' || !event.review.text)
+            if (event.type === 'review_start')
+                return;
+            if (event.type === 'review_end' && event.review.text) {
+                this.emit({
+                    type: 'fast_review',
+                    sessionId: this.sessionId,
+                    turn: event.review.turn,
+                    model: event.review.model,
+                    text: event.review.text,
+                });
+            }
+            // `null` means this session never registered a tier, and a session with no
+            // tier has no business appearing on this channel at all.
+            const snapshot = controller.fastSnapshot?.();
+            if (!snapshot)
                 return;
             this.emit({
-                type: 'fast_review',
+                type: 'fast_tier',
                 sessionId: this.sessionId,
-                turn: event.review.turn,
-                model: event.review.model,
-                text: event.review.text,
+                turn: this.turns,
+                live: snapshot.live,
+                selfDisabled: snapshot.selfDisabled,
+                model: snapshot.model,
+                sameAsMain: snapshot.sameAsMain,
+                reviews: snapshot.reviews,
+                reviewBudget: snapshot.reviewBudget,
+                budgetReached: snapshot.budgetReached,
+                delegated: snapshot.delegated,
+                inFlight: snapshot.inFlight,
+                ...(event.type === 'review_end'
+                    ? {
+                        review: {
+                            index: event.review.index,
+                            kind: event.review.kind,
+                            ...(event.review.detail !== undefined ? { detail: event.review.detail } : {}),
+                            durationMs: event.review.durationMs,
+                            injected: event.review.injected,
+                        },
+                    }
+                    : {}),
             });
         });
         if (fast)
@@ -132,6 +180,7 @@ export class ExecRunner {
                 return;
             }
             if (event.type === 'compaction_start') {
+                this.progress.record('compaction');
                 this.emit({
                     type: 'compaction',
                     sessionId: this.sessionId,
@@ -143,6 +192,7 @@ export class ExecRunner {
             }
             if (event.type !== 'compaction_end')
                 return;
+            this.progress.record('model');
             const r = event.record;
             this.emit({
                 type: 'compaction',
@@ -177,6 +227,7 @@ export class ExecRunner {
         if (this.detached)
             return;
         this.detached = true;
+        this.progress.dispose();
         for (const off of this.unsubscribers.splice(0)) {
             try {
                 off();
@@ -241,15 +292,42 @@ export class ExecRunner {
             // nothing more to say exits 0 with `end_turn`, not 3 with `max_turns`.
             if (next === null)
                 break;
-            if (this.turnBudgetExhausted()) {
-                this.stopReason = 'max_turns';
-                break;
+            const requestSeq = ++this.requestSeq;
+            this.requestHadError = false;
+            this.progress.begin(requestSeq);
+            this.emit({ type: 'turn_state', sessionId: this.sessionId, requestSeq, phase: 'started' });
+            this.progress.started(requestSeq);
+            try {
+                if (this.isRequestCancelled())
+                    break;
+                if (this.turnBudgetExhausted()) {
+                    this.stopReason = 'max_turns';
+                    break;
+                }
+                const finished = await this.runFollowThroughChain(controller, next, followThrough);
+                if (finished)
+                    break;
+            }
+            catch (err) {
+                this.errored = true;
+                this.recordError('agent_error', err instanceof Error ? err.message : String(err));
+                throw err;
+            }
+            finally {
+                this.progress.finish(requestSeq);
+                const phase = this.isRequestCancelled()
+                    ? 'cancelled'
+                    : this.requestHadError ? 'failed' : 'completed';
+                this.emit({ type: 'turn_state', sessionId: this.sessionId, requestSeq, phase });
             }
-            const finished = await this.runFollowThroughChain(controller, next, followThrough);
-            if (finished)
-                break;
         }
     }
+    requestSeq = 0;
+    requestHadError = false;
+    isRequestCancelled() {
+        return this.stopReason === 'interrupted' || this.stopReason === 'timeout' ||
+            this.stopReason === 'max_turns';
+    }
     /** One caller message plus every auto-continuation it produces. */
     async runFollowThroughChain(controller, initial, followThrough) {
         let budget = emptyBudget();
@@ -281,7 +359,7 @@ export class ExecRunner {
                 // `aborted` is false here for the same structural reason `-p` gives: an
                 // interrupt sets `stopReason` and returns above, so this branch is only
                 // reached by a run that ended on its own terms.
-                runEnd: { aborted: false, errored: this.errored },
+                runEnd: { aborted: false, errored: this.requestHadError },
                 budget,
                 interactive: false,
             });
@@ -394,18 +472,39 @@ export class ExecRunner {
      * this and add the getter.
      */
     installTerminator() {
-        this.signals.setTerminator((signo) => {
-            const at = this.now();
-            const secondSignal = at - this.lastSignalAt <= SECOND_SIGNAL_WINDOW_MS;
-            if (this.detached || (this.lastSignalAt > 0 && secondSignal)) {
-                this.signals.exit(128 + signo);
-                return;
-            }
-            this.lastSignalAt = at;
-            this.signalNumber = signo;
-            this.stopReason = 'interrupted';
-            this.controller?.abort();
-        });
+        this.signals.setTerminator((signo) => this.onSignal(signo));
+    }
+    /**
+     * Exactly synonymous with a SIGINT, only it does not travel through a signal.
+     *
+     * The stdin `{"type":"interrupt"}` frame routes here. It used to route through
+     * `process.kill(process.pid, 'SIGINT')`, which is fine on POSIX and WRONG on
+     * Windows: Node does not deliver a self-directed SIGINT to its own handlers
+     * there, so the process terminates with exit code 1 having run neither the
+     * terminator below, nor the settle path, nor `persist()`, nor the `result`
+     * event. A wrapper that interrupts a turn and respawns on the same
+     * `--session-id` would silently get a conversation missing everything since the
+     * last save - and `exec/index.ts` was already designed for exactly that caller
+     * ("PERSIST FIRST, ANNOUNCE SECOND").
+     *
+     * POSIX behaviour is byte-for-byte unchanged: the same closure runs, with
+     * `signalNumber = 2`, `exitCode() = 130`, and the two-second second-signal
+     * escape hatch intact.
+     */
+    requestInterrupt() {
+        this.onSignal(2);
+    }
+    onSignal(signo) {
+        const at = this.now();
+        const secondSignal = at - this.lastSignalAt <= SECOND_SIGNAL_WINDOW_MS;
+        if (this.detached || (this.lastSignalAt > 0 && secondSignal)) {
+            this.signals.exit(128 + signo);
+            return;
+        }
+        this.lastSignalAt = at;
+        this.signalNumber = signo;
+        this.stopReason = 'interrupted';
+        this.controller?.abort();
     }
     // -----------------------------------------------------------------------
     // Event translation
@@ -431,6 +530,7 @@ export class ExecRunner {
                 this.checkTurnBudget();
                 break;
             case 'tool_execution_start':
+                this.progress.record('tool');
                 this.emit({
                     type: 'tool_call',
                     sessionId: this.sessionId,
@@ -441,6 +541,7 @@ export class ExecRunner {
                 });
                 break;
             case 'tool_execution_end':
+                this.progress.record('model');
                 this.emit({
                     type: 'tool_result',
                     sessionId: this.sessionId,
@@ -457,7 +558,7 @@ export class ExecRunner {
                 break;
             case 'agent_end':
                 // A swallowed throw (missing key / empty stream) produces no `turn_end`.
-                if (!this.sawTurnEnd && !this.errored && this.stopReason === 'end_turn') {
+                if (!this.sawTurnEnd && !this.requestHadError && !this.isRequestCancelled()) {
                     this.errored = true;
                     this.recordError('agent_error', 'The run produced no assistant turn.');
                 }
@@ -467,6 +568,16 @@ export class ExecRunner {
         }
     }
     onStreamEvent(se) {
+        if (se.type === 'text_delta' && se.delta)
+            this.progress.record('model');
+        if (se.type === 'thinking_delta' && se.delta)
+            this.progress.record('thinking');
+        if (se.type === 'tool_call_delta' && se.argsDelta)
+            this.progress.record('tool_arguments');
+        if (se.type === 'retry_scheduled')
+            this.progress.record('retry', se.delayMs);
+        if (se.type === 'retry_attempt')
+            this.progress.record('model');
         if (se.type === 'text_delta') {
             this.flushThinking();
             if (this.opts.partialMessages) {
@@ -527,6 +638,7 @@ export class ExecRunner {
         this.emit({ type: 'thinking', sessionId: this.sessionId, turn: this.turns + 1, text });
     }
     recordError(code, message) {
+        this.requestHadError = true;
         if (this.errorCode)
             return;
         this.errorCode = code;

package/dist/fast/reviewer.d.ts

@@ -59,7 +59,7 @@
 import type { AgentEvent, AssistantMessage, LLMRequest, TokenUsage } from '@aragon-agent/core';
 import type { FastConfig } from '../config/schema.js';
 import type { NoticeLevel } from '../agent/reducer.js';
-import type { FastEvent, FastTier } from './types.js';
+import type { FastEvent, FastSnapshot, FastTier } from './types.js';
 /**
  * Everything the reviewer needs from the rest of the world.
  *
@@ -93,6 +93,14 @@ export interface FastReviewerDeps {
     available(): boolean;
     getApiKey(providerId: string): string | undefined;
     emit(event: FastEvent): void;
+    /**
+     * `FastWiring.snapshot()`, so the self-disable can announce itself.
+     *
+     * The reviewer cannot build a `FastSnapshot` on its own — `live`,
+     * `sameAsMain`, `delegated` and `pricingUnknown` all belong to the wiring —
+     * and the two existing `tier_changed` emitters read it the same way.
+     */
+    snapshot(): FastSnapshot;
     notify(level: NoticeLevel, text: string): void;
     /** Injected clock. A test that reads the wall clock fails on a slow machine
      *  and nowhere else - the reason `TodoStore` and `TeamPanel` take one. */
@@ -155,6 +163,16 @@ export declare class FastReviewer {
     isBudgetReached(): boolean;
     sessionUsage(): TokenUsage;
     isReviewInFlight(): boolean;
+    /**
+     * Whether this reviewer switched itself off after
+     * `FAST_LIMITS.maxConsecutiveFailures` non-transient failures in a row.
+     *
+     * Carried onto `FastSnapshot` so a wrapper can say "the fast reviews stopped,
+     * and here is why" instead of showing a tier that reads as healthy while not
+     * one review ever arrives. Same shape as `reviewCount()` / `isBudgetReached()`
+     * — a read-only accessor, no side effects.
+     */
+    isSelfDisabled(): boolean;
     /**
      * `AgentController.abort()`.
      *

package/dist/fast/reviewer.js

@@ -141,6 +141,18 @@ export class FastReviewer {
     isReviewInFlight() {
         return this.inFlight;
     }
+    /**
+     * Whether this reviewer switched itself off after
+     * `FAST_LIMITS.maxConsecutiveFailures` non-transient failures in a row.
+     *
+     * Carried onto `FastSnapshot` so a wrapper can say "the fast reviews stopped,
+     * and here is why" instead of showing a tier that reads as healthy while not
+     * one review ever arrives. Same shape as `reviewCount()` / `isBudgetReached()`
+     * — a read-only accessor, no side effects.
+     */
+    isSelfDisabled() {
+        return this.selfDisabled;
+    }
     /**
      * `AgentController.abort()`.
      *
@@ -561,6 +573,16 @@ export class FastReviewer {
             this.selfDisabled = true;
             this.deps.notify('warn', `Fast review disabled for this session after ${FAST_LIMITS.maxConsecutiveFailures} ` +
                 `failures. Last error: ${errorText(err)}`);
+            // THE ONE LINE THAT MAKES THE FLAG OBSERVABLE OUTSIDE THIS PROCESS.
+            //
+            // `emitReview({kind:'failed'})` above already fired, carrying a snapshot
+            // in which `selfDisabled` was still `false`, and after this point the
+            // reviewer emits NOTHING EVER AGAIN (`shouldReview()` opens with
+            // `if (this.selfDisabled) return false;`). Without this extra
+            // `tier_changed`, the field exists, the accessor exists, the snapshot line
+            // exists — and no consumer can ever see it as `true`. The `App` chip also
+            // consumes `tier_changed`; one more refresh is free.
+            this.deps.emit({ type: 'tier_changed', snapshot: this.deps.snapshot() });
         }
     }
     // -----------------------------------------------------------------------

package/dist/fast/types.d.ts

@@ -78,6 +78,21 @@ export interface FastReview {
 export interface FastSnapshot {
     /** The tier resolved AND the live switch is on. */
     live: boolean;
+    /**
+     * The reviewer switched ITSELF off after `maxConsecutiveFailures` in a row
+     * (`FastReviewer.onReviewFailure`).
+     *
+     * ORTHOGONAL TO `live`, AND NEITHER IMPLIES THE OTHER. `live` answers "did
+     * this tier resolve at all" and is `registered && enabled && tier.ok`; the
+     * self-disable touches none of those three, so `live` stays `true` after it.
+     * A consumer that wants to report "the fast reviews stopped happening" MUST
+     * read this field: deriving it as `live === false` is a predicate that can
+     * never be true, and a hand-written fixture makes its test green for ever.
+     *
+     * `available()` is deliberately NOT widened to include it — see the note on
+     * `FastWiring.available`.
+     */
+    selfDisabled: boolean;
     model: string;
     sameAsMain: boolean;
     reviews: number;

package/dist/fast/wiring.d.ts

@@ -115,7 +115,16 @@ export declare class FastWiring {
     private getFastRegistry;
     isRegistered(): boolean;
     isEnabled(): boolean;
-    /** §3.3's live predicate. THE THIRD TERM IS THE POINT - see the header. */
+    /**
+     * §3.3's live predicate. THE THIRD TERM IS THE POINT - see the header.
+     *
+     * `FastReviewer.isSelfDisabled()` is DELIBERATELY NOT a fourth term. Folding
+     * it in would look tidier and would break something else: `delegationAvailable()`
+     * is `available() && config.fast.delegate === true`, so three consecutive
+     * REVIEW failures would silently switch DELEGATION off as well - turning a
+     * diagnostic signal into a behaviour change for every user. The two facts are
+     * reported separately on `FastSnapshot` instead (`live` / `selfDisabled`).
+     */
     available(): boolean;
     /**
      * Whether `model: "fast"` on `task` is honoured right now.