@aragon-agent/cli 0.6.15 → 0.6.17

package/dist/input/stdin-filter.d.ts

@@ -60,6 +60,15 @@ export interface StdinFilterFeatures {
     readonly mouse: boolean;
     /** Recognise pastes and deliver them framed. */
     readonly paste: boolean;
+    /**
+     * Translate keyboard-enhancement encodings (win32-input-mode records on
+     * Windows, CSI-u sequences from kitty/modifyOtherKeys elsewhere) back to
+     * legacy bytes BEFORE Ink parses them. TOLD, never derived: `cli.tsx`
+     * resolves config, TTY state and `vtInputSupported`, and passes the same
+     * boolean to `enableKeyboardEnhancement`, so the filter only ever
+     * translates for a session whose mode push actually happened.
+     */
+    readonly enhancedKeys?: boolean;
 }
 export interface StdinFilter {
     /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */

package/dist/input/stdin-filter.js

@@ -36,6 +36,8 @@ import { MAX_PENDING_MOUSE_CHARS, splitMouseEvents, isMousePrefix, } from './mou
 import { ENTER_NEWLINE_FRAME, PASTE_ASSEMBLY_MAX_MS, PASTE_BURST_MS, PASTE_CLOSE, PASTE_MAX_BYTES, PASTE_OPEN, formatPasteSize, } from './limits.js';
 import { PASTE_BEGIN_MARK, PASTE_END_MARK, classifyChunk, sanitisePaste, trailingPastePrefixLength, } from './paste-parse.js';
 import { splitEnterSequences, trailingEnterPrefixLength } from './enter-sequences.js';
+import { splitCsiUKeys, trailingCsiUPrefixLength, translateCsiUKey } from './csiu-keys.js';
+import { splitWin32KeySequences, trailingWin32PrefixLength, translateWin32Key, } from './win32-input-mode.js';
 /**
  * How long a possible-prefix tail is held before being flushed as text.
  *
@@ -82,6 +84,7 @@ function trailingMousePrefixLength(text) {
     return 0;
 }
 export function createStdinFilter(real, features, bridge, onWarn) {
+    const enhancedKeys = features.enhancedKeys === true;
     const wrapper = new PassThrough();
     const listeners = new Set();
     let pending = '';
@@ -251,17 +254,50 @@ export function createStdinFilter(real, features, bridge, onWarn) {
         else
             writeInput(split.pending);
     };
+    /**
+     * THE ENHANCED-KEY WALK, OUTSIDE PASTES ONLY. win32-input-mode records are
+     * split first (their bodies are digits/semicolons, so no paste marker or
+     * CSI-u sequence can live inside one), then CSI-u sequences in the
+     * remaining text, and only then the legacy Enter family. Each translated
+     * key terminates a heuristic burst exactly like an Enter frame does -- a
+     * keystroke mid-burst is the definition of "not a paste".
+     */
+    const writeEnhancedKey = (legacy) => {
+        if (legacy.length === 0)
+            return;
+        flushBurst();
+        writeInput(legacy);
+    };
     const handleOutsidePaste = (text, holdTail) => {
-        const segments = splitEnterSequences(text);
-        for (let index = 0; index < segments.length; index += 1) {
-            const segment = segments[index];
-            if (segment.kind === 'text') {
-                handleText(segment.text, holdTail && index === segments.length - 1);
+        const win32 = enhancedKeys ? splitWin32KeySequences(text)
+            : [{ kind: 'text', text }];
+        for (let w = 0; w < win32.length; w += 1) {
+            const wSeg = win32[w];
+            const wLast = holdTail && w === win32.length - 1;
+            if (wSeg.kind === 'key') {
+                writeEnhancedKey(translateWin32Key(wSeg.record));
                 continue;
             }
-            // A key terminates the heuristic paste before its internal frame is written.
-            flushBurst();
-            writeInput(segment.kind === 'submit' ? '\r' : ENTER_NEWLINE_FRAME);
+            const csiu = enhancedKeys ? splitCsiUKeys(wSeg.text)
+                : [{ kind: 'text', text: wSeg.text }];
+            for (let c = 0; c < csiu.length; c += 1) {
+                const cSeg = csiu[c];
+                if (cSeg.kind === 'key') {
+                    writeEnhancedKey(translateCsiUKey(cSeg.key));
+                    continue;
+                }
+                const segments = splitEnterSequences(cSeg.text);
+                for (let index = 0; index < segments.length; index += 1) {
+                    const segment = segments[index];
+                    if (segment.kind === 'text') {
+                        handleText(segment.text, wLast && c === csiu.length - 1
+                            && index === segments.length - 1);
+                        continue;
+                    }
+                    // A key terminates the heuristic paste before its internal frame is written.
+                    writeEnhancedKey(segment.kind === 'submit' ? '\r' : ENTER_NEWLINE_FRAME);
+                }
+            }
         }
     };
     const appendBracketed = (text) => {
@@ -310,7 +346,7 @@ export function createStdinFilter(real, features, bridge, onWarn) {
                 // the ESC / ESC-[ head bytes, which the max keeps for whoever needs
                 // them. The existing 12 ms flush and the 32-char ceiling bound the
                 // hold, so no new timer is needed.
-                const keep = Math.max(trailingPastePrefixLength(rest), features.mouse ? trailingMousePrefixLength(rest) : 0, trailingEnterPrefixLength(rest));
+                const keep = Math.max(trailingPastePrefixLength(rest), features.mouse ? trailingMousePrefixLength(rest) : 0, trailingEnterPrefixLength(rest), enhancedKeys ? trailingWin32PrefixLength(rest) : 0, enhancedKeys ? trailingCsiUPrefixLength(rest) : 0);
                 const tail = rest.slice(rest.length - keep);
                 handleOutsidePaste(rest.slice(0, rest.length - keep), true);
                 pending += tail;

package/dist/input/win32-input-mode.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Win32-input-mode translation (win32 keyboard-enhancement section of the
+ * Shift+Enter newline fix).
+ *
+ * WHY THIS EXISTS. With `CSI ? 9001 h` the Windows console (conhost inside
+ * ConPTY included -- verified byte-level on both conhost and Windows Terminal
+ * 1.24, see docs/diagnoses/shift-enter-newline-dead-by-default) reports EVERY
+ * key as `ESC [ vk ; scan ; char ; keyDown ; mods ; repeat _`. That is the
+ * only Windows-side encoding in which Shift+Enter is distinguishable from
+ * Enter: mods carries SHIFT_PRESSED (0x10) on the record. Nothing else
+ * survives ConPTY: kitty `CSI > 1 u` is swallowed (a `CSI ? u` query never
+ * answers) and modifyOtherKeys is a no-op.
+ *
+ * THE CONTRACT. `splitWin32KeySequences` recognises the records in a chunk;
+ * `translateWin32Key` rewrites each one to the LEGACY bytes the same keypress
+ * would have produced with the mode off -- except the modified-Enter family,
+ * which becomes `ENTER_NEWLINE_FRAME` exactly like `enter-sequences.ts` maps
+ * its CSI-u cousins. Ink therefore sees the stream it has always seen. Key-up
+ * records are dropped (every press arrives as a down/up pair in one chunk).
+ *
+ * Pure: no node/React imports, callable from any test environment.
+ */
+/** Enable / disable win32-input-mode (private mode 9001). */
+export declare const WIN32_INPUT_ENABLE = "\u001B[?9001h";
+export declare const WIN32_INPUT_DISABLE = "\u001B[?9001l";
+/** One decoded `ESC [ vk ; sc ; char ; down ; mods ; rep _` record. */
+export interface Win32KeyRecord {
+    readonly vk: number;
+    readonly scan: number;
+    readonly char: number;
+    readonly down: boolean;
+    readonly mods: number;
+    readonly repeat: number;
+}
+export type Win32Segment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'key';
+    record: Win32KeyRecord;
+};
+/**
+ * Split a chunk into text spans and win32-input-mode records.
+ *
+ * MATCHES ONLY `ESC [ <digits/semicolons> _`: mouse reports need `<`, paste
+ * markers end in `~`, CSI-u ends in `u`, DECRPM replies start with `?`. A
+ * `_`-terminated all-numeric-parameter sequence is therefore unambiguous in
+ * the stream this filter ever sees.
+ */
+export declare function splitWin32KeySequences(text: string): Win32Segment[];
+/**
+ * Translate one record to the legacy bytes the same keypress would have
+ * produced with win32-input-mode off (Enter family excepted: a modified Enter
+ * becomes the newline frame, mirroring `ENTER_SEQUENCES`).
+ */
+export declare function translateWin32Key(record: Win32KeyRecord): string;
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * win32-input-mode record, or 0. Longest match, mirroring the other families.
+ */
+export declare function trailingWin32PrefixLength(text: string): number;

package/dist/input/win32-input-mode.js

@@ -0,0 +1,251 @@
+/**
+ * Win32-input-mode translation (win32 keyboard-enhancement section of the
+ * Shift+Enter newline fix).
+ *
+ * WHY THIS EXISTS. With `CSI ? 9001 h` the Windows console (conhost inside
+ * ConPTY included -- verified byte-level on both conhost and Windows Terminal
+ * 1.24, see docs/diagnoses/shift-enter-newline-dead-by-default) reports EVERY
+ * key as `ESC [ vk ; scan ; char ; keyDown ; mods ; repeat _`. That is the
+ * only Windows-side encoding in which Shift+Enter is distinguishable from
+ * Enter: mods carries SHIFT_PRESSED (0x10) on the record. Nothing else
+ * survives ConPTY: kitty `CSI > 1 u` is swallowed (a `CSI ? u` query never
+ * answers) and modifyOtherKeys is a no-op.
+ *
+ * THE CONTRACT. `splitWin32KeySequences` recognises the records in a chunk;
+ * `translateWin32Key` rewrites each one to the LEGACY bytes the same keypress
+ * would have produced with the mode off -- except the modified-Enter family,
+ * which becomes `ENTER_NEWLINE_FRAME` exactly like `enter-sequences.ts` maps
+ * its CSI-u cousins. Ink therefore sees the stream it has always seen. Key-up
+ * records are dropped (every press arrives as a down/up pair in one chunk).
+ *
+ * Pure: no node/React imports, callable from any test environment.
+ */
+import { ENTER_NEWLINE_FRAME } from './limits.js';
+/** Enable / disable win32-input-mode (private mode 9001). */
+export const WIN32_INPUT_ENABLE = '\x1b[?9001h';
+export const WIN32_INPUT_DISABLE = '\x1b[?9001l';
+/** Windows console `dwControlKeyState` modifier bits this module cares about. */
+const RIGHT_ALT = 0x1;
+const LEFT_ALT = 0x2;
+const RIGHT_CTRL = 0x4;
+const LEFT_CTRL = 0x8;
+const SHIFT = 0x10;
+/** Lock states, ENHANCED_KEY and friends must never look like modifiers. */
+const MODIFIER_MASK = SHIFT | LEFT_CTRL | RIGHT_CTRL | LEFT_ALT | RIGHT_ALT;
+/** Virtual-key codes the translator names explicitly. */
+const VK_BACK = 0x08;
+const VK_TAB = 0x09;
+const VK_ENTER = 0x0d;
+const VK_ESCAPE = 0x1b;
+const VK_PACKET = 0xe7;
+/**
+ * Parse one candidate body (`digits and semicolons`, the `_` excluded).
+ * Returns null when the field count is impossible for a real record -- that
+ * is what keeps a random `ESC [ 1 ; 2 3 _`-shaped paste from being eaten.
+ */
+function parseRecord(body) {
+    const fields = body.split(';');
+    if (fields.length !== 6)
+        return null;
+    const nums = fields.map(Number);
+    if (nums.some((n) => !Number.isInteger(n) || n < 0 || n > 0x10ffff))
+        return null;
+    const [vk, , char, down, mods, repeat] = nums;
+    if (vk === undefined || char === undefined || down === undefined)
+        return null;
+    if (mods === undefined || repeat === undefined)
+        return null;
+    if (vk > 0xff)
+        return null;
+    return { vk, scan: nums[1] ?? 0, char, down: down === 1, mods, repeat };
+}
+/**
+ * Split a chunk into text spans and win32-input-mode records.
+ *
+ * MATCHES ONLY `ESC [ <digits/semicolons> _`: mouse reports need `<`, paste
+ * markers end in `~`, CSI-u ends in `u`, DECRPM replies start with `?`. A
+ * `_`-terminated all-numeric-parameter sequence is therefore unambiguous in
+ * the stream this filter ever sees.
+ */
+export function splitWin32KeySequences(text) {
+    const segments = [];
+    let start = 0;
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== '\x1b' || text[index + 1] !== '[') {
+            index += 1;
+            continue;
+        }
+        let end = index + 2;
+        while (end < text.length && text[end] !== '_') {
+            const c = text[end];
+            if (c < '0' || c > '9') {
+                if (c !== ';') {
+                    end = -1;
+                    break;
+                }
+            }
+            end += 1;
+        }
+        if (end === -1 || end >= text.length) {
+            index += 1;
+            continue;
+        }
+        const record = parseRecord(text.slice(index + 2, end));
+        if (!record) {
+            index += 1;
+            continue;
+        }
+        if (index > start)
+            segments.push({ kind: 'text', text: text.slice(start, index) });
+        segments.push({ kind: 'key', record });
+        index = end + 1;
+        start = index;
+    }
+    if (start < text.length)
+        segments.push({ kind: 'text', text: text.slice(start) });
+    return segments;
+}
+/** Legacy modifier parameter (xterm): 1 + shift + 2*alt + 4*ctrl. */
+function legacyModifierParam(m) {
+    let p = 1;
+    if (m & SHIFT)
+        p += 1;
+    if (m & (LEFT_ALT | RIGHT_ALT))
+        p += 2;
+    if (m & (LEFT_CTRL | RIGHT_CTRL))
+        p += 4;
+    return p;
+}
+/** Functional keys named by vk, as (letter | tilde-code) legacy shapes. */
+const FUNCTIONAL_KEYS = new Map([
+    [0x21, { code: 5 }], // PgUp
+    [0x22, { code: 6 }], // PgDn
+    [0x23, { letter: 'F' }], // End
+    [0x24, { letter: 'H' }], // Home
+    [0x25, { letter: 'D' }], // Left
+    [0x26, { letter: 'A' }], // Up
+    [0x27, { letter: 'C' }], // Right
+    [0x28, { letter: 'B' }], // Down
+    [0x2d, { code: 2 }], // Insert
+    [0x2e, { code: 3 }], // Delete
+    [0x70, { letter: 'P' }], // F1
+    [0x71, { letter: 'Q' }], // F2
+    [0x72, { letter: 'R' }], // F3
+    [0x73, { letter: 'S' }], // F4
+    [0x74, { code: 15 }], // F5
+    [0x75, { code: 17 }], // F6
+    [0x76, { code: 18 }], // F7
+    [0x77, { code: 19 }], // F8
+    [0x78, { code: 20 }], // F9
+    [0x79, { code: 21 }], // F10
+    [0x7a, { code: 23 }], // F11
+    [0x7b, { code: 24 }], // F12
+]);
+/** Emit the legacy form of a functional key under `m` modifiers. */
+function functionalLegacy(vk, m) {
+    const key = FUNCTIONAL_KEYS.get(vk);
+    if (!key)
+        return '';
+    if (m === 0) {
+        return 'letter' in key
+            ? (key.letter === 'P' || key.letter === 'Q' || key.letter === 'R' || key.letter === 'S'
+                ? `\x1bO${key.letter}`
+                : `\x1b[${key.letter}`)
+            : `\x1b[${key.code}~`;
+    }
+    const p = legacyModifierParam(m);
+    return 'letter' in key ? `\x1b[1;${p}${key.letter}` : `\x1b[${key.code};${p}~`;
+}
+/** Control code for Ctrl+letter, or the char itself when not a letter. */
+function ctrlByte(char) {
+    if (char >= 97 && char <= 122)
+        return char - 96; // a-z -> 1-26
+    if (char >= 65 && char <= 90)
+        return char - 64; // A-Z -> 1-26
+    return char;
+}
+const isPrintable = (char) => char >= 0x20 && char !== 0x7f;
+/**
+ * Translate one record to the legacy bytes the same keypress would have
+ * produced with win32-input-mode off (Enter family excepted: a modified Enter
+ * becomes the newline frame, mirroring `ENTER_SEQUENCES`).
+ */
+export function translateWin32Key(record) {
+    if (!record.down)
+        return '';
+    const m = record.mods & MODIFIER_MASK;
+    const ctrl = (m & (LEFT_CTRL | RIGHT_CTRL)) !== 0;
+    const alt = (m & (LEFT_ALT | RIGHT_ALT)) !== 0;
+    const shift = (m & SHIFT) !== 0;
+    const char = record.char === 0 ? '' : String.fromCodePoint(record.char);
+    // AltGr arrives as RightCtrl|RightAlt (or lone RightAlt) WITH the composed
+    // character already in `char`; prefixing ESC or control-translating it would
+    // break every non-US layout. Plain typing first, exotic combos never.
+    if (isPrintable(record.char) && (m === RIGHT_CTRL + RIGHT_ALT || m === RIGHT_ALT)) {
+        return char;
+    }
+    switch (record.vk) {
+        case VK_ENTER:
+            // A modified Enter NEVER submits -- same rule as `ENTER_SEQUENCES`.
+            return m === 0 ? '\r' : ENTER_NEWLINE_FRAME;
+        case VK_TAB:
+            return shift ? '\x1b[Z' : '\t';
+        case VK_ESCAPE:
+            return alt ? '\x1b\x1b' : '\x1b';
+        case VK_BACK:
+            // POST-normalisation bytes: `handleText` rewrites DEL (0x7f) to BS
+            // (0x08) for Ink, and translated records bypass that walk -- emitting
+            // the final form keeps the stream byte-identical to the baseline.
+            if (alt)
+                return '\x1b\x08';
+            return '\x08';
+        default:
+            break;
+    }
+    if (record.char !== 0 && record.char < 0x20 && record.vk !== VK_PACKET) {
+        // Ctrl combos: Windows already resolves the control character (Ctrl+C is
+        // 0x03). Alt keeps the ESC prefix; Ctrl+Alt prefixes ESC over the code.
+        if (!ctrl && !alt && !shift)
+            return char;
+        if (!ctrl && alt)
+            return `\x1b${char}`;
+        return ctrl ? `${alt ? '\x1b' : ''}${char}` : char;
+    }
+    if (isPrintable(record.char)) {
+        if (ctrl) {
+            const code = ctrlByte(record.char);
+            return `${alt ? '\x1b' : ''}${code === record.char ? char : String.fromCharCode(code)}`;
+        }
+        if (alt)
+            return `\x1b${char}`;
+        return char;
+    }
+    return functionalLegacy(record.vk, m);
+}
+/** True when `s` is a PROPER prefix of some win32-input-mode record. */
+function isWin32Prefix(s) {
+    // A bare ESC (or ESC + anything else) belongs to the Enter/mouse/paste
+    // families' hold; this family only ever extends `\x1b[` with digits and
+    // semicolons, up to but never including the `_`.
+    if (s.length < 3 || s[0] !== '\x1b' || s[1] !== '[')
+        return false;
+    for (let i = 2; i < s.length; i += 1) {
+        const c = s[i];
+        if ((c < '0' || c > '9') && c !== ';')
+            return false;
+    }
+    return true;
+}
+/**
+ * Length of the trailing run of `text` that could still complete into a
+ * win32-input-mode record, or 0. Longest match, mirroring the other families.
+ */
+export function trailingWin32PrefixLength(text) {
+    const max = Math.min(text.length, 32);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isWin32Prefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}

package/dist/session/validate-session.js

@@ -128,7 +128,9 @@ const todo = shape({
 });
 const subagent = shape({
     label: string, description: string,
-    // Old team archives predate tier; renderers already treat absence as main.
+    // OPTIONAL IN BOTH DIRECTIONS: sessions written since main-agent parity
+    // have no tier at all, and older archives may carry `main` or `fast` from
+    // the removed per-child fast dispatch. Renderers treat absence as main.
     tier: optional(enumeration('main', 'fast')),
     phase: enumeration('queued', 'starting', 'thinking', 'tool', 'waiting', 'done', 'failed', 'aborted'),
     startedAt: optional(number), endedAt: optional(number), turns: number, toolCalls: number,

package/dist/team/child-reviewer.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Per-child fast review (main-agent parity).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte.
+ *
+ * THE LEAD HAS A FAST REVIEWER; A CHILD NOW HAS ONE TOO. The requirement is
+ * that "when the main agent pulls up subagents, all subagents are as capable as
+ * the main agent", and the fast/slow cooperation is part of what the main agent
+ * has: a cheap second model periodically critiques the run and steers a
+ * `<fast_review>` block into the conversation. A child runs the lead's own
+ * model, and this module gives that run the same second opinion.
+ *
+ * WHAT IS SHARED, AND WHAT IS PER CHILD:
+ *   - SHARED: the tier resolution (`resolveFastTier` on the LIVE config), the
+ *     fail-fast review transport (`FastWiring.completeViaFastRegistry` - one
+ *     lazy registry for the whole session, the same adapter-state reuse
+ *     argument `TeamRuntime` makes about the lead's `ProviderRegistry`), and
+ *     the `fast.*` policy keys. A `/fast off` mid-dispatch therefore stops
+ *     child reviews at the same instant it stops the lead's.
+ *   - PER CHILD: one `FastReviewer` instance, its own turn-frame ring, its own
+ *     session budget, its own goal (the spec's description).
+ *
+ * THE REVIEWER'S PROTOCOL IS UNCHANGED, AND THAT IS THE POINT. `FastReviewer`
+ * steers from exactly one place (the `tool_execution_end` that brings the batch
+ * to zero), never steers into a requested abort, and proves delivery at the
+ * next `turn_start`. The two guards need host-side facts, and a child supplies
+ * them differently than the lead:
+ *
+ *   - `userSteerCount` is ALWAYS ZERO: no human can steer a child. That makes
+ *     the reviewer's `clearAllQueues` provably safe by construction (D-21).
+ *   - `isAbortRequested` comes from the HANDLE-level abort flag that
+ *     `TeamRuntime` sets BEFORE calling `agent.abort()`. Reading the agent
+ *     alone is not enough: an Esc lands as `abortAll()`, and without the flag
+ *     the reviewer would race the abort it was told about.
+ *   - `emit` and `notify` LOG INSTEAD OF RENDERING. A child has no transcript
+ *     card and no status chip; the team panel row and the dispatch report are
+ *     where a child's internals belong, and review spend is bounded by the
+ *     same `fast.reviewMaxPerSession` budget the lead obeys.
+ */
+import type { AgentEvent, AssistantMessage, LLMRequest } from '@aragon-agent/core';
+import type { ModelRole } from '../config/model-profiles.js';
+import type { CliConfig } from '../config/schema.js';
+/**
+ * The slice of a child `Agent` the reviewer needs beyond what
+ * `SubagentAgentLike` already carries. Core's `Agent` satisfies this with its
+ * own `steer` / `clearAllQueues`; a test stub satisfies it the same way.
+ */
+export interface ChildReviewerAgent {
+    subscribe(listener: (event: AgentEvent) => void): () => void;
+    steer(text: string): void;
+    clearAllQueues(): void;
+}
+/** Everything one child reviewer needs to know about its child. */
+export interface ChildReviewerRequest {
+    label: string;
+    /** The spec's description: the goal the critique judges the run against. */
+    goal: string;
+    agent: ChildReviewerAgent;
+    /** A live phase, not a terminal one - the lead's `isRunning` equivalent. */
+    isRunning: () => boolean;
+    /** Set by the HANDLE-level abort, synchronously before `agent.abort()`. */
+    isAbortRequested: () => boolean;
+}
+/** Everything the reviewer needs from the session, all of it shared. */
+export interface ChildReviewerDeps {
+    /** Read LIVE on every call - a mid-dispatch `/fast off` must reach children. */
+    getConfig: () => CliConfig;
+    hasKey: (providerId: string, role?: ModelRole) => boolean;
+    getApiKey: (providerId: string, role?: ModelRole) => string | undefined;
+    /** `FastWiring.completeViaFastRegistry` - the shared fail-fast transport. */
+    complete: (providerId: string, request: LLMRequest) => Promise<AssistantMessage>;
+    /** `FastWiring.available()` - registered AND enabled AND resolving. */
+    available: () => boolean;
+}
+export interface ChildReviewerHandle {
+    dispose(): void;
+}
+/**
+ * What the controller hands `subagent.ts`, so a child's reviewer is built from
+ * the lead's own wiring rather than a second tier resolver.
+ *
+ * `active` AND `create` ARE SEPARATE ON PURPOSE: the child's system prompt
+ * must be composed BEFORE the agent exists, and `create` needs the agent. The
+ * two must answer the same question at the same instant, so both derive from
+ * `FastWiring.available() && config.fast.review` and the caller reads `active`
+ * once per child.
+ */
+export interface ChildReviewProvider {
+    /** Whether per-child review is live RIGHT NOW (tier live AND `fast.review`). */
+    active: () => boolean;
+    /** The resolved fast model id, for the child's `<fast_tier>` prompt block. */
+    modelId: () => string;
+    /** Build one reviewer for a child; `undefined` when not active. */
+    create: (req: ChildReviewerRequest) => ChildReviewerHandle | undefined;
+}
+/**
+ * Build one reviewer for one child, or `undefined` when the session has no
+ * live review to give it.
+ *
+ * `undefined` RATHER THAN A NO-OP REVIEWER, for the same reason
+ * `createChildContextManager` declines: the caller then wires nothing at all,
+ * and a session with the fast tier off builds the child it always built.
+ */
+export declare function createChildReviewer(req: ChildReviewerRequest, deps: ChildReviewerDeps): ChildReviewerHandle | undefined;

package/dist/team/child-reviewer.js

@@ -0,0 +1,117 @@
+/**
+ * Per-child fast review (main-agent parity).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte.
+ *
+ * THE LEAD HAS A FAST REVIEWER; A CHILD NOW HAS ONE TOO. The requirement is
+ * that "when the main agent pulls up subagents, all subagents are as capable as
+ * the main agent", and the fast/slow cooperation is part of what the main agent
+ * has: a cheap second model periodically critiques the run and steers a
+ * `<fast_review>` block into the conversation. A child runs the lead's own
+ * model, and this module gives that run the same second opinion.
+ *
+ * WHAT IS SHARED, AND WHAT IS PER CHILD:
+ *   - SHARED: the tier resolution (`resolveFastTier` on the LIVE config), the
+ *     fail-fast review transport (`FastWiring.completeViaFastRegistry` - one
+ *     lazy registry for the whole session, the same adapter-state reuse
+ *     argument `TeamRuntime` makes about the lead's `ProviderRegistry`), and
+ *     the `fast.*` policy keys. A `/fast off` mid-dispatch therefore stops
+ *     child reviews at the same instant it stops the lead's.
+ *   - PER CHILD: one `FastReviewer` instance, its own turn-frame ring, its own
+ *     session budget, its own goal (the spec's description).
+ *
+ * THE REVIEWER'S PROTOCOL IS UNCHANGED, AND THAT IS THE POINT. `FastReviewer`
+ * steers from exactly one place (the `tool_execution_end` that brings the batch
+ * to zero), never steers into a requested abort, and proves delivery at the
+ * next `turn_start`. The two guards need host-side facts, and a child supplies
+ * them differently than the lead:
+ *
+ *   - `userSteerCount` is ALWAYS ZERO: no human can steer a child. That makes
+ *     the reviewer's `clearAllQueues` provably safe by construction (D-21).
+ *   - `isAbortRequested` comes from the HANDLE-level abort flag that
+ *     `TeamRuntime` sets BEFORE calling `agent.abort()`. Reading the agent
+ *     alone is not enough: an Esc lands as `abortAll()`, and without the flag
+ *     the reviewer would race the abort it was told about.
+ *   - `emit` and `notify` LOG INSTEAD OF RENDERING. A child has no transcript
+ *     card and no status chip; the team panel row and the dispatch report are
+ *     where a child's internals belong, and review spend is bounded by the
+ *     same `fast.reviewMaxPerSession` budget the lead obeys.
+ */
+import { getLogger } from '../logging/logger.js';
+import { resolveFastTier } from '../fast/resolve.js';
+import { FastReviewer } from '../fast/reviewer.js';
+/**
+ * A snapshot for the reviewer's self-disable announcement. The lead's
+ * `FastWiring.snapshot()` builds the same shape from its own reviewer; a child
+ * has no wiring, so this builds it from the reviewer the module itself holds.
+ *
+ * `pricingUnknown` is FALSE because the child reviewer never prices anything:
+ * it logs counts, not currency, and an unpriced model id therefore cannot lie
+ * here the way it can on the lead's status line (C-11).
+ */
+function buildSnapshot(reviewer, tier) {
+    return {
+        live: tier.ok,
+        selfDisabled: reviewer?.isSelfDisabled() ?? false,
+        model: tier.ok ? tier.ref.modelId : '',
+        sameAsMain: tier.ok ? tier.sameAsMain : false,
+        reviews: reviewer?.reviewCount() ?? 0,
+        reviewBudget: reviewer?.budgetLimit() ?? 0,
+        budgetReached: reviewer?.isBudgetReached() ?? false,
+        usage: reviewer?.sessionUsage() ?? { inputTokens: 0, outputTokens: 0 },
+        pricingUnknown: false,
+        inFlight: reviewer?.isReviewInFlight() ?? false,
+    };
+}
+/**
+ * Build one reviewer for one child, or `undefined` when the session has no
+ * live review to give it.
+ *
+ * `undefined` RATHER THAN A NO-OP REVIEWER, for the same reason
+ * `createChildContextManager` declines: the caller then wires nothing at all,
+ * and a session with the fast tier off builds the child it always built.
+ */
+export function createChildReviewer(req, deps) {
+    // GATED ON THE SAME THREE FACTS THE LEAD'S REVIEWER IS: the wiring is live
+    // (`available()`), the policy allows reviews (`fast.review`), and the tier
+    // resolves against the LIVE config. Re-checked, never snapshotted, so a
+    // mid-dispatch `/fast off` or a settings-screen model edit reaches the next
+    // child even when it cannot stop one already running.
+    const tier = resolveFastTier(deps.getConfig(), deps.hasKey);
+    if (!deps.available() || !deps.getConfig().fast.review || !tier.ok)
+        return undefined;
+    const log = getLogger().child('fast');
+    let reviewer = null;
+    const built = new FastReviewer({
+        subscribe: (listener) => req.agent.subscribe(listener),
+        complete: deps.complete,
+        steer: (text) => req.agent.steer(text),
+        isRunning: req.isRunning,
+        isAbortRequested: req.isAbortRequested,
+        userSteerCount: () => 0,
+        clearAllQueues: () => req.agent.clearAllQueues(),
+        getTier: () => resolveFastTier(deps.getConfig(), deps.hasKey),
+        getConfig: () => deps.getConfig().fast,
+        available: () => deps.available() && resolveFastTier(deps.getConfig(), deps.hasKey).ok,
+        getApiKey: (providerId) => deps.getApiKey(providerId, 'fast'),
+        emit: (event) => {
+            log.info('child_review', { label: req.label, type: event.type });
+        },
+        snapshot: () => buildSnapshot(reviewer, tier),
+        // A CHILD HAS NO TRANSCRIPT. The lead's warnings ride `notify` into a card
+        // the user reads; the same text from a background worker would claim the
+        // user's attention for an agent they cannot see. It is logged instead.
+        notify: (level, text) => {
+            log.warn('child_review_notice', { label: req.label, level, text });
+        },
+    });
+    reviewer = built;
+    built.setGoal(req.goal);
+    log.info('child_review_attached', {
+        label: req.label,
+        model: tier.ref.modelId,
+        reviewEveryTurns: deps.getConfig().fast.reviewEveryTurns,
+    });
+    return { dispose: () => built.dispose() };
+}