@aragon-agent/cli 0.5.11 → 0.6.1

package/dist/ui/ActivityLine.js

@@ -3,6 +3,24 @@ import { Box, Text } from 'ink';
 import Spinner from 'ink-spinner';
 import { pickGlyphs } from './glyphs.js';
 import { pickActivityPhrase } from './activity-phrases.js';
+/**
+ * The animated spinner this row draws while it is live, or `null` when it would
+ * be STATIC — an ASCII terminal, or a user who asked for stillness.
+ *
+ * A FACTORY, NOT A COMPONENT, and the distinction is load-bearing. A
+ * `<LiveSpinner/>` element whose own render returned `null` would still be
+ * truthy at the call site — the exact trap `BottomStatusRow`'s `update` prop
+ * documents at length. Callers test the RETURN VALUE and get a real answer.
+ *
+ * It is exported so `BottomStatusRow` can put the bare glyph beside a toast
+ * without importing `ink-spinner` itself: `spinner-census.test.ts` enumerates
+ * every file under `src/ui/**` that imports it, and that list is the checklist
+ * for "who is allowed to animate". One more importer is one more site a future
+ * reader has to reason about; one more caller of this function is not.
+ */
+export function liveSpinner(reducedMotion, caps) {
+    return caps.unicode && !reducedMotion ? _jsx(Spinner, { type: "dots" }) : null;
+}
 export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, theme, caps, }) {
     const glyphs = pickGlyphs(caps);
     // PURE AND DERIVED FROM `(startedAt, now)`, so the sequence does not need to
@@ -17,6 +35,10 @@ export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool,
     // The IDENTICAL branch `Transcript.tsx` uses for the assistant role marker, and
     // it must stay identical: braille dots are both an animation AND a Unicode-only
     // glyph, so reduced motion and an ASCII terminal fall back to the same marker.
-    const spinner = caps.unicode && !reducedMotion ? _jsx(Spinner, { type: "dots" }) : glyphs.spinnerStill;
+    //
+    // Through `liveSpinner` rather than inline, so this row and the glyph
+    // `BottomStatusRow` composes beside a toast can never disagree about WHEN the
+    // spinner is live — the same reason `App` names its mount condition once.
+    const spinner = liveSpinner(reducedMotion, caps) ?? glyphs.spinnerStill;
     return (_jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: theme.thinking, children: [' ', spinner, " ", label] }) }));
 }

package/dist/ui/App.d.ts

@@ -50,6 +50,19 @@ export interface AppProps {
      *  is off: inline mode, `--no-mouse`, a non-TTY, or a filter that failed to
      *  build (mouse-wheel-region-routing §4.2). */
     mouseSource?: MouseSource;
+    /**
+     * Present ONLY on a console that can deliver neither `CSI Z` nor a mouse
+     * report — a Windows console whose Node predates `UV_TTY_MODE_RAW_VT`
+     * (`ui/win-vt-input.ts`). Absent everywhere else, which is what makes every
+     * unaffected machine byte-identical to a build without this prop.
+     *
+     * DECIDED BY `cli.tsx`, not here, and by the SAME expression that gates
+     * `mouseSource`: the two must never disagree about whether this terminal
+     * reports anything.
+     */
+    vtInputWarning?: {
+        nodeVersion: string;
+    };
     /**
      * The auto-updater's late-arrival channel (cli-auto-update §3.8).
      *
@@ -60,4 +73,4 @@ export interface AppProps {
      */
     updateBridge?: UpdateBridge;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, updateBridge, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, }: AppProps): React.ReactElement;

package/dist/ui/App.js

@@ -14,7 +14,7 @@ import { computeCost } from '../agent/usage.js';
 import { parseMaxTokensInput, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from '../config/schema.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { appendPrompt, loadPromptHistory } from '../config/prompt-history.js';
-import { bumpSubmitCount, setMouseNoticeSeen } from '../config/ui-state.js';
+import { bumpSubmitCount, setMouseNoticeSeen, setVtInputNoticeSeen } from '../config/ui-state.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret } from '../logging/secret-registry.js';
 import { detectCapabilities } from './capabilities.js';
@@ -32,7 +32,7 @@ import { secondsLeft } from '../agent/retry-view.js';
 import { TeamPanel } from './TeamPanel.js';
 import { TodoPanel } from './TodoPanel.js';
 import { TodoStrip } from './TodoStrip.js';
-import { ActivityLine } from './ActivityLine.js';
+import { ActivityLine, liveSpinner } from './ActivityLine.js';
 import { BottomStatusRow } from './BottomStatusRow.js';
 import { UpdateLine } from './UpdateLine.js';
 // The updater's two PURE modules. `shouldRenderUpdateLine` decides the row's
@@ -110,7 +110,7 @@ export function resolveSettingsMaxTokens(raw, previous) {
 function seedViewState(thinkingVisible) {
     return initialViewState({ thinkingVisible });
 }
-export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, updateBridge, }) {
+export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const fullscreen = mode === 'fullscreen';
@@ -693,6 +693,8 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     }, [fullscreen]);
     // `enabled` is `mouseSource`, not `cfg.mouse`: a user whose terminal drops
     // the events must never be shown advice about a mode not in effect (§6.1).
+    // `cli.tsx::wantMouse` now folds the platform check into the same expression,
+    // so on a console that reports nothing there is no source and no advice.
     useStartupNotices(dispatch, {
         enabled: !!mouseSource,
         // `state.json`, not `config.json`: whether a one-shot notice has been shown
@@ -703,6 +705,20 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // `transcriptRetain` to `transcriptWindow` (tui-render-performance §5.1).
     cfg.transcriptRetainRequested !== undefined
         ? { requested: cfg.transcriptRetainRequested, resolved: cfg.transcriptRetain }
+        : undefined, 
+    // Its own one-shot key, NOT `mouseNoticeSeen`: everyone this notice is for
+    // has already run aragon at least once and already has that flag set.
+    //
+    // `fullscreen` goes with it because only half of the damage is mode-
+    // independent: `Shift+Tab` is broken either way, but inline never asked for
+    // wheel reports and does not own the scroll keys, so it must not be told
+    // about either.
+    vtInputWarning
+        ? {
+            nodeVersion: vtInputWarning.nodeVersion,
+            fullscreen,
+            onSeen: () => setVtInputNoticeSeen(true),
+        }
         : undefined);
     // --- Exit snapshot: the only way state reaches cli.tsx (§4.4). ----------
     useEffect(() => {
@@ -1422,6 +1438,41 @@ 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.
+    //
+    // THE CLAIM ABOVE WAS ONCE FALSE, AND THAT WAS THE WHOLE OF
+    // `activity-spinner-vanishes-behind-toast`. `BottomStatusRow` — not this const
+    // — decides what the row actually shows, and a toast used to take the row
+    // outright, so for its 2.5 s TTL this said "the line is up" while nothing was
+    // mounted and all seven other sites sat still. The answer was NOT to enumerate
+    // `&& !state.toasts.length` here (the next occupant reopens it, and the seven
+    // sites animating out of phase is the defect this whole feature removed):
+    // `BottomStatusRow` now carries the bare spinner alongside the toast, so the
+    // signal is mounted exactly when this const is true and the claim holds by
+    // construction.
+    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 +1491,33 @@ 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, 
+            // THE FORM THE LIFE SIGNAL TAKES WHEN A TOAST HAS THE ROW
+            // (`activity-spinner-vanishes-behind-toast`). Passed UNCONDITIONALLY:
+            // `BottomStatusRow` reads it only when `activity` above is non-null,
+            // so `activityVisible` stays the one mount condition and this cannot
+            // become a second copy of it that drifts. `null` here means the
+            // spinner would be static anyway (ASCII tier, or reduced motion), and
+            // those builds must come out unchanged.
+            activityGlyph: liveSpinner(reducedMotion, caps), 
             // 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/BottomStatusRow.d.ts

@@ -33,6 +33,23 @@
  * end, whereas an activity line deferred is an activity line that never renders.
  * That also means a user who is actively working never sees the updater at all
  * until they stop, which is the whole of the silence requirement.
+ *
+ * THE TOAST TAKES THE ROW BUT NOT THE SPINNER
+ * (`activity-spinner-vanishes-behind-toast`). "Toast wins" used to mean the
+ * activity line was never mounted while an ack was up — and because `App`
+ * suppresses the other seven animated sites for exactly as long as it BELIEVES
+ * this row is showing one, a mid-run toast left the whole frame with ZERO
+ * animations for its 2.5 s TTL, indistinguishable from a hung process. Steering
+ * and plan approval both ack mid-run, so a long run hit it repeatedly.
+ *
+ * The row still belongs to the toast: the spinner joins it as a bare glyph, no
+ * phrase and no clock, so `bottom-status-row.test.tsx`'s "the ack keeps its
+ * words" assertion and the toast's own width are both untouched. A row-direction
+ * box holding two one-row children is STILL ONE ROW, which is what the note
+ * above actually forbids disturbing — `budget.ts` and `AppShell.tsx` stay out of
+ * it. And because the glyph is mounted under precisely the condition `App` uses
+ * to suppress the others, "the line is up" and "every other site is still" agree
+ * again by construction rather than by enumeration of what can pre-empt the row.
  */
 import React from 'react';
 import type { Theme } from './theme.js';
@@ -43,6 +60,21 @@ export interface BottomStatusRowProps {
     toasts: Toast[];
     /** `<ActivityLine>` while a run owns the screen, else `null`. */
     activity: React.ReactNode;
+    /**
+     * The bare animated spinner (`liveSpinner`), or `null` when it would be a
+     * STATIC glyph — an ASCII terminal, or `reducedMotion`.
+     *
+     * IT IS NOT A SECOND MOUNT CONDITION. `activity` alone decides whether a life
+     * signal belongs on this row; this prop only says which FORM the signal takes,
+     * and it is read only when `activity` is non-null. So a caller cannot make the
+     * two disagree, which is the failure mode that produced this prop.
+     *
+     * `null` means PREFIX NOTHING, not "prefix the still glyph". A static `·` in
+     * front of every toast would be a visible change to ASCII terminals and to
+     * users who asked for stillness — neither of whom ever had the dead-frame bug,
+     * and both of whom must come out byte-identical.
+     */
+    activityGlyph?: React.ReactElement | null;
     /**
      * `<UpdateLine>` when the updater has something to say, else `null` — AND THE
      * CALLER DECIDES WHICH (C-15 / cli-auto-update P0-1).
@@ -62,4 +94,4 @@ export interface BottomStatusRowProps {
     update?: React.ReactNode;
     theme: Theme;
 }
-export declare function BottomStatusRow({ mode, toasts, activity, update, theme, }: BottomStatusRowProps): React.ReactElement | null;
+export declare function BottomStatusRow({ mode, toasts, activity, activityGlyph, update, theme, }: BottomStatusRowProps): React.ReactElement | null;

package/dist/ui/BottomStatusRow.js

@@ -1,10 +1,24 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { Box } from 'ink';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
 import { ToastStack } from './ToastStack.js';
-export function BottomStatusRow({ mode, toasts, activity, update, theme, }) {
-    // A toast wins the row outright.
-    if (toasts.length > 0)
-        return _jsx(ToastStack, { toasts: toasts, theme: theme, mode: mode });
+export function BottomStatusRow({ mode, toasts, activity, activityGlyph, update, theme, }) {
+    // A toast wins the row outright — but a run in flight keeps its spinner on it.
+    if (toasts.length > 0) {
+        const spinner = activity ? activityGlyph : null;
+        // Byte-identical to the old branch whenever there is no live spinner to
+        // carry: no run, an ASCII terminal, or `reducedMotion`.
+        if (!spinner)
+            return _jsx(ToastStack, { toasts: toasts, theme: theme, mode: mode });
+        const fullscreen = mode === 'fullscreen';
+        return (
+        // `flexDirection` SPELLED OUT even though `row` is Yoga's default: it is
+        // what keeps two children on ONE row, and the header above turns on that
+        // being true. Left implicit, it reads as an oversight next to the child
+        // below that declares `column` — and "make them match" is a one-word edit
+        // that doubles the row, takes it from the transcript, and desynchronises
+        // every `viewportRows()` consumer without failing a type or a lint.
+        _jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsx(Box, { flexShrink: 0, marginTop: fullscreen ? 0 : 1, children: _jsxs(Text, { color: theme.thinking, children: [fullscreen ? ' ' : '', spinner, fullscreen ? '' : ' '] }) }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(ToastStack, { toasts: toasts, theme: theme, mode: mode }) })] }));
+    }
     // Inline has no frame and therefore nothing to protect: `ToastStack`'s inline
     // branch is already a conditional 0-3 row stack, and these are simply one more
     // conditional row above it.

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/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/overlays/HelpOverlay.js

@@ -33,7 +33,7 @@ const COMMANDS = [
         'Todo planning: status, switches, the rail, follow-through',
     ],
     ['/tools', 'List active tools'],
-    ['/clear', 'Clear the visible transcript'],
+    ['/clear', 'Clear the visible transcript and the todo panel'],
     ['/reset', 'New conversation'],
     ['/cwd [dir]', 'Show or change the tool working directory'],
     ['/save [file]', 'Save the session to JSON'],

package/dist/ui/use-startup-notices.d.ts

@@ -12,6 +12,43 @@
  * not otherwise see — rather than belonging to the view.
  */
 import type { ViewAction } from '../agent/reducer.js';
+/**
+ * The `shift-tab-and-mouse-wheel-dead-on-some-terminals` notice (F1'). Shown at
+ * most once, ever, and only on a Windows console that cannot deliver either
+ * input — see `ui/win-vt-input.ts` for why that is a property of the Node
+ * version rather than of the terminal.
+ *
+ * IT NAMES WHAT THE KEY DOES NOW, not merely that it is unavailable, and that
+ * is the load-bearing half of the text. `Shift+Tab` on these machines is not
+ * inert: the modifier is lost inside libuv, so Ink sees an ordinary `Tab` and
+ * the `/` palette or an `@` popup completes its selection over the user's
+ * draft. A user told only "this key does not work" keeps pressing it and keeps
+ * losing text without ever connecting the two.
+ *
+ * `Shift+Up` / `Shift+Down` is the scroll workaround named here because it is
+ * the only one PROVEN to survive: both Node versions emit `\x1b[1;2A` for it,
+ * byte for byte, in the probe data. `PgUp` / `PgDn` is expected to work too but
+ * was never injected, so it is left out rather than promised.
+ *
+ * THE WHEEL HALF IS FULL-SCREEN ONLY, and dropping it inline is not a detail.
+ * `Shift+Tab` is broken in both modes — the modifier dies inside libuv, well
+ * below anything this app chooses — but the wheel is only ours to lose in
+ * full-screen: inline never asks the console to report it (`mode` is a conjunct
+ * of `cli.tsx::wantMouse`), so the wheel goes on scrolling the terminal's own
+ * scrollback exactly as it always has. And `Shift+Up` / `Shift+Down` are handled
+ * inside `App`'s `if (fullscreen)` branch, so recommending them inline names a
+ * key that does nothing. Telling an inline user their working wheel is dead and
+ * then handing them an inert workaround is the same failure this notice exists
+ * to end — advice about a mode that is not running — merely pointed the other
+ * way.
+ *
+ * EXPORTED FOR ITS TEST, unlike the two notices above it. Asserting this text
+ * through a rendered frame does not work: the transcript wraps a notice at two
+ * columns wider than it displays it, so any phrase landing on a wrap boundary
+ * loses a character or two on the way to `lastFrame()` and the assertion fails
+ * for a reason that has nothing to do with the text.
+ */
+export declare function vtInputDeadNotice(nodeVersion: string, fullscreen: boolean): string;
 /**
  * `{ requested, resolved }` when the raise happened, `undefined` otherwise —
  * i.e. `cfg.transcriptRetainRequested` and `cfg.transcriptRetain`.
@@ -22,12 +59,38 @@ export interface RetainNoticeOptions {
 }
 export interface MouseNoticeOptions {
     /**
-     * Whether reporting is ACTUALLY in effect — i.e. a filter was installed, not
-     * merely that the config asked for one. A user on a terminal where R-1 fires
-     * must never be given advice about a mode that is not running.
+     * Whether reporting is ACTUALLY in effect: a filter was installed AND the
+     * platform can deliver the reports it would filter. A user on a terminal
+     * where R-1 fires must never be given advice about a mode that is not
+     * running.
+     *
+     * THE TWO HALVES ARE NOT THE SAME CLAIM, and this comment used to define the
+     * flag as only the first of them ("i.e. a filter was installed") — which is
+     * how the second sentence came to be violated by an implementation that
+     * satisfied the first. Constructing the filter proves nothing about whether
+     * the terminal will ever send a report; on a Windows console without VT
+     * input it succeeds and then sits in front of a stream no report can reach.
+     * The caller now derives both from one expression (`cli.tsx::wantMouse`), so
+     * re-deriving either one here would put them back out of step.
      */
     enabled: boolean;
     /** Record that it was shown (`state.json`). Called once, after dispatch. */
     onSeen: () => void;
 }
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions): void;
+export interface VtInputNoticeOptions {
+    /** `process.versions.node`, quoted back so the user can act on it. */
+    nodeVersion: string;
+    /**
+     * Whether this run owns the alternate screen, i.e. `App`'s own `fullscreen`.
+     *
+     * Selects which half of the text applies: inline keeps the wheel and loses the
+     * full-screen scroll keys, so it is told about `Shift+Tab` and nothing else
+     * (see `vtInputDeadNotice`). Taken from the caller rather than re-derived here
+     * for the same reason the version is — one source, no chance of the notice and
+     * the renderer disagreeing about which mode is running.
+     */
+    fullscreen: boolean;
+    /** Record that it was shown (`state.json`). Called once, after dispatch. */
+    onSeen: () => void;
+}
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions, vtInputNotice?: VtInputNoticeOptions): void;

package/dist/ui/use-startup-notices.js

@@ -13,7 +13,7 @@
  */
 import { useEffect, useRef } from 'react';
 import { readConfigFile } from '../config/store.js';
-import { getMouseNoticeSeen } from '../config/ui-state.js';
+import { getMouseNoticeSeen, getVtInputNoticeSeen } from '../config/ui-state.js';
 import { getLogger } from '../logging/logger.js';
 /**
  * The §6.1 notice (mouse-wheel-region-routing). Shown at most once, ever.
@@ -39,7 +39,55 @@ function retainRaisedNotice(requested, resolved) {
         'so the whole scroll horizon stays reachable. Lower transcriptWindow too if you meant ' +
         'to cap memory.');
 }
-export function useStartupNotices(dispatch, mouseNotice, retainNotice) {
+/**
+ * The `shift-tab-and-mouse-wheel-dead-on-some-terminals` notice (F1'). Shown at
+ * most once, ever, and only on a Windows console that cannot deliver either
+ * input — see `ui/win-vt-input.ts` for why that is a property of the Node
+ * version rather than of the terminal.
+ *
+ * IT NAMES WHAT THE KEY DOES NOW, not merely that it is unavailable, and that
+ * is the load-bearing half of the text. `Shift+Tab` on these machines is not
+ * inert: the modifier is lost inside libuv, so Ink sees an ordinary `Tab` and
+ * the `/` palette or an `@` popup completes its selection over the user's
+ * draft. A user told only "this key does not work" keeps pressing it and keeps
+ * losing text without ever connecting the two.
+ *
+ * `Shift+Up` / `Shift+Down` is the scroll workaround named here because it is
+ * the only one PROVEN to survive: both Node versions emit `\x1b[1;2A` for it,
+ * byte for byte, in the probe data. `PgUp` / `PgDn` is expected to work too but
+ * was never injected, so it is left out rather than promised.
+ *
+ * THE WHEEL HALF IS FULL-SCREEN ONLY, and dropping it inline is not a detail.
+ * `Shift+Tab` is broken in both modes — the modifier dies inside libuv, well
+ * below anything this app chooses — but the wheel is only ours to lose in
+ * full-screen: inline never asks the console to report it (`mode` is a conjunct
+ * of `cli.tsx::wantMouse`), so the wheel goes on scrolling the terminal's own
+ * scrollback exactly as it always has. And `Shift+Up` / `Shift+Down` are handled
+ * inside `App`'s `if (fullscreen)` branch, so recommending them inline names a
+ * key that does nothing. Telling an inline user their working wheel is dead and
+ * then handing them an inert workaround is the same failure this notice exists
+ * to end — advice about a mode that is not running — merely pointed the other
+ * way.
+ *
+ * EXPORTED FOR ITS TEST, unlike the two notices above it. Asserting this text
+ * through a rendered frame does not work: the transcript wraps a notice at two
+ * columns wider than it displays it, so any phrase landing on a wrap boundary
+ * loses a character or two on the way to `lastFrame()` and the assertion fails
+ * for a reason that has nothing to do with the text.
+ */
+export function vtInputDeadNotice(nodeVersion, fullscreen) {
+    const cause = `Node ${nodeVersion} on Windows does not turn on the console's VT input mode, so `;
+    const cost = 'it will not switch mode, and with the / palette or an @ popup open it completes that ' +
+        'instead, overwriting your draft. ';
+    if (!fullscreen) {
+        return (`${cause}Shift+Tab never arrives: it comes through as a PLAIN TAB - ${cost}` +
+            'Use /plan to switch mode instead. Node 22.17.0+ (or 24.2.0+) restores it.');
+    }
+    return (`${cause}two keys never arrive: the wheel sends nothing at all, and Shift+Tab arrives ` +
+        `as a PLAIN TAB - ${cost}Use /plan to switch mode and Shift+Up / Shift+Down to scroll. ` +
+        'Node 22.17.0+ (or 24.2.0+) restores both.');
+}
+export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNotice) {
     // The sink gives up after repeated write failures (a read-only log directory,
     // a full disk). Silently logging nothing is exactly the state a user must not
     // discover later, from an empty file, while trying to explain a bug.
@@ -76,6 +124,32 @@ export function useStartupNotices(dispatch, mouseNotice, retainNotice) {
         dispatch({ type: 'notice', level: 'info', text: MOUSE_SELECTION_NOTICE });
         noticeRef.current?.onSeen();
     }, [mouseEnabled, dispatch]);
+    // The R-1 notice. `warn`, not `info`: unlike the one above it reports a
+    // capability the user was promised and does not have, plus a key that is
+    // actively editing their draft.
+    //
+    // DEPENDS ON THE SCALAR, never on the options object, for the reason spelled
+    // out on the retain effect below — `App` builds that literal during render.
+    // Its one-shot key is checked only AFTER the presence test, so a machine that
+    // is not affected never touches `state.json` at all.
+    const vtNoticeRef = useRef(vtInputNotice);
+    vtNoticeRef.current = vtInputNotice;
+    const vtNodeVersion = vtInputNotice?.nodeVersion;
+    const vtFullscreen = vtInputNotice?.fullscreen ?? false;
+    const vtNoticeShown = useRef(false);
+    useEffect(() => {
+        if (vtNodeVersion === undefined || vtNoticeShown.current)
+            return;
+        if (getVtInputNoticeSeen())
+            return;
+        vtNoticeShown.current = true;
+        dispatch({
+            type: 'notice',
+            level: 'warn',
+            text: vtInputDeadNotice(vtNodeVersion, vtFullscreen),
+        });
+        vtNoticeRef.current?.onSeen();
+    }, [vtNodeVersion, vtFullscreen, dispatch]);
     // A `warn` notice rather than a toast: it is about a value the user typed, so
     // it belongs in the transcript where it can be scrolled back to, not in a row
     // that expires. DEPENDS ON THE TWO SCALARS, never on the options object —

package/dist/ui/win-vt-input.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Will this console ever deliver `CSI Z` and SGR mouse reports?
+ * (shift-tab-and-mouse-wheel-dead-on-some-terminals, F1')
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope.
+ *
+ * On Windows the answer is decided by NODE, not by the terminal emulator and not
+ * by anything this package writes. `Shift+Tab` and SGR mouse reporting both
+ * exist only while the console input handle has `ENABLE_VIRTUAL_TERMINAL_INPUT`
+ * set, and Node only sets it from v22.17.0 / v24.2.0 onward, where
+ * `SetRawMode` switched from `UV_TTY_MODE_RAW` to `UV_TTY_MODE_RAW_VT`
+ * (`nodejs/node` `src/tty_wrap.cc`). Before that libuv translates console input
+ * records into ANSI itself, and that translation
+ *
+ *   - has no `VK_TAB` entry, and takes the character branch for it because
+ *     `uChar.UnicodeChar` is 0x09, where SHIFT_PRESSED is never read. So
+ *     `Shift+Tab` arrives as a PLAIN TAB, byte-identical to `Tab`;
+ *   - `continue`s past every record that is not a `KEY_EVENT`, so a mouse
+ *     report cannot reach the process at all.
+ *
+ * Measured rather than reasoned: injecting the same keystrokes into the same
+ * console, Node 20.19.0 yields `09` for `Shift+Tab` and Node 22.18.0 yields
+ * `1b 5b 5a`; console mode samples `0x0008` and `0x0208` respectively. The full
+ * probe data is in `docs/diagnoses/shift-tab-and-mouse-wheel-dead-on-some-terminals/`.
+ *
+ * PURE: the platform and the version are arguments, so the whole table is
+ * testable without a Windows box and without a second Node install.
+ */
+/**
+ * The versions whose `setRawMode(true)` reaches `UV_TTY_MODE_RAW_VT`.
+ *
+ * `<23` IS LOAD-BEARING: 23.x branched before the change landed and never got
+ * it, and 24.0/24.1 did not have it either - the fix reached the 24 line only in
+ * 24.2.0. A range of `>=22.17.0` alone would call both of those supported.
+ *
+ * A TYPO HERE DISABLES THE WHOLE GATE SILENTLY, because `satisfiesNodeRange`
+ * fails open: a clause it cannot parse makes the range unknown and the answer
+ * `true`. `win-vt-input.test.ts` pins concrete version strings against concrete
+ * booleans for exactly that reason - it is the only guard this constant has.
+ */
+export declare const WINDOWS_VT_INPUT_NODE_RANGE = ">=22.17.0 <23 || >=24.2.0";
+/**
+ * `false` only for the combination that is known to swallow both inputs:
+ * `win32` running a Node outside `WINDOWS_VT_INPUT_NODE_RANGE`.
+ *
+ * FAILS OPEN, deliberately, in both directions (inherited from
+ * `satisfiesNodeRange`, whose own reasoning is written down at its definition):
+ * a version string that cannot be parsed is assumed supported. Guessing wrong
+ * that way costs nothing beyond today's behaviour; guessing wrong the other way
+ * would turn the mouse off on a machine where it works, which is a regression
+ * this bug does not justify risking.
+ *
+ * Every non-Windows platform is `true` unconditionally. macOS and Linux go
+ * through a real pty, where the terminal - not Node - encodes the keys, so no
+ * version of Node has ever been able to affect this.
+ */
+export declare function supportsWindowsVtInput(platform: string, nodeVersion: string): boolean;