@aragon-agent/cli 0.5.8 → 0.5.9

package/dist/ui/layout/AppShell.d.ts

@@ -11,7 +11,6 @@
  */
 import React from 'react';
 import { type RenderMode } from './frame.js';
-import { type FrameGeometry } from './regions.js';
 export interface AppShellProps {
     mode: RenderMode;
     rows: number;
@@ -21,11 +20,10 @@ export interface AppShellProps {
     /**
      * The live subagent roster (team-subagents §6.1), or nothing.
      *
-     * IT RENDERS INSIDE `bottomRef` IN THE FULL-SCREEN BRANCH, and it has to
-     * (I-10): `geometryRef.current.bottom` is MEASURED from that box, and the
-     * wheel router uses it to decide whether a notch belongs to the transcript or
-     * to prompt history. A panel rendered above the measured box would make the
-     * composer band boundary stale the instant a dispatch started.
+     * IT RENDERS IN THE BOTTOM CHROME OF THE FULL-SCREEN BRANCH, above `toast` and
+     * below the viewport: the roster is transient status about the run in progress,
+     * so it belongs with the other transient rows rather than inside the scrolling
+     * transcript, where it would be interleaved with history and scroll away.
      */
     team?: React.ReactNode;
     /**
@@ -36,10 +34,11 @@ export interface AppShellProps {
      * primitive and has no business knowing what a todo is. `team` above already
      * leaks content vocabulary in here; there is no reason to repeat it.
      *
-     * IT MUST NOT BE RENDERED INSIDE `bottomRef` (C-6 / I-4). That box is MEASURED
-     * and the wheel router reads the composer band boundary from it; a column
-     * added there would inflate the measurement and start routing transcript
-     * scrolls into prompt history.
+     * IT MUST BE RENDERED IN THE MIDDLE BAND, BESIDE THE VIEWPORT (C-6 / I-4) —
+     * that is what makes it a rail rather than another row of bottom chrome. Moved
+     * down into the bottom box it would stop being a column beside the transcript
+     * and start eating viewport height, growing and shrinking the transcript every
+     * time the list changed length.
      *
      * The INLINE branch does not include it at all — a structural guarantee rather
      * than a promise that the caller passes `null` (non-goal 4).
@@ -56,21 +55,13 @@ export interface AppShellProps {
      * both on screen showing the same list (I-6). Fullscreen has the rail; that is
      * the whole design.
      *
-     * It sits between `viewport` and `team`, i.e. OUTSIDE the measured box in the
-     * other branch — but inline has no measured box at all (`geometryRef` is set
-     * to `UNMEASURED_GEOMETRY` there), so there is nothing here to invalidate.
+     * It sits between `viewport` and `team`, mirroring where the rail sits in the
+     * other branch: last thing above the bottom chrome, so the strip and the
+     * roster read top-to-bottom in the same order in both modes.
      */
     strip?: React.ReactNode;
     toast: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
-    /**
-     * Where the wheel router reads the composer band boundary from (mouse-wheel
-     * §4.5). Written in a LAYOUT EFFECT to a MUTABLE REF, never to state: the
-     * measurement happens on every commit, and routing it through `setState`
-     * would add a re-render to the streaming path for a value nothing renders
-     * (R-7).
-     */
-    geometryRef?: React.MutableRefObject<FrameGeometry>;
 }
-export declare function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, geometryRef, }: AppShellProps): React.ReactElement;
+export declare function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, }: AppShellProps): React.ReactElement;

package/dist/ui/layout/AppShell.js

@@ -1,44 +1,9 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-/**
- * AppShell (spec §4.3) — the frame that makes R2 true.
- *
- * In `fullscreen` the root box has a FIXED height of `frameHeight(rows)` and the
- * middle viewport is the only `flexGrow` child, so the bottom chrome (toast /
- * composer / status bar) is physically the last thing on the screen from the
- * very first frame — empty session, long session, mid-scroll, overlay open.
- *
- * In `inline` the same children are emitted in the same order with no height
- * constraint, i.e. byte-for-byte the v0.2.0 document-flow behavior.
- */
-import { useLayoutEffect, useRef } from 'react';
-import { Box, measureElement } from 'ink';
+import { Box } from 'ink';
 import { frameHeight } from './frame.js';
-import { UNMEASURED_GEOMETRY } from './regions.js';
-export function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, geometryRef, }) {
-    const bottomRef = useRef(null);
-    // DECLARED ABOVE THE INLINE EARLY RETURN, and it has to stay there: React
-    // keys hooks by call order, and a hook that only runs in one mode changes
-    // that order between modes.
-    //
-    // Ink computes yoga layout in `onRender`, which React runs BEFORE layout
-    // effects, so this reflects the commit that just happened — the same
-    // mechanism `ScrollViewport` already relies on.
-    useLayoutEffect(() => {
-        if (!geometryRef)
-            return;
-        if (mode === 'inline' || !bottomRef.current) {
-            geometryRef.current = UNMEASURED_GEOMETRY;
-            return;
-        }
-        geometryRef.current = {
-            // 1 in the alternate screen — see the note on `FrameGeometry.top`.
-            top: 1,
-            height: frameHeight(rows),
-            bottom: measureElement(bottomRef.current).height,
-        };
-    });
+export function AppShell({ mode, rows, cols, header, viewport, team, rail, strip, toast, composer, status, }) {
     if (mode === 'inline') {
         return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, strip, team, toast, composer, status] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), rail] }), _jsxs(Box, { ref: bottomRef, flexDirection: "column", flexShrink: 0, children: [team, toast, composer, status] })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsxs(Box, { flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), rail] }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [team, toast, composer, status] })] }));
 }

package/dist/ui/layout/virtual-window.d.ts

@@ -73,7 +73,7 @@ export declare function heightKey(entry: Entry, cols: number, expanded: boolean,
  * 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 declare function estimateEntryRows(entry: Entry, cols: number, density: DensityMode, expanded: boolean): number;
+export declare function estimateEntryRows(entry: Entry, cols: number, density: DensityMode, expanded: boolean, thinkingVisible?: boolean): number;
 export interface WindowSelection {
     /** First mounted entry, inclusive. */
     startIndex: number;

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

@@ -21,6 +21,7 @@
  * 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 = {
     /**
@@ -54,16 +55,52 @@ export function entryRevision(entry) {
             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}`;
+            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}`;
+            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';
     }
@@ -101,6 +138,10 @@ function wrappedRows(text, usable) {
 }
 /** 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.
@@ -110,7 +151,7 @@ const TOOL_COLLAPSED_LINES = 8;
  * 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) {
+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
@@ -122,12 +163,60 @@ export function estimateEntryRows(entry, cols, density, expanded) {
         case 'notice':
             return separation + wrappedRows(entry.text, usable);
         case 'assistant': {
-            const thinking = entry.thinking ? 1 + wrappedRows(entry.thinking, usable) : 0;
+            // 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': {
-            if (!entry.preview || (entry.status !== 'done' && entry.status !== 'error')) {
+            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);
@@ -139,6 +228,21 @@ export function estimateEntryRows(entry, cols, density, expanded) {
             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;
     }

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));

package/dist/ui/overlays/SettingsScreen.d.ts

@@ -9,6 +9,7 @@
  */
 import React from 'react';
 import { type ThinkingLevel } from '@aragon-agent/core';
+import { type FastConfig } from '../../config/schema.js';
 import { type LogLevelName } from '../../logging/levels.js';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
@@ -17,6 +18,22 @@ export interface SettingsValues {
     model: string;
     baseUrl: string;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Whether the transcript draws the reasoning (agent-activity-presentation
+     * §4.3). `'on' | 'off'` rather than a boolean because this screen edits an
+     * enum row and reads it back as one; `App` converts at both ends.
+     */
+    showThinking: 'on' | 'off';
+    /**
+     * Whether a running tool card draws a live output tail
+     * (agent-activity-presentation-live §4.1). `'on' | 'off'` for the reason its
+     * neighbour records: this screen edits an enum row and reads it back as one.
+     *
+     * PERSIST-ONLY, unlike `showThinking`. The store is allocated in
+     * `AgentController`'s constructor and there is no setter, so this row takes
+     * effect on the next launch -- which is also what manual row 8 asks for.
+     */
+    liveToolOutput: 'on' | 'off';
     maxTokens: string;
     apiKey: string;
     /**
@@ -25,6 +42,21 @@ export interface SettingsValues {
      * credentials on disk cannot be flipped by a stray arrow key.
      */
     logLevel: LogLevelName;
+    /**
+     * The fast tier (fast-model-tier §4.5, extended by the hardening round §4.4).
+     *
+     * FIVE ROWS, and only the first is always meaningful — the other four
+     * describe a tier that may not be on. They are `string` rather than their
+     * config types because this screen edits TEXT: `fastReview` accepts a number
+     * or `off`, and a typo must change nothing rather than resolve to a default
+     * (the discipline `maxTokens` already follows here).
+     */
+    fastEnabled: 'on' | 'off';
+    fastModel: string;
+    fastProvider: string;
+    fastReview: string;
+    /** The session review budget. `fastReview` is the PACE, this is the TOTAL. */
+    fastReviewBudget: string;
 }
 interface SettingsScreenProps {
     initial: SettingsValues;
@@ -39,7 +71,56 @@ interface SettingsScreenProps {
     theme: Theme;
     caps: TermCapabilities;
     onSave: (values: SettingsValues) => void;
+    /**
+     * `API retries` READ-ONLY row (llm-api-retry-backoff §6.9), e.g. `10` or `off`.
+     *
+     * A STRING FROM `App`, NOT A `SettingsValues` FIELD, and that distinction is the
+     * whole design: `SettingsValues` is what Enter WRITES, and routing retry through
+     * it would mean nine more editable rows (or one row whose Enter silently
+     * rewrote a section it does not own). `/retry` is the discoverable control;
+     * this row exists so "is it on, and how many" is answerable without leaving the
+     * screen. Absent = omit the row entirely.
+     */
+    retrySummary?: string;
 }
+/**
+ * The derived, non-editable line under the five fast rows — the sibling of
+ * `effectiveCapLine`, and it exists for the same reason (§4.5).
+ *
+ * A SETTINGS SCREEN THAT LETS A USER SWITCH A TIER ON AND GIVES NO SIGNAL THAT
+ * IT CANNOT RESOLVE is the failure `effectiveCapLine` was added to fix for
+ * `maxTokens`, one screen later. `keyFor` is the same resolver the controller
+ * uses, so this line and the runtime cannot disagree.
+ *
+ * IT DOES NOT TAKE `fastReviewBudget` AND MUST NOT (§4.4 part 5): this line
+ * describes what the tier IS, not what it is allowed to spend.
+ */
+export declare function fastTierLine(values: Pick<SettingsValues, 'provider' | 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview'>, hasKey: (providerId: string) => boolean): string;
+/**
+ * The five editable fast rows, as a config patch (§4.5 / hardening §4.4).
+ *
+ * PURE AND EXPORTED so `App`'s save handler holds no parsing of its own, and so
+ * the round trip `fastSettingsFrom(config)` -> edit -> `readFastSettings` can be
+ * tested without a terminal.
+ *
+ * A TYPO IN `fastReview` CHANGES NOTHING — the `review` / `reviewEveryTurns`
+ * keys are simply omitted from the patch, so `clampFastConfig`'s merge keeps
+ * whatever was there. That is the `Max tokens` discipline this screen already
+ * follows, and the alternative (resolving a typo to the default) silently
+ * discards the cadence the user actually set. `fastReviewBudget` follows the
+ * same rule; an out-of-range NUMBER is passed through to `clampFastConfig`'s
+ * `REVIEW_SESSION_RANGE` rather than being validated a second time here, so a
+ * row edit and a hand-edited `config.json` land on the same value.
+ */
+export declare function readFastSettings(values: Pick<SettingsValues, 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview' | 'fastReviewBudget'>): Partial<FastConfig>;
+/**
+ * The inverse: seed the five rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW (§4.4 part 4): the row
+ * renders empty, `readFastSettings` sees an unparseable value, and an untouched
+ * save writes the clamp's default over whatever the user had.
+ */
+export declare function fastSettingsFrom(fast: FastConfig): Pick<SettingsValues, 'fastEnabled' | 'fastModel' | 'fastProvider' | 'fastReview' | 'fastReviewBudget'>;
 /**
  * The cap this setting will ACTUALLY produce against the selected model.
  *
@@ -51,5 +132,5 @@ interface SettingsScreenProps {
  * "I set 64000 but answers still stop early" has no answer anywhere in the UI.
  */
 export declare function effectiveCapLine(values: Pick<SettingsValues, 'provider' | 'model' | 'maxTokens'>): string;
-export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }: SettingsScreenProps): React.ReactElement;
+export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, retrySummary, }: SettingsScreenProps): React.ReactElement;
 export {};

package/dist/ui/overlays/SettingsScreen.js

@@ -15,12 +15,137 @@ import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, }
 import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
+const SHOW_THINKING_OPTIONS = ['off', 'on'];
+const LIVE_OUTPUT_OPTIONS = ['off', 'on'];
+const FAST_ENABLED_OPTIONS = ['off', 'on'];
+/**
+ * `(inherit)` IS THE EMPTY STRING, rendered as a word.
+ *
+ * An empty enum cell would read as "unset and therefore broken"; the truth is
+ * that an empty `fast.provider` INHERITS the main provider, which is the setting
+ * most users want and the one they should not have to type (§3.2 rule 2).
+ */
+const FAST_INHERIT_PROVIDER = '(inherit)';
+const FAST_PROVIDER_OPTIONS = [FAST_INHERIT_PROVIDER, ...ADAPTER_PROVIDERS];
+/**
+ * The derived, non-editable line under the five fast rows — the sibling of
+ * `effectiveCapLine`, and it exists for the same reason (§4.5).
+ *
+ * A SETTINGS SCREEN THAT LETS A USER SWITCH A TIER ON AND GIVES NO SIGNAL THAT
+ * IT CANNOT RESOLVE is the failure `effectiveCapLine` was added to fix for
+ * `maxTokens`, one screen later. `keyFor` is the same resolver the controller
+ * uses, so this line and the runtime cannot disagree.
+ *
+ * IT DOES NOT TAKE `fastReviewBudget` AND MUST NOT (§4.4 part 5): this line
+ * describes what the tier IS, not what it is allowed to spend.
+ */
+export function fastTierLine(values, hasKey) {
+    if (values.fastEnabled !== 'on')
+        return 'Fast tier: off';
+    const model = values.fastModel.trim();
+    if (model.length === 0)
+        return 'Fast tier: off  (fast.model is not set)';
+    const provider = values.fastProvider === FAST_INHERIT_PROVIDER || values.fastProvider.trim().length === 0
+        ? values.provider
+        : values.fastProvider;
+    if (!hasKey(provider)) {
+        return `Fast tier: ${provider}:${model}  (no API key for ${provider} - the tier will stay off)`;
+    }
+    const review = values.fastReview.trim().toLowerCase();
+    const cadence = review === 'off'
+        ? 'review off'
+        : /^\d+$/.test(review)
+            ? `review every ${review} turns`
+            : 'review every 5 turns';
+    return `Fast tier: ${provider}:${model}  (key set)  ${cadence}`;
+}
+/**
+ * The five editable fast rows, as a config patch (§4.5 / hardening §4.4).
+ *
+ * PURE AND EXPORTED so `App`'s save handler holds no parsing of its own, and so
+ * the round trip `fastSettingsFrom(config)` -> edit -> `readFastSettings` can be
+ * tested without a terminal.
+ *
+ * A TYPO IN `fastReview` CHANGES NOTHING — the `review` / `reviewEveryTurns`
+ * keys are simply omitted from the patch, so `clampFastConfig`'s merge keeps
+ * whatever was there. That is the `Max tokens` discipline this screen already
+ * follows, and the alternative (resolving a typo to the default) silently
+ * discards the cadence the user actually set. `fastReviewBudget` follows the
+ * same rule; an out-of-range NUMBER is passed through to `clampFastConfig`'s
+ * `REVIEW_SESSION_RANGE` rather than being validated a second time here, so a
+ * row edit and a hand-edited `config.json` land on the same value.
+ */
+export function readFastSettings(values) {
+    const review = values.fastReview.trim().toLowerCase();
+    const parsed = /^\d+$/.test(review) ? Number.parseInt(review, 10) : Number.NaN;
+    const budget = values.fastReviewBudget.trim();
+    const parsedBudget = /^\d+$/.test(budget) ? Number.parseInt(budget, 10) : Number.NaN;
+    return {
+        enabled: values.fastEnabled === 'on',
+        model: values.fastModel.trim(),
+        provider: values.fastProvider === FAST_INHERIT_PROVIDER ? '' : values.fastProvider.trim(),
+        ...(review === 'off' ? { review: false } : {}),
+        ...(Number.isFinite(parsed) && parsed > 0
+            ? { review: true, reviewEveryTurns: parsed }
+            : {}),
+        ...(Number.isFinite(parsedBudget) ? { reviewMaxPerSession: parsedBudget } : {}),
+    };
+}
+/**
+ * The inverse: seed the five rows from a resolved config.
+ *
+ * OMITTING A KEY HERE IS THE SILENT HALF OF ADDING A ROW (§4.4 part 4): the row
+ * renders empty, `readFastSettings` sees an unparseable value, and an untouched
+ * save writes the clamp's default over whatever the user had.
+ */
+export function fastSettingsFrom(fast) {
+    return {
+        fastEnabled: fast.enabled ? 'on' : 'off',
+        fastModel: fast.model,
+        fastProvider: fast.provider.trim().length > 0 ? fast.provider : FAST_INHERIT_PROVIDER,
+        fastReview: fast.review ? String(fast.reviewEveryTurns) : 'off',
+        fastReviewBudget: String(fast.reviewMaxPerSession),
+    };
+}
 const FIELDS = [
     { key: 'provider', label: 'Provider', kind: 'enum', options: ADAPTER_PROVIDERS },
     { key: 'model', label: 'Model', kind: 'text' },
     { key: 'baseUrl', label: 'Base URL', kind: 'text' },
     { key: 'thinkingLevel', label: 'Thinking', kind: 'enum', options: THINKING_LEVELS },
+    // Directly under `Thinking`, so the effort setting and the display setting are
+    // read together. `Show thinking` is 13 characters, inside the 18-column label
+    // budget `.padEnd(18)` enforces below and that IF-H7 records as silently
+    // overflowing.
+    { key: 'showThinking', label: 'Show thinking', kind: 'enum', options: SHOW_THINKING_OPTIONS },
+    // Beside `Show thinking`, because the two are the transcript's only display
+    // switches. `Live output` is 11 characters, inside the 18-column label budget
+    // `.padEnd(18)` enforces below and that IF-H7 records as silently overflowing.
+    { key: 'liveToolOutput', label: 'Live output', kind: 'enum', options: LIVE_OUTPUT_OPTIONS },
     { key: 'maxTokens', label: 'Max tokens', kind: 'text' },
+    // The fast tier sits AFTER `Max tokens` and BEFORE `API key`, because the key
+    // row is the one a user scrolls to deliberately and putting five rows past it
+    // would bury it (fast-model-tier §4.5). The rationale survives a fifth row;
+    // the count in it did not.
+    //
+    // `Fast review budget` is a `'text'` row, NOT a new numeric kind (D-H12):
+    // `SettingsRow.kind` is `'enum' | 'text' | 'secret'`, and `Max tokens` and
+    // `Fast review` are both bounded numbers already living as text plus an
+    // adapter parse. A fourth kind for one row would be a new interaction pattern
+    // in a screen whose whole design is that it edits text.
+    //
+    // ITS LABEL IS SHORT BECAUSE THE LABEL COLUMN IS A BUDGET, NOT A HINT SLOT.
+    // Labels render `.padEnd(18)` below, so one that reaches 18 does not truncate
+    // and does not wrap - it pushes ITS OWN value right (or butts against it at
+    // exactly 18) while every other row's value stays put, and the column stops
+    // being a column. So no `(1-500)` here: no other bounded row carries its range
+    // either (`Max tokens`, `Fast review`), `clampFastConfig` is the enforcement,
+    // and `/fast budget` states the range in the one place a user meets it - when
+    // it refuses a bad one. The name matches that command for the same reason.
+    { key: 'fastEnabled', label: 'Fast tier', kind: 'enum', options: FAST_ENABLED_OPTIONS },
+    { key: 'fastModel', label: 'Fast model', kind: 'text' },
+    { key: 'fastProvider', label: 'Fast provider', kind: 'enum', options: FAST_PROVIDER_OPTIONS },
+    { key: 'fastReview', label: 'Fast review', kind: 'text' },
+    { key: 'fastReviewBudget', label: 'Fast budget', kind: 'text' },
     { key: 'apiKey', label: 'API key', kind: 'secret' },
     { key: 'logLevel', label: 'Log level', kind: 'enum', options: LOG_LEVEL_NAMES },
 ];
@@ -52,7 +177,7 @@ export function effectiveCapLine(values) {
         return `Effective: ${resolution.value}  (auto)`;
     return `Effective: ${resolution.value}`;
 }
-export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }) {
+export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, retrySummary, }) {
     const [values, setValues] = useState(initial);
     const [index, setIndex] = useState(0);
     const glyphs = pickGlyphs(caps);
@@ -132,6 +257,15 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
         // setting, which is the one thing this field can never be.
         if (f.key === 'maxTokens' && raw.length === 0)
             return 'auto';
+        // `(not set)` and NOT `(same as main)`, which is the honest reading of §3.2
+        // rule 3: an empty `fast.model` does not inherit, it means the tier is
+        // unconfigured. `(same as main)` is a fact the derived line below states
+        // when the value literally equals the main model — never a placeholder.
+        if (f.key === 'fastModel' && raw.length === 0) {
+            return selected ? '(type a model id)' : '(not set)';
+        }
+        if (f.key === 'fastReview' && raw.length === 0)
+            return 'every 5 turns';
         return raw.length > 0 ? raw : selected ? '(type to set)' : '(none)';
     };
     // One element per row, each `wrap="truncate"` — the contract for OverlayFrame's
@@ -145,6 +279,18 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
     // controlled mode slices by ELEMENT, so a row that wraps desynchronises the
     // position indicator.
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: effectiveCapLine(values) }, "__effective"));
+    rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: fastTierLine(values, (id) => (apiKeys[id] ?? '').length > 0) }, "__fast"));
+    /**
+     * ONE ROW, NOT NINE (llm-api-retry-backoff §6.9).
+     *
+     * READ-ONLY, and deliberately so: the nine `retry.*` keys belong to `config set`
+     * and `config.json`, and a settings screen that exposed a jitter checkbox is a
+     * settings screen nobody reads. What a user needs HERE is the answer to "is it
+     * on, and how many" — the discoverable control is `/retry`, which this row names.
+     */
+    if (retrySummary) {
+        rows.push(_jsxs(Text, { wrap: "truncate", color: theme.muted, children: ['  ', 'API retries'.padEnd(18), retrySummary] }, "__retry"));
+    }
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: "Enter saves. Keys persist to the config file (0600)." }, "__save"));
     return (_jsx(OverlayFrame, { title: "Settings", hint: `${glyphs.arrowUp}${glyphs.arrowDown} field ${glyphs.midDot} ${glyphs.arrowLeft}${glyphs.arrowRight} change ${glyphs.midDot} Enter save ${glyphs.midDot} Esc close`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
 }