@aragon-agent/cli 0.5.4 → 0.5.6

package/dist/ui/App.js

@@ -29,9 +29,14 @@ import { PromptInput } from './PromptInput.js';
 import { Composer } from './Composer.js';
 import { StatusBar } from './StatusBar.js';
 import { TeamPanel } from './TeamPanel.js';
+import { TodoPanel } from './TodoPanel.js';
+import { TodoStrip } from './TodoStrip.js';
 import { ToastStack } from './ToastStack.js';
 import { AppShell } from './layout/AppShell.js';
 import { ScrollViewport } from './layout/ScrollViewport.js';
+import { todoRailRows, todoRailWidth } from './layout/rail.js';
+import { TODO_LIMITS } from '../todo/limits.js';
+import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
 import { useTerminalSize } from './layout/useTerminalSize.js';
 import { frameHeight, MIN_FULLSCREEN_ROWS } from './layout/frame.js';
 import { HINT_MIN_ROWS, viewportRows as computeViewportRows } from './layout/budget.js';
@@ -144,6 +149,66 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const pendingHuman = useRef(new Set());
     /** Written by `AppShell`'s layout effect, read at wheel-event time (§4.5). */
     const geometryRef = useRef(UNMEASURED_GEOMETRY);
+    // --- Follow-through (todo-plan-followthrough §3.4). ---------------------
+    //
+    // THREE REFS AND NO VIEW STATE, DELIBERATELY (§5.2). Every field added to
+    // `ViewState` is a field `restoreEntries`, `/clear`, `/reset` and the session
+    // round-trip each have to have an opinion about, and none of them has an
+    // opinion about a 3-second timer.
+    const budgetRef = useRef(emptyBudget());
+    const followTimer = useRef(null);
+    /** True while the run in flight was started by the grace timer, not the user. */
+    const autoContinuationRef = useRef(false);
+    /**
+     * WHY THE END REASON TRAVELS IN A REF THIS FEATURE OWNS (C-11 / D-17).
+     *
+     * `ViewState.aborted` / `.errorNoticed` are the DEFINITION of the end reason —
+     * `runEnd` reads exactly that pair for its own silent-failure guard — but the
+     * reducer is not a safe CHANNEL for it, because the answer is needed inside a
+     * controller callback rather than during a render.
+     *
+     * Reading `stateRef.current` there happens to work under Ink 5 only because
+     * Ink mounts a LEGACY root (`ink.js`: `createContainer(rootNode, 0 …)`), so a
+     * dispatch from a promise context flushes synchronously. Under a concurrent
+     * root — an Ink major bump, or its `experimental` renderer — React 18's
+     * automatic batching returns, and a provider stream error emitted as
+     * `message_update` immediately before `agent_end` (core throws in the loop and
+     * emits `agent_end` from `runLoopWithLifecycle`'s `finally`, microtasks apart)
+     * would still read `errorNoticed: false`. That auto-continues into a run that
+     * just failed authentication: silent, and billable.
+     *
+     * So this ref is mutated in the SAME SYNCHRONOUS CALLBACK that dispatches the
+     * corresponding action, and the reducer fields stay as the cross-check.
+     */
+    const endReasonRef = useRef({
+        aborted: false,
+        errored: false,
+    });
+    /**
+     * Disarm an armed continuation. Idempotent; NEVER touches the budget — a
+     * cancelled continuation was never issued, so it must not be charged (AC-18).
+     *
+     * Three callers and there must be no fourth: `Esc` in the idle branch, the
+     * first line of `submitMessage`, and the subscription effect's cleanup.
+     */
+    const cancelFollowThrough = useCallback(() => {
+        if (followTimer.current) {
+            clearTimeout(followTimer.current);
+            followTimer.current = null;
+        }
+    }, []);
+    /**
+     * `submitMessage` as of the LATEST render, for the grace timer.
+     *
+     * The subscription effect below never re-runs (its deps are stable by
+     * construction), so a direct call would close over the mount render's binding
+     * forever. That binding happens to be functionally correct today because
+     * `submitMessage` reads everything mutable through refs — which is exactly the
+     * kind of "happens to be correct" this feature has already had to unwind once
+     * (P1-1, P1-6). Assigned during render, the same discipline `stateRef` uses
+     * twenty lines up.
+     */
+    const submitRef = useRef(() => { });
     /**
      * THE SINGLE SETTLE PATH for a human request. Idempotent per entry, and it
      * clears the overlay as its last act.
@@ -200,6 +265,14 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         const unsubscribe = controller.subscribe((event) => {
             const cost = controller.getModelInfo().cost;
             for (const action of reduceEvent(event, cost)) {
+                // MUTATED HERE, ONE INSTANT BEFORE THE ACTION THAT SETS
+                // `ViewState.errorNoticed`, rather than read back from the reducer one
+                // commit later (C-11). This is the whole of the batching-independence
+                // guarantee: `agent_end` can follow this action in the same tick with no
+                // render in between, and AC-40 asserts exactly that sequence.
+                if (action.type === 'notice' && action.level === 'error') {
+                    endReasonRef.current.errored = true;
+                }
                 if (action.type === 'textDelta' || action.type === 'thinkingDelta') {
                     pending.current.push(action);
                     if (!flushTimer.current) {
@@ -220,6 +293,69 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             // Without it, an aborted run leaves a plan card on screen whose `a` key
             // silently flips the session to build, with no visible cause.
             cancelPendingHuman();
+            // --- Follow-through (todo-plan-followthrough §3.4). ------------------
+            //
+            // Round 1 printed one notice here and stopped, under a good argument
+            // ("auto-continuation is an unbounded cost loop wearing a helpful hat").
+            // That judgement is not overturned: the loop is BOUNDED first, by two
+            // structural counters, and only then permitted — opt-in, and off by
+            // default, so `followThrough: 'notify'` reproduces the old notice byte for
+            // byte (AC-1).
+            const todos = controller.getTodoSnapshot();
+            budgetRef.current = advanceBudget(budgetRef.current, todos, autoContinuationRef.current);
+            autoContinuationRef.current = false;
+            const decision = decideFollowThrough({
+                // FROM THE CONTROLLER, NOT FROM `cfg` (P1-1). This effect's dependency
+                // list never changes, so it closes over the `cfg` object from the render
+                // in which it mounted — and `setTodoConfig` builds a NEW object, which
+                // that closure will never see. `cfg.todo.followThrough` would therefore
+                // be pinned to the launch value for the whole session and
+                // `/todo follow auto` would report success and do nothing. Note the
+                // asymmetry with `showStrip` further down, which is right to use `cfg`
+                // because it runs in render scope where `cfg` is re-read every frame.
+                mode: controller.getTodoConfig().followThrough,
+                snapshot: todos,
+                runEnd: { ...endReasonRef.current },
+                budget: budgetRef.current,
+                interactive: true,
+            });
+            endReasonRef.current = { aborted: false, errored: false };
+            if (decision.kind === 'notify') {
+                dispatch({ type: 'notice', level: decision.level, text: decision.text });
+            }
+            else if (decision.kind === 'continue') {
+                dispatch({ type: 'notice', level: 'info', text: decision.notice });
+                // NO LIVE COUNTDOWN (D-10). The notice is written once and does not
+                // tick: a 10 Hz re-render of the whole frame to animate a number is the
+                // repaint cost this package refuses elsewhere, and Ink's two dedupe
+                // gates mean the alternative is not free either.
+                cancelFollowThrough(); // I-3: at most one armed continuation, ever
+                followTimer.current = setTimeout(() => {
+                    followTimer.current = null;
+                    // TWO RE-CHECKS AT FIRE TIME, not only at decision time. The grace
+                    // window is 3 s and the user can type in it (C-6): without the first,
+                    // a fired continuation would either be swallowed into
+                    // `controller.steer()` (the quiet failure) or reach
+                    // `controller.prompt()`, which REJECTS while running.
+                    if (controller.isRunning())
+                        return;
+                    const live = controller.getTodoSnapshot();
+                    if (!live || live.doneCount >= live.total)
+                        return; // the list moved
+                    budgetRef.current = { ...budgetRef.current, used: budgetRef.current.used + 1 };
+                    autoContinuationRef.current = true;
+                    // COUNTS ONLY, NEVER ITEM TEXT (D-19), and only at the fire point —
+                    // the quiet paths must stay quiet.
+                    getLogger().debug('agent', 'todo_follow', {
+                        used: budgetRef.current.used,
+                        noProgressStreak: budgetRef.current.noProgressStreak,
+                        total: live.total,
+                        done: live.doneCount,
+                        mode: 'auto',
+                    });
+                    submitRef.current(decision.message, { userInitiated: false });
+                }, decision.graceMs);
+            }
             // A deferred `plan -> build` becomes real here and nowhere else (§3.2).
             const applied = controller.applyPendingMode();
             if (applied) {
@@ -233,9 +369,13 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         });
         return () => {
             flushPending();
+            // An armed continuation must not outlive the tree that armed it (AC-21):
+            // the timer would fire into an unmounted App and `submitRef.current` would
+            // prompt a controller nobody is rendering.
+            cancelFollowThrough();
             unsubscribe();
         };
-    }, [controller, flushPending, cancelPendingHuman]);
+    }, [controller, flushPending, cancelPendingHuman, cancelFollowThrough]);
     // --- Team-mode event stream (team-subagents §5.2 / §3.9). --------------
     //
     // A SEPARATE SUBSCRIPTION, not a branch in the one above: `TeamEvent` is
@@ -292,6 +432,34 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             controller.dispose();
         };
     }, [controller]);
+    // --- Todo event stream (todo-plan-execution §3.8 / §5.2). --------------
+    //
+    // A THIRD SUBSCRIPTION, for the reason the team one records: `TodoEvent` is
+    // deliberately not a member of core's `AgentEvent` union (D-11), so it cannot
+    // arrive through `controller.subscribe`.
+    //
+    // NOT ROUTED THROUGH THE STREAMING COALESCER either. That buffer exists to
+    // merge text/thinking deltas; a `todo_write` is one deliberate act per step,
+    // and delaying the one surface the user is watching a long task through would
+    // be exactly backwards.
+    useEffect(() => {
+        return controller.subscribeTodos((event) => {
+            switch (event.type) {
+                case 'updated':
+                    dispatch({ type: 'todoUpdate', snapshot: event.snapshot });
+                    break;
+                case 'cleared':
+                    dispatch({ type: 'todoCleared' });
+                    break;
+                case 'rejected':
+                    // THE COMPENSATING PATH FOR SUPPRESSING THE TOOL CARD (§3.8). Without
+                    // it, the one case where `todo_write` produces nothing visible would
+                    // be the case that most needs to be visible.
+                    dispatch({ type: 'notice', level: 'warn', text: event.reason });
+                    break;
+            }
+        });
+    }, [controller]);
     // --- Elapsed timer + tokens/sec baseline while running. ----------------
     useEffect(() => {
         if (state.status !== 'running') {
@@ -495,9 +663,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         toast,
         persistConfig,
         exit: doExit,
-        submit: (text) => submitMessage(text),
+        submit: (text, opts) => submitMessage(text, opts),
         refreshSkills: () => setSkillsNonce((n) => n + 1),
         applyAgentMode: applyMode,
+        // Read at command time, so `/todo status` reports the live count rather than
+        // whatever it was when this context was built.
+        followBudget: budgetRef.current,
     });
     /**
      * Submitting a prompt no longer touches `config.json` at all — it appends one
@@ -527,13 +698,26 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
      * `handleSubmit` would re-parse it as input and, for a body that happens to
      * start with `/`, recurse into command dispatch.
      */
-    const submitMessage = (message) => {
+    const submitMessage = (message, opts = {}) => {
+        // A USER MESSAGE IS A NEW INTENT AND OUTRANKS A QUEUED ONE (AC-19). First
+        // line, before the steering branch: a message typed during the grace window
+        // must be the one that runs, whichever branch it takes.
+        cancelFollowThrough();
         if (stateRef.current.status === 'running') {
             controller.steer(message);
             toast('info', 'Steering queued.');
             return;
         }
-        recordPrompt(message);
+        // `userInitiated: false` skips TWO things and both are wanted: the
+        // prompt-history append, and the `submitCount` bump that drives the
+        // composer's hint fade. An auto-continuation demonstrates nothing about what
+        // the user has learned, so suppressing the fade is correct rather than
+        // incidental — which is why the parameter is named for the CAUSE (P2-8).
+        if (opts.userInitiated !== false)
+            recordPrompt(message);
+        // Mirrors where the reducer clears its own copies, in the same action
+        // (C-11): a new turn's end reason must not inherit the previous one's.
+        endReasonRef.current = { aborted: false, errored: false };
         dispatch({ type: 'submit', text: message });
         const pre = controller.preflight();
         if (!pre.ok) {
@@ -544,6 +728,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         // Fire-and-forget: events drive the UI. prompt() never rejects.
         void controller.prompt(message);
     };
+    submitRef.current = submitMessage;
     const handleSubmit = async (raw) => {
         // Submitting is an unconditional "take me to the newest output" (§4.5).
         setPinToBottomNonce((n) => n + 1);
@@ -782,8 +967,24 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             }
             if (stateRef.current.status === 'running') {
                 controller.abort();
+                // Next to `abortMark`, in the same callback, for the reason
+                // `endReasonRef`'s own comment gives (C-11). D-5 turns this into
+                // silence at `agent_end`: the user's Esc is the statement, and
+                // restating what they interrupted is the CLI arguing.
+                endReasonRef.current.aborted = true;
                 dispatch({ type: 'abortMark' });
                 toast('info', 'Run aborted.');
+                return;
+            }
+            // IDLE. Today this branch does nothing at all, which is what makes it free
+            // to take (R-4). OVERLAY PRECEDENCE IS UNCHANGED AND DELIBERATE (P2-9):
+            // the block above returns while an overlay is open, so with one open the
+            // first Esc closes the overlay and the second cancels the continuation.
+            // Reaching past it would make "close this dialog" silently also mean
+            // "abandon the plan".
+            if (followTimer.current) {
+                cancelFollowThrough();
+                toast('info', 'Auto-continue cancelled.');
             }
             return;
         }
@@ -802,6 +1003,40 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // tells `OverlayFrame` to render everything and show no position indicator.
     const viewportBudget = computeViewportRows(rows);
     const overlayMaxRows = fullscreen ? viewportBudget : Number.POSITIVE_INFINITY;
+    // --- The todo rail (todo-plan-execution §3.9). --------------------------
+    //
+    // ONE NUMBER FOR THE GATE AND FOR THE LAYOUT (I-10). `railRows` is both what
+    // decides whether the panel mounts and what the panel lays out against; a
+    // panel that mounts on one number and renders against another shows nothing
+    // and reports nothing. `todoRailRows` is NOT `viewportBudget`: the live team
+    // roster costs up to 8 rows inside `AppShell`'s measured bottom box that the
+    // budget knows nothing about (P1-3).
+    const railRows = todoRailRows(viewportBudget, state.team !== null);
+    const railWidth = todoRailWidth(cols);
+    const showRail = fullscreen && // non-goal 4: inline mode has no fixed frame
+        cfg.todo.panel && // `/todo panel off`, persisted
+        overlay === null && // a modal owns the screen (D-7)
+        state.todos !== null && // no list -> no furniture, zero layout cost
+        railWidth > 0 && // too narrow (under 80 columns)
+        railRows >= TODO_LIMITS.panelMinRows; // too short to say anything useful
+    // The inline plan strip (todo-plan-followthrough §3.7 / W2).
+    //
+    // DELIBERATELY NOT `!showRail`, which is true for FOUR different reasons and
+    // three of them mean "do not draw this". `cfg.todo.panel` is included because
+    // `--no-todo-panel` means "keep the planning, drop the display" and a strip is
+    // a display. Overlays are NOT consulted: inline mode's overlays are part of
+    // the document flow, not a modal that owns the screen.
+    //
+    // `cfg` is the right read here and `controller.getTodoConfig()` would be
+    // needless — this runs in RENDER scope, where `cfg` is re-read every frame.
+    // The asymmetry with the `agent_end` handler above is the whole of P1-1.
+    const showStrip = !fullscreen && cfg.todo.panel && state.todos !== null;
+    // Every consumer INSIDE the viewport slot switches to this; the header,
+    // composer, status bar, toasts and every overlay keep the full frame width
+    // (C-7). Overlays keep it because `showRail` already includes `overlay ===
+    // null`: splitting the screen with a status panel behind a modal is both worse
+    // design and a second source of width-contract bugs in six components.
+    const contentCols = cols - (showRail ? railWidth : 0);
     const overlayNode = overlay === 'help' ? (_jsx(OverlayFrame, { title: "Help", hint: `Esc close ${glyphs.midDot} PgUp/PgDn scroll`, maxRows: overlayMaxRows, cols: cols, rows: helpRows(theme, caps), scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps })) : overlay === 'model' ? (_jsx(ModelPicker, { registry: controller.getModelRegistry(), currentProvider: cfg.provider, currentModel: cfg.model, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onSelect: handleModelSelect })) : overlay === 'settings' ? (_jsx(SettingsScreen, { initial: {
             provider: cfg.provider,
             model: cfg.model,
@@ -834,15 +1069,15 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // The wordmark + getting-started card now live INSIDE the viewport, as its
     // first block of content, so they scroll away instead of being yanked out of
     // the header the moment the first message lands.
-    const opener = empty ? (_jsx(SessionOpener, { variant: fullscreen ? pickOpenerVariant(viewportBudget, cols, caps) : 'none', version: version, cwd: controller.getCwd(), hasKey: hasKey, viewportRows: fullscreen ? viewportBudget : Number.POSITIVE_INFINITY, theme: theme, caps: caps })) : null;
+    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 viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, showScrollIndicator: true, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps, windowSize: cfg.transcriptWindow ?? DEFAULT_TRANSCRIPT_WINDOW })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, 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: reducedMotion, density: density, theme: theme, caps: caps, windowSize: cfg.transcriptWindow ?? DEFAULT_TRANSCRIPT_WINDOW })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, 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, historyIntent: historyIntent, 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, geometryRef: geometryRef, header: header, viewport: viewport, team: state.team ? (_jsx(TeamPanel, { snapshot: state.team, rows: rows, cols: cols, reducedMotion: reducedMotion, theme: theme, caps: caps })) : null, toast: _jsx(ToastStack, { toasts: state.toasts, theme: theme, mode: mode }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode, ...(state.team
+    return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, geometryRef: geometryRef, 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(ToastStack, { toasts: state.toasts, theme: theme, mode: mode }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode, ...(state.team
                 ? {
                     teamActive: {
                         running: state.team.runs.filter((r) => r.phase !== 'queued' && r.phase !== 'done' &&
@@ -850,5 +1085,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
                         total: state.team.runs.length,
                     },
                 }
+                : {}), ...(state.todos && !showRail
+                ? { todoActive: { done: state.todos.doneCount, total: state.todos.total } }
                 : {}) }) }));
 }

package/dist/ui/StatusBar.d.ts

@@ -70,6 +70,24 @@ interface StatusBarProps {
         running: number;
         total: number;
     };
+    /**
+     * Live todo counts (todo-plan-execution §6.3), or absent.
+     *
+     * `App` sends this ONLY when a list exists AND the rail does not: with the
+     * rail on screen the numbers are already there in a larger typeface, and
+     * duplicating them costs the context gauge columns it cannot spare. This is
+     * therefore the INLINE-MODE and NARROW-TERMINAL fallback for R-d, which is
+     * exactly why it is here rather than being folded into the rail's own gate.
+     *
+     * Degrades below `TODO_LIMITS.statusCompactCols` from `todo 2/7` to `[2/7]`,
+     * the same treatment and the same justification as the team counter's
+     * `agents 3/5` -> `[3]`. See the note on `agentMode` for why that rule does
+     * NOT apply to the mode word.
+     */
+    todoActive?: {
+        done: number;
+        total: number;
+    };
 }
 export declare function StatusBar(props: StatusBarProps): React.ReactElement;
 export {};

package/dist/ui/StatusBar.js

@@ -5,6 +5,7 @@ import { formatCost, formatTokens, formatDuration } from '../agent/usage.js';
 import { buildGauge } from './gauge.js';
 import { MODE_LABEL } from '../agent/agent-mode.js';
 import { TEAM_LIMITS } from '../team/limits.js';
+import { TODO_LIMITS } from '../todo/limits.js';
 /**
  * I-5 — DO NOT "CLEAN THIS UP". Ink short-circuits identical output at TWO
  * gates (`ink.js:132` and `log-update.js:13`), so a fixed frame whose React
@@ -24,7 +25,7 @@ function redrawChar(nonce) {
     return nonce % 2 === 0 ? ' ' : NBSP;
 }
 export function StatusBar(props) {
-    const { model, provider, usageTotal, contextTokens, contextWindow, contextWindowKnown, status, elapsedMs, thinkingLevel, tokPerSec, theme, caps, scrolledLines = 0, redrawNonce = 0, agentMode = 'build', pendingAgentMode = null, teamActive, } = props;
+    const { model, provider, usageTotal, contextTokens, contextWindow, contextWindowKnown, status, elapsedMs, thinkingLevel, tokPerSec, theme, caps, scrolledLines = 0, redrawNonce = 0, agentMode = 'build', pendingAgentMode = null, teamActive, todoActive, } = props;
     const { stdout } = useStdout();
     const cols = stdout?.columns ?? 80;
     const running = status === 'running';
@@ -50,5 +51,7 @@ export function StatusBar(props) {
     // land in one predictable place.
     _jsxs(Box, { flexDirection: "row", justifyContent: "space-between", flexShrink: 0, children: [_jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsxs(Text, { color: running ? theme.toolRunning : theme.toolDone, children: [redrawChar(redrawNonce), statusGlyph, " ", running ? 'running' : 'idle'] }), modeWord && (_jsxs(Text, { color: theme.accent, bold: true, children: ['  ', modeWord] })), teamActive && (_jsxs(Text, { color: theme.toolRunning, bold: true, children: ['  ', cols >= TEAM_LIMITS.statusCompactCols
                                 ? `agents ${teamActive.running}/${teamActive.total}`
-                                : `[${teamActive.running}]`] })), cols >= 60 && (_jsxs(Text, { color: theme.muted, children: ['  ', provider, ":", model] })), thinkingLevel !== 'off' && cols >= 72 && (_jsxs(Text, { color: theme.accent, children: ["  think:", thinkingLevel] }))] }), _jsxs(Box, { flexDirection: "row", children: [scrolledLines > 0 && (_jsxs(Text, { color: theme.noticeWarn, children: [glyphs.arrowUp, scrolledLines, '  '] })), cols >= 60 && (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "[" }), _jsx(Text, { color: gauge.fillColor, children: gauge.filled }), _jsx(Text, { color: gauge.trackColor, children: gauge.empty }), _jsx(Text, { color: theme.muted, children: "] " })] })), _jsx(Text, { color: theme.muted, children: pctLabel }), cols >= 72 && _jsxs(Text, { color: theme.muted, children: ["  ", tokens] }), _jsxs(Text, { color: theme.muted, children: ["  ", formatCost(usageTotal.costUsd)] }), running && (_jsxs(Text, { color: theme.muted, children: [tokPerSec > 0 && cols >= 72 ? `  ${tokPerSec} tok/s` : '', "  ", formatDuration(elapsedMs)] }))] })] }));
+                                : `[${teamActive.running}]`] })), todoActive && (_jsxs(Text, { color: theme.accent, children: ['  ', cols >= TODO_LIMITS.statusCompactCols
+                                ? `todo ${todoActive.done}/${todoActive.total}`
+                                : `[${todoActive.done}/${todoActive.total}]`] })), cols >= 60 && (_jsxs(Text, { color: theme.muted, children: ['  ', provider, ":", model] })), thinkingLevel !== 'off' && cols >= 72 && (_jsxs(Text, { color: theme.accent, children: ["  think:", thinkingLevel] }))] }), _jsxs(Box, { flexDirection: "row", children: [scrolledLines > 0 && (_jsxs(Text, { color: theme.noticeWarn, children: [glyphs.arrowUp, scrolledLines, '  '] })), cols >= 60 && (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "[" }), _jsx(Text, { color: gauge.fillColor, children: gauge.filled }), _jsx(Text, { color: gauge.trackColor, children: gauge.empty }), _jsx(Text, { color: theme.muted, children: "] " })] })), _jsx(Text, { color: theme.muted, children: pctLabel }), cols >= 72 && _jsxs(Text, { color: theme.muted, children: ["  ", tokens] }), _jsxs(Text, { color: theme.muted, children: ["  ", formatCost(usageTotal.costUsd)] }), running && (_jsxs(Text, { color: theme.muted, children: [tokPerSec > 0 && cols >= 72 ? `  ${tokPerSec} tok/s` : '', "  ", formatDuration(elapsedMs)] }))] })] }));
 }

package/dist/ui/TodoPanel.d.ts

@@ -0,0 +1,48 @@
+/**
+ * TodoPanel — the right rail (todo-plan-execution §6.1).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`; a literal here bypasses the
+ * capability probe and shows mojibake on a legacy console (`glyphs.ts` header).
+ *
+ * MOUNTED ONLY WHEN A LIST EXISTS. `App` passes `null` the rest of the time and
+ * this component is not rendered at all, so a session that never plans has zero
+ * columns and zero layout shift (R-g's "no furniture when idle" / AC-24).
+ *
+ * IT MUST BE MOUNTED IN `AppShell`'s MIDDLE BAND, NEVER 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.
+ *
+ * WIDTH IS MEASURED IN COLUMNS, NEVER IN CODE UNITS (P2-3). This rail is 18-36
+ * columns wide and the system prompt's last line is "Respond in the language the
+ * user writes in", so CJK item text in an 18-column rail is the NORMAL case
+ * rather than the edge case. Every text cell is `wrap="truncate"` and Ink's
+ * truncation is display-width aware, so nothing can overflow the box — and NO
+ * ARITHMETIC HERE MAY BUDGET USER TEXT BY `.length`. The `padEnd(3)` /
+ * `padStart(2)` cells below are ASCII markers and indices, which is why they are
+ * safe; a "characters that fit" calculation over `content` would not be. That is
+ * the whole of the lesson `TeamPanel`'s `WIDE_CHAR_ALLOWANCE` records at length,
+ * and the mitigation here is to have no such budget at all.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+import type { TodoSnapshot } from '../todo/types.js';
+export interface TodoPanelProps {
+    snapshot: TodoSnapshot;
+    /** From `todoRailWidth(cols)`. The rail's whole column budget, separator included. */
+    width: number;
+    /**
+     * From `todoRailRows(viewportBudget, teamActive)` — NOT `viewportBudget`
+     * (I-10 / P1-3). The gate that mounts this component and the number it lays
+     * out against are ONE value computed once in `App`: a panel that mounts on one
+     * number and lays out against another renders nothing and reports nothing.
+     */
+    rows: number;
+    /** Whether the agent is running; gates the spinner (never animate when idle). */
+    running: boolean;
+    reducedMotion: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function TodoPanel({ snapshot, width, rows, running, reducedMotion, theme, caps, }: TodoPanelProps): React.ReactElement;

package/dist/ui/TodoPanel.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { pickGlyphs } from './glyphs.js';
+import { buildGauge } from './gauge.js';
+import { railBorderProps } from './layout/Gutter.js';
+import { TODO_RAIL_INDEX_MIN_COLS } from './layout/rail.js';
+import { TODO_LIMITS } from '../todo/limits.js';
+import { selectTodoRows } from '../todo/panel-rows.js';
+/** Header row + the blank row under the gauge. */
+const FIXED_ROWS = 2;
+/** The gauge is the one purely decorative element, so it is the first to go. */
+const GAUGE_MIN_ROWS = 8;
+const GAUGE_MIN_COLS = 20;
+/** Separator column + one space of padding, supplied by `railBorderProps`. */
+const CHROME_COLS = 2;
+/** Marker cell. Three, because the ASCII tier's `[x]` / `[ ]` are three wide. */
+const MARKER_COLS = 3;
+/** Index cell: two digits plus the space that separates it from the text. */
+const INDEX_COLS = 3;
+function marker(item, glyphs) {
+    if (item.status === 'completed')
+        return glyphs.todoDone;
+    if (item.status === 'in_progress')
+        return glyphs.todoActive;
+    return glyphs.todoPending;
+}
+function rowColor(item, theme) {
+    if (item.status === 'completed')
+        return theme.muted;
+    if (item.status === 'in_progress')
+        return theme.primary;
+    return theme.hintFg ?? theme.muted;
+}
+export function TodoPanel({ snapshot, width, rows, running, reducedMotion, theme, caps, }) {
+    const glyphs = pickGlyphs(caps);
+    const showGauge = width >= GAUGE_MIN_COLS && rows >= GAUGE_MIN_ROWS;
+    const showIndex = width >= TODO_RAIL_INDEX_MIN_COLS;
+    const itemRows = Math.max(1, rows - FIXED_ROWS - (showGauge ? 1 : 0));
+    const { visible, hiddenAbove, hiddenBelow } = selectTodoRows(snapshot.items, itemRows);
+    const pct = snapshot.total > 0 ? Math.round((snapshot.doneCount / snapshot.total) * 100) : 0;
+    const gauge = buildGauge(pct, Math.max(4, width - CHROME_COLS - 2), theme, caps);
+    const complete = snapshot.doneCount === snapshot.total;
+    return (
+    // `flexShrink={0}` IS LOAD-BEARING (P1-4). Ink's `Box.defaultProps` is
+    // `{ flexWrap:'nowrap', flexDirection:'row', flexGrow:0, flexShrink:1 }`, so
+    // a `width={n}` box inside a shrinking row is SQUEEZED under pressure — and
+    // every piece of arithmetic in `rail.ts` silently becomes a suggestion at
+    // exactly the narrow widths where the guarantee matters. `ScrollIndicator`
+    // spells the same pair one level down. Cross-axis height needs no prop:
+    // `alignItems` is unset in this tree and yoga's default is `stretch`.
+    _jsxs(Box, { flexDirection: "column", flexShrink: 0, width: width, overflow: "hidden", paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(Text, { wrap: "truncate", color: theme.accent, bold: true, children: "TODO" }), _jsxs(Text, { wrap: "truncate", color: complete ? theme.toolDone : theme.muted, children: [snapshot.doneCount, "/", snapshot.total, complete ? ' done' : ''] })] }), showGauge && (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: gauge.fillColor, children: gauge.filled }), _jsx(Text, { color: gauge.trackColor, children: gauge.empty })] })), _jsx(Text, { children: " " }), hiddenAbove > 0 && (_jsxs(Text, { wrap: "truncate", color: theme.muted, children: ['   ', "+", hiddenAbove, " above"] })), visible.map(({ item, index }) => {
+                const active = item.status === 'in_progress';
+                // The spinner is gated on `running`: a spinner while the agent is idle
+                // is a lie about the state of the world, and this panel outlives the run
+                // that filled it. Reduced motion and a non-Unicode terminal fall back to
+                // the same static marker, exactly as `AssistantEntry` and `TeamPanel` do.
+                const animate = active && running && !reducedMotion && caps.unicode;
+                return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Box, { flexShrink: 0, width: MARKER_COLS, children: _jsx(Text, { color: rowColor(item, theme), bold: active, children: animate ? _jsx(Spinner, { type: "dots" }) : marker(item, glyphs) }) }), showIndex && (_jsx(Box, { flexShrink: 0, width: INDEX_COLS, children: _jsx(Text, { color: theme.muted, children: String(index + 1).padStart(2) }) })), _jsx(Box, { flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Text, { wrap: active ? 'wrap' : 'truncate', color: rowColor(item, theme), bold: active, children: active ? clampWrapped(item.activeForm, width) : item.content }) })] }, `${index}-${item.content}`));
+            }), hiddenBelow > 0 && (_jsxs(Text, { wrap: "truncate", color: theme.muted, children: ['   ', "+", hiddenBelow, " more"] }))] }));
+}
+/**
+ * Keep the wrapping row inside `TODO_LIMITS.activeWrapRows`.
+ *
+ * A CHARACTER BUDGET IS NOT A COLUMN BUDGET (P2-3), so this is deliberately
+ * generous rather than exact: it exists to stop a maximum-length `activeForm`
+ * from claiming five rows of an 18-column rail, and Ink's display-width-aware
+ * truncation is what actually keeps the row inside the box. Erring long costs
+ * nothing — the surrounding `overflow="hidden"` clips it.
+ */
+function clampWrapped(text, width) {
+    const budget = Math.max(1, width - CHROME_COLS) * TODO_LIMITS.activeWrapRows;
+    return text.length > budget ? text.slice(0, budget) : text;
+}

package/dist/ui/TodoStrip.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TodoStrip — the inline-mode plan surface (todo-plan-followthrough §3.7 / W2).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`; a literal here bypasses the
+ * capability probe and shows mojibake on a legacy console. This file is inside
+ * the glyph scanner's scope because it is under `ui/`, NOT because of the
+ * `todo/` clause (C-4) — moving it would not move the guard rail with it.
+ *
+ * WHY A STRIP AND NOT THE RAIL. `decideRenderMode` picks inline for every pipe,
+ * every `CI=1`, every `TERM=dumb` and every terminal under 12 rows, and inline
+ * has no fixed frame to hang a column off (round 1's non-goal 4). Before this,
+ * such a session had the tool and a `todo 3/7` counter in the status bar, and no
+ * way at all to see WHICH step was running (OQ-1).
+ *
+ * WHY NOT IN THE STATUS BAR. The bar's left cluster is `flexShrink={0}` and its
+ * own comment records what happens when the row over-subscribes: Ink drops a
+ * character from EACH cluster and it renders `idl` / `? hel`. A variable-length
+ * step title cannot go there (C-7), which is what forces this into its own row.
+ *
+ * EXACTLY ONE RENDERED ROW, ALWAYS (AC-29). A strip that wrapped would push the
+ * composer down by an unpredictable number of rows on every keystroke, which is
+ * the worst possible behaviour for the mode with no frame to absorb it — hence
+ * `wrap="truncate"` inside a `flexGrow`/`flexShrink` box and no exceptions.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+import type { TodoSnapshot } from '../todo/types.js';
+export interface TodoStripProps {
+    snapshot: TodoSnapshot;
+    /** Full terminal width; the strip spans the row in inline mode. */
+    cols: number;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function TodoStrip({ snapshot, cols, theme, caps }: TodoStripProps): React.ReactElement;

package/dist/ui/TodoStrip.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { pickGlyphs } from './glyphs.js';
+import { TODO_LIMITS } from '../todo/limits.js';
+import { todoAnchorIndex } from '../todo/panel-rows.js';
+export function TodoStrip({ snapshot, cols, theme, caps }) {
+    const glyphs = pickGlyphs(caps);
+    // THE SAME FUNCTION THE RAIL USES (R-9 / AC-30). Two surfaces that each decide
+    // for themselves which step is "current" is two surfaces that disagree, and
+    // this one is on screen in exactly the mode where the rail is not, so the
+    // disagreement would never be seen side by side and never be reported.
+    const anchor = todoAnchorIndex(snapshot.items);
+    const item = snapshot.items[anchor];
+    const active = item?.status === 'in_progress';
+    // `activeForm` while in progress, `content` otherwise — `TodoPanel`'s rule.
+    const label = item ? (active ? item.activeForm : item.content) : '';
+    // The same degradation the status bar already applies, so the two counters can
+    // never disagree about how much room they need.
+    const counter = cols >= TODO_LIMITS.statusCompactCols
+        ? `todo ${snapshot.doneCount}/${snapshot.total}`
+        : `[${snapshot.doneCount}/${snapshot.total}]`;
+    const showDone = snapshot.doneCount > 0 && cols >= TODO_LIMITS.stripDoneCols;
+    return (
+    // `width` IS LOAD-BEARING, exactly as it is on `TodoPanel` and for a related
+    // reason. Inline mode has no fixed frame, so nothing upstream constrains
+    // this row: without an explicit width the flexible middle cell is sized by
+    // whatever the parent offers, and a long item overflows the terminal and
+    // WRAPS — the one thing this component exists not to do. Pinning it here
+    // makes the truncation deterministic and self-contained rather than a
+    // property of the tree above.
+    _jsxs(Box, { flexDirection: "row", width: cols, overflow: "hidden", children: [_jsx(Box, { flexShrink: 0, children: _jsx(Text, { wrap: "truncate", color: theme.accent, children: counter }) }), _jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: theme.muted, children: [' ', glyphs.arrowRight, ' '] }) }), _jsx(Box, { flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Text, { wrap: "truncate", color: active ? theme.primary : theme.muted, bold: active, children: label }) }), showDone && (_jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: theme.muted, children: [' ', "+", snapshot.doneCount, " done"] }) }))] }));
+}