@aragon-agent/cli 0.5.10 → 0.5.12

package/dist/todo/store.js

@@ -10,12 +10,18 @@
  * `TeamRuntime`.
  *
  * INVARIANT I-2 — the list is a PROJECTION OF WHAT THE MODEL BELIEVES, and
- * nothing that does not tell the model may change it. `/clear` wipes the
- * transcript but not the conversation, so it must NOT reach this class;
- * `/reset` clears `messages`, so it must. Every write is a FULL REPLACEMENT and
- * every clear is a FULL REMOVAL - there is no partial update anywhere, which is
- * what makes I-9 ("the panel is never a contradiction of the model") provable
- * rather than argued.
+ * nothing that does not tell the model may change it — EXCEPT AN EXPLICIT USER
+ * INSTRUCTION, which is the rule's standing exception and is marked
+ * `TodoClearReason = 'user'`. Two commands come through that door: `/todo clear`
+ * and `/clear`. Neither tells the model anything, and that is fine, because what
+ * they leave behind is "panel absent, model still remembers" - the direction I-9
+ * below calls safe, and one the model's next full-replacement write heals on its
+ * own. `/reset` (reason `'reset'`) remains the only clear caused by the belief
+ * itself being destroyed, because it clears `messages`.
+ *
+ * Every write is a FULL REPLACEMENT and every clear is a FULL REMOVAL - there is
+ * no partial update anywhere, which is what makes I-9 ("the panel is never a
+ * contradiction of the model") provable rather than argued.
  */
 import { getLogger } from '../logging/logger.js';
 import { TODO_LIMITS } from './limits.js';

package/dist/todo/types.d.ts

@@ -42,7 +42,8 @@ export interface TodoSnapshot {
 /**
  * Why a list went away.
  *
- *   `user`  - `/todo clear`.
+ *   `user`  - `/todo clear`, or `/clear`. Both are an explicit user instruction,
+ *             which is I-2's standing exception; neither touches `messages`.
  *   `reset` - `/reset`, or a `/resume` whose file carried no list (§3.13).
  *   `turn`  - every item was completed when the next user turn started.
  *   `stale` - unfinished, and unwritten for more than `TODO_LIMITS.staleTurns`

package/dist/ui/ActivityLine.d.ts

@@ -21,6 +21,22 @@
  *
  * What is left is the one thing the status bar cannot say: THAT THE SILENCE IS
  * WORK. The bar shows state; this row shows life.
+ *
+ * THIS ROW OWNS THE ONLY ANIMATED SPINNER WHILE IT IS MOUNTED
+ * (single-spinner-while-running D-1). Seven other sites can animate — the
+ * streaming assistant marker, the tool badge, the team/fast/retry cards, and the
+ * two panels' rows — and each was independently right to. Emergently they put up
+ * to five braille animations on adjacent rows, each on its own 80 ms timer: one
+ * piece of information rendered five times and out of phase, which is the same
+ * duplication the paragraph above legislates against for text. So `App` widens
+ * the `reducedMotion` it hands those seven to `cfg.reducedMotion || (running &&
+ * !overlay)`, and they all fall back to the static glyphs they already had.
+ *
+ * THIS COMPONENT KEEPS THE RAW CONFIG FLAG, and that asymmetry is deliberate
+ * (D-5). It reads the flag TWICE: once for the spinner below, and once for
+ * `pickActivityPhrase`'s rotation. Handing it the widened value would freeze the
+ * phrase at the first word of every run — a second, unrelated regression, and
+ * one nobody would connect to a change about icons.
  */
 import React from 'react';
 import type { Theme } from './theme.js';

package/dist/ui/App.js

@@ -1422,6 +1422,30 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const opener = empty ? (_jsx(SessionOpener, { variant: fullscreen ? pickOpenerVariant(viewportBudget, contentCols, caps) : 'none', version: version, cwd: controller.getCwd(), hasKey: hasKey, viewportRows: fullscreen ? viewportBudget : Number.POSITIVE_INFINITY, theme: theme, caps: caps })) : null;
     const density = cfg.density;
     const transcriptWindow = cfg.transcriptWindow ?? DEFAULT_TRANSCRIPT_WINDOW;
+    // --- One spinner per run (single-spinner-while-running D-1 .. D-5). ------
+    //
+    // THE MOUNT CONDITION, NAMED ONCE AND USED TWICE (D-4). This const both gates
+    // the `<ActivityLine>` element below and feeds the derivation on the next
+    // line, so "the line is up" and "every other site is still" can never
+    // disagree. Two copies of the same boolean expression is exactly how that
+    // invariant becomes false in six months, silently and in only one branch.
+    //
+    // NOT `running` ALONE (D-3). While an overlay owns the screen the activity row
+    // is suppressed, so keying suppression off `running` would leave the frame
+    // with ZERO life signals: the bar shows state, this row shows life. Never
+    // trade one duplicate for one absence.
+    const activityVisible = running && !overlayNode;
+    // The FOUR VIEW CONSUMERS (transcript x 2, team panel, todo panel) take this;
+    // the activity line keeps the raw config flag (D-5), because it reads that
+    // flag a second time to gate phrase rotation and the widened value would
+    // freeze the phrase at the first word of every run.
+    //
+    // So below `App` the prop now means "this frame does not animate here" rather
+    // than "the user asked for reduced motion". `cfg.reducedMotion` (`:279`) stays
+    // the sole config source, and `spinner-census.test.ts` pins this wiring —
+    // threading the raw flag into a fifth consumer is the one silent way back to
+    // two spinners (R-2).
+    const viewReducedMotion = reducedMotion || activityVisible;
     // Assigned during render so `/perf` reads the CURRENT frame (see `perfRef`).
     // `mountedEntries` is the same number `render-budget.test.tsx` asserts (AC-9).
     perfRef.current = {
@@ -1440,20 +1464,25 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         viewportRows: fullscreen ? viewportBudget : rows,
         offset: scrolledLines,
     };
-    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, showScrollIndicator: true, cols: contentCols, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps, windowSize: transcriptWindow, cols: contentCols, heights: heights, mountedSink: mountedCount })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps }), overlayNode] }));
+    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, showScrollIndicator: true, cols: contentCols, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps, windowSize: transcriptWindow, cols: contentCols, heights: heights, mountedSink: mountedCount })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: density, mode: mode, nowSec: nowSec, theme: theme, caps: caps }), overlayNode] }));
     // The completion popup lives inside the bottom chrome and can add up to 9
     // rows; unbounded, it pushes the status bar past the frame height where
     // `overflow: hidden` clips it away (R-14 / M-14). Cap it against the viewport.
     const popupMaxRows = fullscreen ? Math.max(1, viewportBudget - 4) : undefined;
     const composer = fullscreen ? (_jsx(Composer, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), showHint: rows >= HINT_MIN_ROWS, submitCount: cfg.submitCount, hintsEnabled: cfg.hints, agentMode: state.agentMode, popupMaxRows: popupMaxRows, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) })) : (_jsx(Box, { marginTop: 1, children: _jsx(PromptInput, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), agentMode: state.agentMode, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) }) }));
-    return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, header: header, viewport: viewport, team: state.team ? (_jsx(TeamPanel, { snapshot: state.team, rows: rows, cols: cols, reducedMotion: reducedMotion, theme: theme, caps: caps })) : null, rail: showRail && state.todos ? (_jsx(TodoPanel, { snapshot: state.todos, width: railWidth, rows: railRows, running: state.status === 'running', reducedMotion: reducedMotion, theme: theme, caps: caps })) : null, strip: showStrip && state.todos ? (_jsx(TodoStrip, { snapshot: state.todos, cols: cols, theme: theme, caps: caps })) : null, toast: _jsx(BottomStatusRow, { mode: mode, toasts: state.toasts, 
+    return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, header: header, viewport: viewport, team: state.team ? (_jsx(TeamPanel, { snapshot: state.team, rows: rows, cols: cols, reducedMotion: viewReducedMotion, theme: theme, caps: caps })) : null, rail: showRail && state.todos ? (_jsx(TodoPanel, { snapshot: state.todos, width: railWidth, rows: railRows, running: running, reducedMotion: viewReducedMotion, theme: theme, caps: caps })) : null, strip: showStrip && state.todos ? (_jsx(TodoStrip, { snapshot: state.todos, cols: cols, theme: theme, caps: caps })) : null, toast: _jsx(BottomStatusRow, { mode: mode, toasts: state.toasts, 
             // `!overlayNode` suppresses the line while an overlay owns the screen:
             // the full-screen branch replaces the whole viewport with the overlay,
             // and a working line under a settings screen is noise attached to a
             // surface the run is not visible on. (Inline overlays are part of the
             // document flow, so there the suppression is conservative rather than
             // necessary — P2-5.)
-            activity: running && !overlayNode ? (_jsx(ActivityLine, { startedAt: runStartedAt.current, elapsedMs: elapsedMs, reducedMotion: reducedMotion, runningTool: runningTool, theme: theme, caps: caps })) : null, 
+            //
+            // THE CONDITION IS `activityVisible`, THE SAME CONST THE SUPPRESSION
+            // SIGNAL IS DERIVED FROM (D-4): inlining it here again is how the two
+            // drift apart, and the drift is silent in whichever branch is not
+            // edited.
+            activity: activityVisible ? (_jsx(ActivityLine, { startedAt: runStartedAt.current, elapsedMs: elapsedMs, reducedMotion: reducedMotion, runningTool: runningTool, theme: theme, caps: caps })) : null, 
             // PRESENCE IS DECIDED HERE, NOT BY `UpdateLine` RETURNING `null`
             // (C-15 / cli-auto-update P0-1 / D-19). `BottomStatusRow` tests this
             // prop for truthiness, and a React element is truthy however it

package/dist/ui/PromptInput.d.ts

@@ -7,6 +7,16 @@
  * The buffer/cursor transforms (`applyEdit`, `moveVertical`) and the suggestion
  * computations (`slashSuggestions`, `fileTokenAt`) are pure module functions,
  * exported for `input.test.ts`, so the component itself stays thin.
+ *
+ * THE EDITOR'S FIVE PIECES OF STATE LIVE IN ONE REDUCER, and every branch of the
+ * input handler performs AT MOST ONE `dispatch` (tui-input-flicker-fix §3.4).
+ * Ink mounts a LEGACY React root, where `setState` outside a React event handler
+ * is not batched — and `useInput` runs from a stdin `'data'` listener, which is
+ * outside React entirely. The five `setState` calls one keystroke used to make
+ * were five commits, five whole-tree Yoga layouts and, through Ink's 32 ms
+ * leading+trailing throttle, two full-frame repaints per character. `fileMatches`
+ * stays a plain `useState` because it is written from the debounced glob effect
+ * rather than from a key.
  */
 import React from 'react';
 import type { Theme } from './theme.js';

package/dist/ui/PromptInput.js

@@ -8,13 +8,24 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  * The buffer/cursor transforms (`applyEdit`, `moveVertical`) and the suggestion
  * computations (`slashSuggestions`, `fileTokenAt`) are pure module functions,
  * exported for `input.test.ts`, so the component itself stays thin.
+ *
+ * THE EDITOR'S FIVE PIECES OF STATE LIVE IN ONE REDUCER, and every branch of the
+ * input handler performs AT MOST ONE `dispatch` (tui-input-flicker-fix §3.4).
+ * Ink mounts a LEGACY React root, where `setState` outside a React event handler
+ * is not batched — and `useInput` runs from a stdin `'data'` listener, which is
+ * outside React entirely. The five `setState` calls one keystroke used to make
+ * were five commits, five whole-tree Yoga layouts and, through Ink's 32 ms
+ * leading+trailing throttle, two full-frame repaints per character. `fileMatches`
+ * stays a plain `useState` because it is written from the debounced glob effect
+ * rather than from a key.
  */
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useReducer, useRef, useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { glob as tinyGlob } from 'tinyglobby';
 import { pickGlyphs } from './glyphs.js';
 import { recognize } from '../input/keymap.js';
 import { AutocompletePopup } from './AutocompletePopup.js';
+import { editorReducer, INITIAL_EDITOR_STATE } from './editor-reducer.js';
 // ---------------------------------------------------------------------------
 // Pure editing helpers (unit-tested in input.test.ts)
 // ---------------------------------------------------------------------------
@@ -128,11 +139,8 @@ function isControlSeq(input) {
 // Component
 // ---------------------------------------------------------------------------
 export function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, }) {
-    const [buffer, setBuffer] = useState('');
-    const [cursor, setCursor] = useState(0);
-    const [historyIndex, setHistoryIndex] = useState(null);
-    const [dismissed, setDismissed] = useState(false);
-    const [sel, setSel] = useState(0);
+    const [editor, dispatch] = useReducer(editorReducer, INITIAL_EDITOR_STATE);
+    const { buffer, cursor, historyIndex, dismissed, sel } = editor;
     const [fileMatches, setFileMatches] = useState([]);
     // --- Derived suggestion state (shared by render + input handler). --------
     const slashSug = dismissed ? null : slashSuggestions(buffer, commands);
@@ -189,46 +197,36 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         onDraftChange(hasDraft);
     }, [hasDraft, onDraftChange]);
     // --- Mutators. -----------------------------------------------------------
-    const resetDraftFlags = () => {
-        setHistoryIndex(null);
-        setDismissed(false);
-        setSel(0);
-    };
+    // ONE DISPATCH EACH, and that is the rule §3.4 asks a reviewer to check line
+    // by line. Two dispatches from one key would put the legacy root back to two
+    // commits and undo the whole of F3 for that branch.
     const insert = (text) => {
-        setBuffer(buffer.slice(0, cursor) + text + buffer.slice(cursor));
-        setCursor(cursor + text.length);
-        resetDraftFlags();
+        dispatch({ type: 'insert', text });
     };
     const submit = (text) => {
         onSubmit(text);
-        setBuffer('');
-        setCursor(0);
-        resetDraftFlags();
+        dispatch({ type: 'clear' });
     };
     const recallUp = () => {
         if (history.length === 0)
             return;
         const idx = historyIndex === null ? history.length - 1 : Math.max(0, historyIndex - 1);
         const value = history[idx] ?? '';
-        setHistoryIndex(idx);
-        setBuffer(value);
-        setCursor(value.length);
+        dispatch({ type: 'recall', buffer: value, cursor: value.length, historyIndex: idx });
     };
     const recallDown = () => {
         if (historyIndex === null)
             return;
         const idx = historyIndex + 1;
+        // Past the newest entry the walk ends and the draft goes back to empty —
+        // `historyIndex: null` is what tells `verticalOrHistory` the user is editing
+        // again rather than still stepping.
         if (idx >= history.length) {
-            setHistoryIndex(null);
-            setBuffer('');
-            setCursor(0);
-        }
-        else {
-            const value = history[idx] ?? '';
-            setHistoryIndex(idx);
-            setBuffer(value);
-            setCursor(value.length);
+            dispatch({ type: 'recall', buffer: '', cursor: 0, historyIndex: null });
+            return;
         }
+        const value = history[idx] ?? '';
+        dispatch({ type: 'recall', buffer: value, cursor: value.length, historyIndex: idx });
     };
     const completeSelection = () => {
         const chosen = popupItems[clampedSel];
@@ -236,20 +234,17 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
             return;
         if (popupKind === 'slash') {
             const next = `${chosen.label} `;
-            setBuffer(next);
-            setCursor(next.length);
+            dispatch({ type: 'replace', buffer: next, cursor: next.length });
         }
         else if (popupKind === 'file' && fileTok) {
             const next = buffer.slice(0, fileTok.start) + chosen.label + buffer.slice(fileTok.end);
-            setBuffer(next);
-            setCursor(fileTok.start + chosen.label.length);
+            dispatch({ type: 'replace', buffer: next, cursor: fileTok.start + chosen.label.length });
         }
-        resetDraftFlags();
     };
     const verticalOrHistory = (dir) => {
         const moved = moveVertical(buffer, cursor, dir);
         if (moved) {
-            setCursor(moved.cursor);
+            dispatch({ type: 'moveCursor', cursor: moved.cursor });
             return;
         }
         // At an edge: recall history only from an empty buffer or while already
@@ -274,11 +269,11 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         // Popup navigation owns Up/Down/Tab/→/Enter/Esc while it is open.
         if (popupItems.length > 0) {
             if (key.upArrow) {
-                setSel(Math.max(0, clampedSel - 1));
+                dispatch({ type: 'select', sel: Math.max(0, clampedSel - 1) });
                 return;
             }
             if (key.downArrow) {
-                setSel(Math.min(popupItems.length - 1, clampedSel + 1));
+                dispatch({ type: 'select', sel: Math.min(popupItems.length - 1, clampedSel + 1) });
                 return;
             }
             if (key.tab || (key.rightArrow && cursor >= buffer.length)) {
@@ -292,7 +287,7 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
                 return;
             }
             if (key.escape) {
-                setDismissed(true);
+                dispatch({ type: 'dismiss' });
                 return;
             }
             // Any other key falls through so typing keeps filtering the popup.
@@ -303,9 +298,7 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         const intent = recognize(input, key);
         if (intent) {
             const next = applyEdit(buffer, cursor, intent);
-            setBuffer(next.buffer);
-            setCursor(next.cursor);
-            resetDraftFlags();
+            dispatch({ type: 'replace', buffer: next.buffer, cursor: next.cursor });
             return;
         }
         if (key.ctrl)
@@ -321,19 +314,19 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
             return;
         }
         if (key.backspace || key.delete) {
-            if (cursor > 0) {
-                setBuffer(buffer.slice(0, cursor - 1) + buffer.slice(cursor));
-                setCursor(cursor - 1);
-                resetDraftFlags();
-            }
+            // The `cursor > 0` guard lives in the reducer now, so this branch is one
+            // unconditional dispatch and a no-op at the left edge returns the same
+            // state object — which React bails out on, exactly as the old
+            // `if (cursor > 0)` skipped the `setState`s.
+            dispatch({ type: 'backspace' });
             return;
         }
         if (key.leftArrow) {
-            setCursor(Math.max(0, cursor - 1));
+            dispatch({ type: 'moveCursor', cursor: Math.max(0, cursor - 1) });
             return;
         }
         if (key.rightArrow) {
-            setCursor(Math.min(buffer.length, cursor + 1));
+            dispatch({ type: 'moveCursor', cursor: Math.min(buffer.length, cursor + 1) });
             return;
         }
         // `!key.shift` is load-bearing: Shift+↑/↓ is the viewport's line-scroll

package/dist/ui/Transcript.js

@@ -138,6 +138,21 @@ function EntryViewImpl({ entry, prev, expanded, thinkingVisible, reducedMotion,
             // While text streams, the spinner IS the role marker. Braille dots are
             // both an animation and a Unicode-only glyph, so reduced motion and an
             // ASCII terminal fall back to the same static marker (P2-11 / A-10).
+            //
+            // `reducedMotion` ARRIVES PRE-WIDENED FROM `App`: it is now
+            // `cfg.reducedMotion || activityVisible`, so this marker is static for the
+            // whole of every run and the activity row above the composer carries the
+            // one animation (single-spinner-while-running D-2). Nothing here changes —
+            // the expression already meant "do not animate here".
+            //
+            // THAT IS SAFE FOR `<Static>` BY CONSTRUCTION, not by luck: a settled
+            // prefix is printed once and can never be re-printed, so a boolean that
+            // changed how an already-printed entry renders would tear the history.
+            // `computeSettledCount` below breaks on EVERY condition that makes an
+            // entry animate (`:84` streaming, `:85` running tool, `:91` active team,
+            // `:104` retry, `:109` live fast), so every animating entry is in the live
+            // region and every entry in `<Static>` already has `animate === false` on
+            // both sides of the flip. Weakening a break clause breaks that proof.
             const animate = entry.streaming && !reducedMotion && caps.unicode;
             return frame(animate ? _jsx(Spinner, { type: "dots" }) : glyphs.assistant, theme.primary, _jsx(AssistantEntry, { text: entry.text, thinking: entry.thinking, thinkingOpen: entry.thinkingOpen, thinkingVisible: thinkingVisible, streaming: entry.streaming, aborted: entry.aborted, 
                 // `EntryViewImpl` hands each renderer EXPLICIT SCALAR PROPS, so

package/dist/ui/editor-reducer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Composer editor state — F3 of tui-input-flicker-fix (§3.4).
+ *
+ * Ink creates its container with tag `0` — a LEGACY React root
+ * (`ink/build/ink.js:59-61`). In a legacy root, `setState` called outside a
+ * React event handler is NOT batched: each call schedules and immediately
+ * flushes a synchronous render. `useInput`'s callback runs from a stdin
+ * `'data'` listener, which is outside React entirely, so `PromptInput.insert`'s
+ * five `setState` calls became five commits, five whole-tree Yoga layouts, and
+ * — through Ink's 32 ms leading+trailing throttle — TWO full-frame repaints per
+ * printable character (§2 R3). The flicker got worse the faster the user typed,
+ * which is exactly what the report described.
+ *
+ * Collapsing the five always-together pieces of state into one reducer makes a
+ * keystroke cost one commit. `fileMatches` deliberately stays a separate
+ * `useState` in the component: it is written from the debounced async glob
+ * effect, not from the key handler, so folding it in here would couple two
+ * unrelated update sources.
+ *
+ * THE RULE A REVIEWER SHOULD CHECK LINE BY LINE: every branch of the `useInput`
+ * callback performs at most ONE `dispatch` and then returns.
+ *
+ * Extracted from the component so it is unit-testable without mounting Ink.
+ */
+export interface EditorState {
+    buffer: string;
+    cursor: number;
+    historyIndex: number | null;
+    dismissed: boolean;
+    sel: number;
+}
+/**
+ * A `type` and not an `interface` because it is a discriminated union — the one
+ * documented exception to this package's interface-first convention.
+ */
+export type EditorAction = {
+    type: 'insert';
+    text: string;
+} | {
+    type: 'replace';
+    buffer: string;
+    cursor: number;
+} | {
+    type: 'backspace';
+} | {
+    type: 'moveCursor';
+    cursor: number;
+} | {
+    type: 'recall';
+    buffer: string;
+    cursor: number;
+    historyIndex: number | null;
+} | {
+    type: 'select';
+    sel: number;
+} | {
+    type: 'dismiss';
+} | {
+    type: 'clear';
+};
+export declare const INITIAL_EDITOR_STATE: EditorState;
+export declare function editorReducer(state: EditorState, action: EditorAction): EditorState;

package/dist/ui/editor-reducer.js

@@ -0,0 +1,90 @@
+/**
+ * Composer editor state — F3 of tui-input-flicker-fix (§3.4).
+ *
+ * Ink creates its container with tag `0` — a LEGACY React root
+ * (`ink/build/ink.js:59-61`). In a legacy root, `setState` called outside a
+ * React event handler is NOT batched: each call schedules and immediately
+ * flushes a synchronous render. `useInput`'s callback runs from a stdin
+ * `'data'` listener, which is outside React entirely, so `PromptInput.insert`'s
+ * five `setState` calls became five commits, five whole-tree Yoga layouts, and
+ * — through Ink's 32 ms leading+trailing throttle — TWO full-frame repaints per
+ * printable character (§2 R3). The flicker got worse the faster the user typed,
+ * which is exactly what the report described.
+ *
+ * Collapsing the five always-together pieces of state into one reducer makes a
+ * keystroke cost one commit. `fileMatches` deliberately stays a separate
+ * `useState` in the component: it is written from the debounced async glob
+ * effect, not from the key handler, so folding it in here would couple two
+ * unrelated update sources.
+ *
+ * THE RULE A REVIEWER SHOULD CHECK LINE BY LINE: every branch of the `useInput`
+ * callback performs at most ONE `dispatch` and then returns.
+ *
+ * Extracted from the component so it is unit-testable without mounting Ink.
+ */
+export const INITIAL_EDITOR_STATE = {
+    buffer: '',
+    cursor: 0,
+    historyIndex: null,
+    dismissed: false,
+    sel: 0,
+};
+/**
+ * The three flags `resetDraftFlags()` used to clear with three separate
+ * `setState` calls.
+ *
+ * Every action that CHANGES THE BUFFER resets them, and that is the pre-existing
+ * semantics rather than a new rule: an edit invalidates the history cursor (the
+ * draft is no longer the recalled entry), un-dismisses the popup (the user is
+ * typing again, so suggestions should come back), and re-homes the selection
+ * (the candidate list is about to be recomputed).
+ */
+const DRAFT_FLAGS = { historyIndex: null, dismissed: false, sel: 0 };
+export function editorReducer(state, action) {
+    switch (action.type) {
+        case 'insert':
+            return {
+                ...state,
+                ...DRAFT_FLAGS,
+                buffer: state.buffer.slice(0, state.cursor) + action.text + state.buffer.slice(state.cursor),
+                cursor: state.cursor + action.text.length,
+            };
+        case 'replace':
+            return { ...state, ...DRAFT_FLAGS, buffer: action.buffer, cursor: action.cursor };
+        case 'backspace': {
+            if (state.cursor <= 0)
+                return state;
+            return {
+                ...state,
+                ...DRAFT_FLAGS,
+                buffer: state.buffer.slice(0, state.cursor - 1) + state.buffer.slice(state.cursor),
+                cursor: state.cursor - 1,
+            };
+        }
+        case 'moveCursor':
+            // NO DRAFT-FLAG RESET. Moving the caret is not an edit: clearing
+            // `historyIndex` here would end a history walk the moment the user pressed
+            // ← to look at what they recalled.
+            return state.cursor === action.cursor ? state : { ...state, cursor: action.cursor };
+        case 'recall':
+            // `historyIndex` is SET, not reset, which is why recall cannot reuse
+            // `replace` — the two differ in exactly the field that keeps the walk
+            // alive. `dismissed` and `sel` are LEFT ALONE, which is not an oversight:
+            // the three `setState` calls this replaces did not touch them either, and
+            // an Esc-dismissed popup that reopened when the user stepped through their
+            // history would be a behaviour change smuggled in by a refactor whose whole
+            // claim is that input semantics are identical (K-7).
+            return {
+                ...state,
+                buffer: action.buffer,
+                cursor: action.cursor,
+                historyIndex: action.historyIndex,
+            };
+        case 'select':
+            return state.sel === action.sel ? state : { ...state, sel: action.sel };
+        case 'dismiss':
+            return state.dismissed ? state : { ...state, dismissed: true };
+        case 'clear':
+            return INITIAL_EDITOR_STATE;
+    }
+}

package/dist/ui/entries/FastCard.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * FastCard — one fast-model review in the transcript (fast-model-tier §6).
  *
@@ -76,7 +76,25 @@ function FastCardImpl(props) {
     const duration = durationMs === undefined ? '' : `  ${glyphs.midDot}  ${formatDuration(durationMs)}`;
     const head = `fast review #${reviewIndex}  ${glyphs.midDot}  ${model}  ${glyphs.midDot}  turn ${turn}${duration}`;
     const showBody = status === 'advice' && text !== undefined && text.trim().length > 0;
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: theme.accent, bold: true, children: "fast" }), live && !reducedMotion && caps.unicode ? (_jsxs(Text, { color: color, children: ['  ', _jsx(Spinner, { type: "dots" }), " ", head] })) : (_jsxs(Text, { color: theme.muted, wrap: "truncate", children: ['  ', live ? `${glyphs.spinnerStill} ` : '', head] }))] }), showBody ? (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: textRows(text).map((line, index) => (_jsx(Text, { color: theme.primary, children: line }, index))) })) : (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, children: _jsx(Text, { color: color, wrap: "truncate", children: statusLine(props) }) }))] }));
+    // COLOUR TRACKS `live`, MOTION TRACKS `animate` — one headline, two separate
+    // decisions (single-spinner-while-running C-1 / D-7).
+    //
+    // These used to be two whole `<Text>` elements, so the still branch also
+    // demoted the head to `theme.muted`. That was harmless while stillness meant
+    // "the user set reducedMotion", but `App` now widens the prop to "this frame
+    // does not animate here" for the whole of every run — and under the old shape
+    // that would have greyed out every live fast review for the whole run, losing
+    // the status colour along with the motion.
+    //
+    // Three things are load-bearing and all three are silent if dropped: the
+    // leading two-space gutter that separates the head from the bold `fast` label,
+    // the single space after the marker (the still form bakes it into its template
+    // string), and `head` itself. `wrap="truncate"` now applies to the animated
+    // path too, which it did not before: it is what the still branch always did,
+    // it is the behaviour this card has in every state that is now common, and an
+    // unbounded wrap inside a one-row headline is the worse failure.
+    const animate = live && !reducedMotion && caps.unicode;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: theme.accent, bold: true, children: "fast" }), _jsxs(Text, { color: live ? color : theme.muted, wrap: "truncate", children: ['  ', animate ? (_jsxs(_Fragment, { children: [_jsx(Spinner, { type: "dots" }), ' '] })) : live ? (`${glyphs.spinnerStill} `) : (''), head] })] }), showBody ? (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: textRows(text).map((line, index) => (_jsx(Text, { color: theme.primary, children: line }, index))) })) : (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, children: _jsx(Text, { color: color, wrap: "truncate", children: statusLine(props) }) }))] }));
 }
 /**
  * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).

package/dist/ui/frame-differ.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Frame differ — F1 of tui-input-flicker-fix (§3.2).
+ *
+ * Ink 5.2.1 has exactly one repaint strategy: on every commit it serialises the
+ * WHOLE frame and hands it to `log-update`, which writes
+ * `eraseLines(previousLineCount) + frame` in a single `stdout.write`
+ * (`ink/build/log-update.js:17`). `ansiEscapes.eraseLines` walks BOTTOM-UP, so
+ * the composer — the last row of the frame — is erased near the start of every
+ * repaint and rewritten at the very end of it. During a run that happens 15–30
+ * times a second with the composer's bytes unchanged, and the user sees the
+ * bottom of their screen flicker while they type (§2 R1/R2).
+ *
+ * This module recognises that write shape, diffs the new frame against the
+ * previous one line by line, and emits only the rows that actually changed, each
+ * addressed absolutely. It is PURE: no I/O, no Node globals, no event emitter —
+ * `stdout-frame-writer.ts` is what binds it to a real stream. That is what keeps
+ * it unit-testable with plain string literals and no TTY.
+ *
+ * THREE INVARIANTS LIVE HERE AND EACH ONE FAILS SILENTLY IF DROPPED:
+ *
+ *  - I-4 · An emitted line is `CUP · SGR0 · text · SGR0 · CSI K`, IN THAT ORDER,
+ *    and it never contains `CSI 2K`. Erasing first would blank the row and refill
+ *    it, which is R1's defect at 1/H the scale but on the one row the user is
+ *    watching. Overwriting in place means no cell is ever presentably empty; the
+ *    trailing `CSI K` removes only the residue a longer previous line left, and
+ *    the trailing SGR reset before it stops a BCE terminal painting that residue
+ *    in whatever background colour the line ended inside.
+ *  - I-5 · Every emitted batch ends parked on row `H+1`. Ink's own
+ *    `previousLineCount` is computed from the string IT produced and is
+ *    unaffected by what we actually wrote, so a later pass-through's
+ *    `eraseLines(H+1)` must find the cursor exactly where log-update left it last
+ *    time. Drop this and one fallback shifts the frame up a row for the rest of
+ *    the session.
+ *  - I-6 · Any unrecognised write invalidates the cache. Absolute addressing is
+ *    valid only while nothing else writes to stdout. Full-screen mode already
+ *    forbids that, but "forbidden" is not "impossible", and the failure mode of
+ *    the guard being absent is a permanently misaligned screen while the failure
+ *    mode of it firing spuriously is one extra full repaint.
+ */
+/**
+ * Rebuild `ansiEscapes.eraseLines(count)` byte for byte.
+ *
+ * Exported for the upgrade tripwire (`frame-differ-ink-shape.test.ts`), which
+ * drives the real `ink/build/log-update.js` and asserts this reconstruction is
+ * byte-equal to what it produced. If a future Ink changes the shape, that test
+ * fails loudly instead of this module silently degrading to pass-through for the
+ * rest of the package's life (K-2).
+ */
+export declare function eraseLinesPrefix(count: number): string;
+export interface FrameDifferOptions {
+    /** Emit the DEC 2026 envelope around each batch. */
+    sync: boolean;
+    /**
+     * Live terminal height. Read on every `transform`, NEVER cached: it is the
+     * only input to the I-9 geometry guard and it changes under the differ's feet
+     * on resize. `undefined` ⇒ stand down and pass through.
+     */
+    rows: () => number | undefined;
+    /** Raised once, on the 0→1 edge of `fallbacks` (§5.6). */
+    onFirstFallback?: () => void;
+}
+export interface FrameWriterStats {
+    /** Frames the differ EMITTED — `framesDiffed + framesFull`, never pass-throughs. */
+    framesTotal: number;
+    framesDiffed: number;
+    framesFull: number;
+    linesWritten: number;
+    bytesWritten: number;
+    /**
+     * Pass-throughs caused by a write the differ did not understand.
+     *
+     * NOT INVALIDATIONS (AC-11 / K-14). A resize legitimately invalidates and shows
+     * up as `framesFull`; counting invalidations here would put AC-7 and AC-11 in
+     * direct contradiction and one of them would end up quietly relaxed. It also
+     * excludes the two pass-throughs this module inflicts on ITSELF and already
+     * knows are benign — the session's seed write and the degenerate-geometry
+     * stand-down — because `fallbacks > 0` is documented to mean "something wrote
+     * to stdout behind Ink's back" and is what raises the §5.6 notice.
+     */
+    fallbacks: number;
+}
+export interface FrameDiffer {
+    /**
+     * Bytes to write instead of `chunk`; `''` = write nothing; `null` = write
+     * `chunk`. The parameter is `string` and only `string` (P1-4): decoding, and
+     * the decision about what is even diffable, belong to the writer — the only
+     * place untyped input arrives.
+     */
+    transform(chunk: string): string | null;
+    /** Force the next frame to be a full repaint. */
+    invalidate(): void;
+    /** Single owner of the counters (P2-2); the writer re-exports this. */
+    stats(): FrameWriterStats;
+}
+export declare function createFrameDiffer(options: FrameDifferOptions): FrameDiffer;