@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/ui/layout/virtual-window.js

@@ -0,0 +1,308 @@
+/**
+ * Viewport virtualisation maths (tui-render-performance L3 / R1). Pure,
+ * React-free, unit-tested.
+ *
+ * THE STRUCTURAL FIX. Ink's `renderNodeToOutput` has no early-out for clipped
+ * subtrees: for every `ink-text` node it runs `squashTextNodes`, `widestLine`
+ * and possibly `wrapText` — all O(chars) — and `Output.get()` then evaluates
+ * `widestLine` a SECOND time before it is allowed to skip an out-of-clip
+ * operation. A clipped 50 000-character entry therefore costs two full string
+ * scans per frame and buys nothing. Bounding the ENTRY COUNT (`transcriptWindow`)
+ * never bounded that, because one entry can be fifty thousand lines.
+ *
+ * So entries outside the visible band are not mounted at all. They are replaced
+ * by two spacer boxes whose heights come from a height cache, which makes the
+ * per-frame cost O(visible rows) instead of O(characters ever produced).
+ *
+ * V-4 — `offset` counts rows FROM THE BOTTOM (`layout/scroll.ts:1-13`), and that
+ * is what makes virtualisation safe here for free: a height correction on an
+ * entry ABOVE the viewport changes the content height and therefore
+ * `overflowLines`, while `offset` — and hence what the user is looking at — is
+ * unchanged. No scroll-anchoring compensation pass is required. Do NOT
+ * "simplify" `offset` to count from the top.
+ */
+import { FAST_LIMITS } from '../../fast/limits.js';
+import { GUTTER_WIDTH } from './Gutter.js';
+export const VIRTUAL_LIMITS = {
+    /**
+     * Entries kept mounted on each side of the visible band.
+     *
+     * V-2 — must stay `>= 2`, so a one-row scroll can never expose an entry whose
+     * height has never been measured at the very edge of the viewport.
+     */
+    overscan: 2,
+    /** Height-cache ceiling (LRU). Four thousand numbers, not four thousand strings. */
+    heightEntries: 4096,
+};
+/**
+ * A cheap content version: it changes exactly when the rendered content does.
+ *
+ * DERIVED, NEVER HASHED. Hashing a 256 KiB string once per entry per frame would
+ * recreate the very cost this module exists to remove, so every field below is
+ * an O(1) read of a length or a scalar.
+ *
+ * I-L3-1 — this must change whenever the rendered output changes. The only lossy
+ * case is a same-LENGTH text replacement, which the reducer cannot produce: all
+ * text fields are append-only (`appendBounded` only ever elides the middle,
+ * which changes the length). A future NON-APPEND mutation MUST extend the
+ * revision, or the entry freezes at a stale height AND a stale rendered subtree
+ * with nothing anywhere reporting it. `virtual-window.test.ts` enumerates every
+ * kind against every mutating action.
+ */
+export function entryRevision(entry) {
+    switch (entry.kind) {
+        case 'user':
+            return 'u';
+        case 'notice':
+            return 'n';
+        // `thinkingMs` is O(1) and it CHANGES THE ROW: sealing the clock turns
+        // `* thought` into `* thought for 12s`, and with thinking hidden that row is
+        // the entry's whole rendered height.
+        case 'assistant':
+            return `a${entry.text.length}.${entry.thinking?.length ?? 0}.${entry.streaming ? 1 : 0}.${entry.aborted ? 1 : 0}.${entry.thinkingMs ?? -1}`;
+        // `patch.lineCount` is PRECOMPUTED for exactly this term: summing
+        // `hunks[].lines.length` per entry per frame is the cost the height cache
+        // exists to remove, and I-L3-1 forbids hashing.
+        // `liveSeq` IS A COUNTER AND NOT `live.length`, and that is precisely the
+        // NON-APPEND mutation I-L3-1 above says must extend the revision: a
+        // fixed-size tail evicting its oldest row while appending a new one of the
+        // same width leaves the joined length unchanged, so a length term would go
+        // on matching while the card's content changed under it.
+        //
+        // SIX TERMS NOW, the longest revision in this file (P2-12). Still O(1) per
+        // entry per frame, which is the property I-L3-1 requires -- but the next
+        // field makes it seven, and a term that is not O(1) would put the cost this
+        // module exists to remove back on every frame.
+        case 'tool':
+            return `t${entry.status}.${entry.argsRaw.length}.${entry.preview?.length ?? 0}.${entry.durationMs ?? -1}.${entry.patch?.lineCount ?? -1}.${entry.liveSeq ?? -1}`;
+        case 'team':
+            return `m${entry.active ? 1 : 0}.${entry.runs.length}.${entry.runs
+                .map((r) => r.phase[0])
+                .join('')}.${entry.runs.reduce((acc, r) => acc + r.toolCalls, 0)}`;
+        case 'todo':
+            return `d${entry.live ? 1 : 0}.${entry.doneCount}.${entry.total}.${entry.items.length}`;
+        /**
+         * The retry card is ONE ROW IN EVERY PHASE, so its revision carries the phase
+         * and the counter but deliberately NOT the countdown: `resumeAt` changes the
+         * rendered SECONDS once a second while the height stays 1, and folding it in
+         * here would invalidate the height cache 30 times per backoff to re-measure a
+         * number that cannot change the answer.
+         *
+         * `phase` and `attempt` ARE in, because they change the row's text and a stale
+         * measurement would be wrong in a way nothing reports (I-L3-1).
+         */
+        case 'retry':
+            return `r${entry.phase}.${entry.attempt}.${entry.maxRetries}`;
+        /**
+         * `status`, `live` and the TEXT LENGTH, because all three change the rows the
+         * card draws: `advice` renders a body, everything else renders one line, and
+         * the body's length decides how many rows it wraps to. `durationMs` is in the
+         * header, which is `wrap="truncate"`, so it can never change the height.
+         */
+        case 'fast':
+            return `f${entry.status}.${entry.live ? 1 : 0}.${entry.text?.length ?? 0}.${entry.detail?.length ?? 0}`;
+        default:
+            return 'x';
+    }
+}
+/**
+ * The height-cache key.
+ *
+ * V-5 — `cols` is part of the key, so a resize invalidates every entry. The
+ * frame after a resize renders from estimates and re-measures lazily: one
+ * reflow, no crash, no stale layout.
+ *
+ * `flags` carries the render-affecting switches that are neither per-entry nor
+ * part of `density` — today only `thinkingVisible` (Ctrl+T). It is a parameter
+ * rather than a fifth positional scalar so a future switch costs one character
+ * at the call site instead of a signature change at four.
+ */
+export function heightKey(entry, cols, expanded, density, flags = '') {
+    return `${entry.id}|${entryRevision(entry)}|${cols}|${expanded ? 1 : 0}|${density}|${flags}`;
+}
+/** Rows a string occupies at `usable` columns, wrapping included. At least 1. */
+function wrappedRows(text, usable) {
+    const width = Math.max(1, usable);
+    let rows = 0;
+    let lineLen = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            rows += Math.max(1, Math.ceil(lineLen / width));
+            lineLen = 0;
+        }
+        else {
+            lineLen += 1;
+        }
+    }
+    return rows + Math.max(1, Math.ceil(lineLen / width));
+}
+/** Collapsed preview rows in `ToolCard`; duplicated as a NUMBER, not imported. */
+const TOOL_COLLAPSED_LINES = 8;
+/** Collapsed diff rows in `DiffView`; duplicated for the same reason as above. */
+const DIFF_COLLAPSED_LINES = 12;
+/** Live tail rows in `ToolCard`; duplicated as a NUMBER, for the same reason. */
+const TOOL_LIVE_TAIL_ROWS = 8;
+/**
+ * Pure UPPER-BOUND estimate of an entry's height, used until a real measurement
+ * exists.
+ *
+ * Upper bound rather than best guess, and deliberately so: an over-estimate
+ * makes the scroll position slightly conservative and self-corrects the frame
+ * after the entry is measured, while an under-estimate can put the newest output
+ * off the bottom of a viewport the user believes is pinned.
+ */
+export function estimateEntryRows(entry, cols, density, expanded, thinkingVisible = true) {
+    const usable = Math.max(1, cols - GUTTER_WIDTH);
+    // `separationRows` needs the PRECEDING entry, which a per-entry estimate does
+    // not have. One row is its maximum, so charging it unconditionally keeps this
+    // an upper bound (`compact` never spends it at all).
+    const separation = density === 'comfortable' ? 1 : 0;
+    switch (entry.kind) {
+        case 'user':
+            return separation + wrappedRows(entry.text, usable);
+        case 'notice':
+            return separation + wrappedRows(entry.text, usable);
+        case 'assistant': {
+            // THE PARAMETER'S `true` DEFAULT IS A FAIL-SAFE FOR A FORGOTTEN CALLER,
+            // NOT THE PLAN FOR THE ONE THERE IS (P1-6a). `Transcript.tsx` holds
+            // `thinkingVisible` as a prop and MUST pass it: with thinking hidden by
+            // default, an unpassed flag inflates every assistant entry that thought by
+            // `1 + wrappedRows(thinking)` — hundreds of rows at `thinkingLevel: high`
+            // against a real height of one. The self-correction argument does not
+            // rescue that, because an entry is only measured once `selectWindow`
+            // mounts it, and an entry estimated at 400 rows is exactly the one that
+            // never gets mounted.
+            const thinking = !entry.thinking
+                ? 0
+                : thinkingVisible
+                    ? 1 + wrappedRows(entry.thinking, usable)
+                    : // The collapsed `thought for Ns` marker is exactly one row, and it is
+                        // suppressed while the entry is still streaming (the activity line is
+                        // the live surface then).
+                        entry.streaming
+                            ? 0
+                            : 1;
+            const body = entry.text.length > 0 ? wrappedRows(entry.text, usable) : 1;
+            return separation + thinking + body + (entry.aborted ? 1 : 0);
+        }
+        case 'tool': {
+            const settled = entry.status === 'done' || entry.status === 'error';
+            // WHEN A PATCH IS PRESENT IT, NOT THE PREVIEW, IS WHAT DRAWS (§3.4): the
+            // stored preview is one line by then, so estimating from it would report a
+            // 3-row card for a 12-row diff — an UNDER-estimate, the direction this
+            // file names as unsafe.
+            if (settled && entry.patch) {
+                const rows = entry.patch.lineCount + Math.max(0, entry.patch.hunks.length - 1);
+                const shown = expanded ? rows : Math.min(rows, DIFF_COLLAPSED_LINES);
+                // card header + `+N -M` summary + rows + footer
+                return separation + 1 + 1 + shown + 1;
+            }
+            // THE ONE-LINE `if (!entry.preview || !settled)` THIS REPLACES COVERED TWO
+            // CASES, and both must survive the split (P1-4): not settled, and settled
+            // with nothing to draw (an aborted call, a tool that returned an empty
+            // string). A `!settled` block alone would drop the second into
+            // `wrappedRows(entry.preview, usable)` with `undefined`.
+            if (!settled) {
+                const live = entry.live?.length ?? 0;
+                if (live === 0)
+                    return separation + 1;
+                // Header + tail rows + the unconditional stall/`(running)` footer row.
+                //
+                // ROWS ARE COUNTED, NOT WRAPPED, which is legitimate only because every
+                // live row is rendered `wrap="truncate"` AND clipped at
+                // `LIVE_ROW_MAX_CHARS` on the way into the store -- the same argument
+                // `DiffView.tsx:6-11` makes for itself, and the same coupling: if a
+                // future change lets a live row wrap, this silently UNDER-counts, the
+                // direction this file names as the one the layout cannot absorb.
+                return separation + 1 + Math.min(live, TOOL_LIVE_TAIL_ROWS) + 1;
+            }
+            if (!entry.preview) {
+                return separation + 1;
+            }
+            const lines = wrappedRows(entry.preview, usable);
+            const shown = expanded ? lines : Math.min(lines, TOOL_COLLAPSED_LINES);
+            // header + body + the `+N lines (Ctrl+O)` / `(Ctrl+O to collapse)` footer
+            return separation + 1 + shown + 1;
+        }
+        case 'team':
+            return separation + 1 + entry.runs.length + (expanded ? entry.runs.length * 3 + 1 : 1);
+        case 'todo':
+            return separation + 1 + entry.items.length;
+        // ONE ROW, ALWAYS. The card is `wrap="truncate"` in every phase, so this is an
+        // exact height rather than an upper bound.
+        case 'retry':
+            return separation + 1;
+        // ADDING THE CASE TO ONLY ONE OF THIS FILE'S TWO SWITCHES YIELDS A
+        // TRANSCRIPT WHOSE SCROLL ARITHMETIC DISAGREES WITH WHAT IT DREW, which
+        // manifests as drift rather than as an error (RV-13). Header row, then
+        // either the wrapped critique (clamped to `cardTextRows`) or one status
+        // line — an upper bound, which is what this function owes its caller.
+        case 'fast': {
+            const body = entry.status === 'advice' && entry.text
+                ? Math.min(FAST_LIMITS.cardTextRows, wrappedRows(entry.text, usable))
+                : 1;
+            return separation + 1 + body;
+        }
+        default:
+            return separation + 1;
+    }
+}
+/** Choose which entries to mount, and how tall the two spacers must be. */
+export function selectWindow(input) {
+    const { entries, heightOf } = input;
+    const n = entries.length;
+    if (n === 0) {
+        return { startIndex: 0, endIndex: 0, leadingRows: 0, trailingRows: 0, totalRows: 0 };
+    }
+    const heights = new Array(n);
+    let totalRows = 0;
+    for (let i = 0; i < n; i += 1) {
+        const h = heightOf(i);
+        const rows = Number.isFinite(h) && h > 0 ? Math.floor(h) : 1;
+        heights[i] = rows;
+        totalRows += rows;
+    }
+    // A viewport of 0 is the FIRST FRAME, before `measureElement` has run. Falling
+    // back to 1 keeps the live tail mounted through it, so the first paint is real
+    // content rather than a blank rectangle that only fills in on the second.
+    const viewport = Math.max(1, Math.floor(input.viewportRows) || 0);
+    const offset = Math.max(0, Math.floor(input.offset) || 0);
+    const overscan = Math.max(VIRTUAL_LIMITS.overscan, Math.floor(input.overscan) || 0);
+    const bottom = totalRows - offset;
+    const top = bottom - viewport;
+    let start = n - 1;
+    let acc = 0;
+    for (let i = 0; i < n; i += 1) {
+        const next = acc + heights[i];
+        if (next > top) {
+            start = i;
+            break;
+        }
+        acc = next;
+    }
+    let end = n;
+    acc = 0;
+    for (let i = 0; i < n; i += 1) {
+        if (acc >= bottom) {
+            end = i;
+            break;
+        }
+        acc += heights[i];
+    }
+    start = Math.max(0, start - overscan);
+    end = Math.min(n, end + overscan);
+    // V-3 — while pinned, the LAST entry is always inside the window, whatever its
+    // height. The live tail must be real content and never a spacer, or a
+    // streaming answer renders as a growing blank rectangle.
+    if (offset <= 0)
+        end = n;
+    if (end <= start)
+        end = Math.min(n, start + 1);
+    let leadingRows = 0;
+    for (let i = 0; i < start; i += 1)
+        leadingRows += heights[i];
+    let trailingRows = 0;
+    for (let i = end; i < n; i += 1)
+        trailingRows += heights[i];
+    return { startIndex: start, endIndex: end, leadingRows, trailingRows, totalRows };
+}

package/dist/ui/live-clamp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Live-region clamp for INLINE render mode (tui-render-performance L5 / R6).
+ *
+ * Inline mode has no fixed frame, so nothing kept its live (non-`<Static>`)
+ * region shorter than the terminal. When one live entry grew taller than
+ * `stdout.rows`, Ink took the branch at `ink.js:118-123`:
+ *
+ *     if (outputHeight >= this.options.stdout.rows) {
+ *       stdout.write(clearTerminal + this.fullStaticOutput + output);
+ *     }
+ *
+ * `fullStaticOutput` accumulates EVERY `<Static>` frame of the whole session and
+ * is never trimmed, so once that branch is taken it is taken on every subsequent
+ * frame — bypassing both the `output !== lastOutput` dedupe and `throttledLog` —
+ * and the terminal receives the entire session history thirty times a second.
+ * That is a genuine hard freeze, and it is reachable today by any inline user
+ * (`--no-fullscreen`, `TERM=dumb`, CI, a short or narrow terminal) whose model
+ * writes a long answer.
+ *
+ * I-L5-1 — keeping the live region strictly below `stdout.rows` makes that
+ * branch UNREACHABLE, which is the inline analogue of `frame.ts`'s
+ * `frameHeight(r) < r` and deserves the same standing. We cannot bound Ink's
+ * `fullStaticOutput` growth (it is private and append-only); preventing the
+ * branch that WRITES it is the entire mitigation, and nothing about the memory
+ * it holds is fixed by this module.
+ *
+ * Nothing is lost, only deferred: when the entry settles it moves into
+ * `<Static>` and is printed in full.
+ */
+export interface LiveClamp {
+    text: string;
+    /** Rows dropped off the FRONT. `0` means the text was returned untouched. */
+    hiddenRows: number;
+}
+/**
+ * Keep the LAST `maxRows` rows of `text`; report how many were dropped.
+ *
+ * Rows, not wrapped display lines: this runs per frame on a streaming entry, and
+ * a wrap-aware count would need the column width and a second full scan of a
+ * string this function exists to avoid scanning twice.
+ */
+export declare function clampLiveText(text: string, maxRows: number): LiveClamp;

package/dist/ui/live-clamp.js

@@ -0,0 +1,74 @@
+/**
+ * Live-region clamp for INLINE render mode (tui-render-performance L5 / R6).
+ *
+ * Inline mode has no fixed frame, so nothing kept its live (non-`<Static>`)
+ * region shorter than the terminal. When one live entry grew taller than
+ * `stdout.rows`, Ink took the branch at `ink.js:118-123`:
+ *
+ *     if (outputHeight >= this.options.stdout.rows) {
+ *       stdout.write(clearTerminal + this.fullStaticOutput + output);
+ *     }
+ *
+ * `fullStaticOutput` accumulates EVERY `<Static>` frame of the whole session and
+ * is never trimmed, so once that branch is taken it is taken on every subsequent
+ * frame — bypassing both the `output !== lastOutput` dedupe and `throttledLog` —
+ * and the terminal receives the entire session history thirty times a second.
+ * That is a genuine hard freeze, and it is reachable today by any inline user
+ * (`--no-fullscreen`, `TERM=dumb`, CI, a short or narrow terminal) whose model
+ * writes a long answer.
+ *
+ * I-L5-1 — keeping the live region strictly below `stdout.rows` makes that
+ * branch UNREACHABLE, which is the inline analogue of `frame.ts`'s
+ * `frameHeight(r) < r` and deserves the same standing. We cannot bound Ink's
+ * `fullStaticOutput` growth (it is private and append-only); preventing the
+ * branch that WRITES it is the entire mitigation, and nothing about the memory
+ * it holds is fixed by this module.
+ *
+ * Nothing is lost, only deferred: when the entry settles it moves into
+ * `<Static>` and is printed in full.
+ */
+/**
+ * Keep the LAST `maxRows` rows of `text`; report how many were dropped.
+ *
+ * Rows, not wrapped display lines: this runs per frame on a streaming entry, and
+ * a wrap-aware count would need the column width and a second full scan of a
+ * string this function exists to avoid scanning twice.
+ */
+export function clampLiveText(text, maxRows) {
+    if (!Number.isFinite(maxRows) || maxRows <= 0)
+        return { text: '', hiddenRows: rowCount(text) };
+    const keep = Math.floor(maxRows);
+    // Cheap reject: a string with fewer than `keep` newlines cannot have more than
+    // `keep` rows, and this is the path every ordinary entry takes.
+    let newlines = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            newlines += 1;
+    }
+    if (newlines + 1 <= keep)
+        return { text, hiddenRows: 0 };
+    // Walk back from the end to the `keep`-th newline rather than splitting the
+    // whole string: the point of the clamp is to stop touching the head at all.
+    let cut = text.length;
+    let seen = 0;
+    for (let i = text.length - 1; i >= 0; i -= 1) {
+        if (text.charCodeAt(i) === 10) {
+            seen += 1;
+            if (seen === keep) {
+                cut = i + 1;
+                break;
+            }
+        }
+    }
+    return { text: text.slice(cut), hiddenRows: newlines + 1 - keep };
+}
+function rowCount(text) {
+    if (text.length === 0)
+        return 0;
+    let n = 1;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            n += 1;
+    }
+    return n;
+}

package/dist/ui/markdown-blocks.d.ts

@@ -15,11 +15,13 @@ export interface HeadingBlock {
 export interface RuleBlock {
     kind: 'rule';
 }
+/** Column alignment carried by a table's `|---|:--:|` divider row. */
+export type Align = 'left' | 'right' | 'center';
 export interface TableBlock {
     kind: 'table';
     /** Already column-aligned; render as plain monospace rows. */
     rows: string[][];
-    align: ('left' | 'right' | 'center')[];
+    align: Align[];
 }
 export declare function parseHeading(line: string): HeadingBlock | null;
 export declare function isRule(line: string): boolean;
@@ -34,6 +36,28 @@ export declare function tableAlignments(dividerLine: string): TableBlock['align'
  * on any realistic terminal.
  */
 export declare function formatTable(rows: string[][], align: TableBlock['align']): string[];
+/**
+ * One parsed top-level block.
+ *
+ * `line` is deliberately UNPARSED: heading / rule / quote / bullet detection is
+ * a handful of regexes over one short string and is done at render time, where
+ * the theme and the glyph set live. Caching a themed element instead would make
+ * `/theme` a no-op until the cache evicted (K-5).
+ */
+export type MdBlock = {
+    kind: 'code';
+    code: string;
+    lang: string;
+} | {
+    kind: 'table';
+    rows: string[][];
+    align: Align[];
+} | {
+    kind: 'line';
+    text: string;
+};
+/** Split a document into fenced code, pipe tables, and everything else. */
+export declare function parseMarkdownBlocks(text: string): MdBlock[];
 export type InlineSpan = {
     kind: 'text';
     text: string;

package/dist/ui/markdown-blocks.js

@@ -73,6 +73,49 @@ export function formatTable(rows, align) {
         .join('  ')
         .trimEnd());
 }
+/** A fence line: ```` ```lang ```` or a bare ```` ``` ````. */
+const FENCE_RE = /^```(\w*)\s*$/;
+/** Split a document into fenced code, pipe tables, and everything else. */
+export function parseMarkdownBlocks(text) {
+    const lines = text.split('\n');
+    const blocks = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        const fence = FENCE_RE.exec(line.trim());
+        if (fence) {
+            const lang = fence[1] || '';
+            const codeLines = [];
+            i += 1;
+            while (i < lines.length && !FENCE_RE.test((lines[i] ?? '').trim())) {
+                codeLines.push(lines[i] ?? '');
+                i += 1;
+            }
+            i += 1; // skip the closing fence
+            blocks.push({ kind: 'code', code: codeLines.join('\n'), lang });
+            continue;
+        }
+        // A pipe row followed by a divider row starts a table; consume the run.
+        const headerCells = parseTableRow(line);
+        if (headerCells && i + 1 < lines.length && isTableDivider(lines[i + 1] ?? '')) {
+            const align = tableAlignments(lines[i + 1] ?? '');
+            const rows = [headerCells];
+            i += 2;
+            while (i < lines.length) {
+                const cells = parseTableRow(lines[i] ?? '');
+                if (!cells)
+                    break;
+                rows.push(cells);
+                i += 1;
+            }
+            blocks.push({ kind: 'table', rows, align });
+            continue;
+        }
+        blocks.push({ kind: 'line', text: line });
+        i += 1;
+    }
+    return blocks;
+}
 const CODE_RE = /`[^`]+`/g;
 const EMPHASIS_RE = /(\*\*[^*]+\*\*|~~[^~]+~~|\*[^*]+\*)/g;
 /**

package/dist/ui/overlays/HelpOverlay.js

@@ -10,10 +10,10 @@ function keyRows(times) {
         ['Shift+Tab', 'Toggle plan mode (same as /plan)'],
         [`Ctrl+C ${times}2`, 'Exit'],
         ['Ctrl+L', 'Redraw the frame'],
-        ['Ctrl+T', 'Toggle thinking blocks'],
+        ['Ctrl+T', 'Show/hide thinking (off by default)'],
         ['PgUp / PgDn', 'Scroll a page (transcript, or this overlay)'],
         ['Shift+Up / Shift+Down', 'Scroll the transcript a line (full-screen mode)'],
-        ['Wheel', 'Scroll the transcript (over the input box: prompt history)'],
+        ['Wheel', 'Scroll the transcript (or the open overlay)'],
         ['Shift+Wheel', 'Scroll the transcript a page'],
         ['Up / Down', 'Prompt history (empty input)'],
     ];
@@ -27,6 +27,7 @@ const COMMANDS = [
     ['/thinking <level>', 'Set thinking level'],
     ['/max-tokens [n|auto]', 'Output token cap; no argument reports the effective one'],
     ['/team [on|off|max n]', 'Team subagents: status, switch, fan-out width'],
+    ['/fast [on|off|model|review]', 'Fast model tier: status, switch, model, review cadence'],
     [
         '/todo [on|off|panel|follow|clear|continue]',
         'Todo planning: status, switches, the rail, follow-through',
@@ -67,6 +68,16 @@ const TEAM_ROWS = [
     ['--team / --no-team', 'Start a session with team mode on or off (also ARAGON_TEAM=0)'],
     ['team_send / team_wait', 'How subagents message each other; 6 each, one every 15s'],
 ];
+const FAST_ROWS = [
+    ['/fast', 'Status: on/off, the model, the cadence, and this session\'s totals'],
+    ['/fast on | off', 'Switch the tier for this session (and save it)'],
+    ['/fast model <id>', 'Set the fast model; accepts provider:model'],
+    ['/fast same', 'Run the fast tier on the main model'],
+    ['/fast review <n> | off', 'Turns between automatic reviews, or turn them off'],
+    ['/fast delegate on | off', 'Allow model:"fast" on task subagents'],
+    ['--fast / --no-fast', 'Start a session with the tier on or off (also ARAGON_FAST=1)'],
+    ['<fast_review>', 'An automated second opinion from the fast model - advice, not the user'],
+];
 /** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
 export function helpRows(theme, caps) {
     const glyphs = pickGlyphs(caps);
@@ -85,6 +96,9 @@ export function helpRows(theme, caps) {
     rows.push(section('Team subagents'));
     for (const [c, d] of TEAM_ROWS)
         rows.push(pair(c, d));
+    rows.push(section('Fast model tier'));
+    for (const [c, d] of FAST_ROWS)
+        rows.push(pair(c, d));
     rows.push(section('Skills'));
     for (const [c, d] of SKILL_ROWS)
         rows.push(pair(c, d));