@aragon-agent/cli 0.5.12 → 0.6.2

package/dist/ui/App.js

@@ -14,11 +14,11 @@ 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, setVtInputNoticeVersion, } from '../config/ui-state.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret } from '../logging/secret-registry.js';
 import { detectCapabilities } from './capabilities.js';
-import { useStartupNotices } from './use-startup-notices.js';
+import { useStartupNotices, VT_INPUT_NOTICE_VERSION } from './use-startup-notices.js';
 import { getTheme } from './theme.js';
 import { pickGlyphs } from './glyphs.js';
 import { Header } from './Header.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
@@ -67,7 +67,7 @@ import { PlanReviewOverlay } from './overlays/PlanReviewOverlay.js';
 import { CommandRegistry, runSlashInput } from '../commands/registry.js';
 import { registerBuiltinCommands } from '../commands/builtins.js';
 import { makeSkillsCommand, registerSkillCommands } from '../commands/skills.js';
-import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+import { MODE_LABEL, MODE_TOGGLE_KEYS, nextMode } from '../agent/agent-mode.js';
 /**
  * Decide what the `Max tokens` field means, WITHOUT letting a bad value in it
  * discard the rest of the form.
@@ -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,23 @@ 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. That
+    // key is now a VERSION for the same reason, one turn later — the audience
+    // for the text that finally names the fallback key is, again, exactly the
+    // set of users who already have the old flag on disk.
+    //
+    // `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: () => setVtInputNoticeVersion(VT_INPUT_NOTICE_VERSION),
+        }
         : undefined);
     // --- Exit snapshot: the only way state reaches cli.tsx (§4.4). ----------
     useEffect(() => {
@@ -1180,7 +1199,13 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         // AFTER the overlay block, and with an EXPLICIT guard rather than relying on
         // ordering: that block only `return`s for the keys it recognizes, and
         // everything else falls through (AC-P2).
-        if (key.tab && key.shift) {
+        //
+        // TWO KEYS, ONE BRANCH (shift-tab-mode-toggle-still-dead-on-windows, C2).
+        // `Ctrl+P` is not a Windows-only alias bolted on beside the real binding: it
+        // is the rung that survives when `Shift+Tab` cannot be delivered at all, and
+        // it shares this branch precisely so the two can never drift into different
+        // behaviour. See `MODE_TOGGLE_KEYS` for why this key and not another.
+        if ((key.tab && key.shift) || (key.ctrl && (input === 'p' || input === 'P'))) {
             if (stateRef.current.overlay)
                 return;
             applyMode(nextMode(controller.getAgentMode()));
@@ -1434,6 +1459,17 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // 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
@@ -1469,7 +1505,17 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // 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' }) }) }));
+    // WHICH KEY THE HINT ROW NAMES (shift-tab-mode-toggle-still-dead-on-windows,
+    // C3-1). Derived from `vtInputWarning` rather than from a probe of its own,
+    // because that prop is already the single answer to "can this console deliver
+    // `CSI Z`?" — `cli.tsx` computes it AFTER trying to force the bit on, so a
+    // machine we just repaired is told to press `shift+tab` and a machine we could
+    // not repair is told to press the key that provably survives.
+    //
+    // Both keys always WORK (they share one branch in the input handler); this
+    // only decides which one the user is taught.
+    const modeToggleKey = vtInputWarning ? MODE_TOGGLE_KEYS.fallback : MODE_TOGGLE_KEYS.primary;
+    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, modeToggleKey: modeToggleKey, 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: 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,
@@ -1483,6 +1529,14 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             // 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/Composer.d.ts

@@ -34,10 +34,23 @@ export interface ComposerProps {
     hintsEnabled: boolean;
     /** Mirror of the controller's effective mode; drives the chip and the border. */
     agentMode: AgentMode;
+    /**
+     * Which key this hint should NAME for the mode toggle
+     * (shift-tab-mode-toggle-still-dead-on-windows, C3-1).
+     *
+     * A PROP RATHER THAN A CONSTANT because on some consoles the constant is a
+     * lie. This row used to render `shift+tab` unconditionally, with no link to
+     * the capability check three files away, so the machines where that key is
+     * swallowed were the ones being told to press it - permanently, on every
+     * frame, while the one warning they got scrolled out of the transcript
+     * minutes earlier (analysis section 3.7). Defaults to the primary key, which
+     * is what every unaffected machine renders.
+     */
+    modeToggleKey?: string;
     popupMaxRows?: number;
     theme: Theme;
     caps: TermCapabilities;
     onSubmit: (text: string) => void;
     onHelp?: () => void;
 }
-export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;
+export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, modeToggleKey, popupMaxRows, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;

package/dist/ui/Composer.js

@@ -21,7 +21,7 @@ import { pickGlyphs } from './glyphs.js';
 import { HINT_FADE_AFTER } from '../config/schema.js';
 import { PromptInput } from './PromptInput.js';
 import { ModeChip } from './ModeChip.js';
-import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+import { MODE_LABEL, MODE_TOGGLE_KEYS, nextMode } from '../agent/agent-mode.js';
 /**
  * Build the hint row.
  *
@@ -32,7 +32,7 @@ import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
  * Progressive disclosure is for teaching discoverable things, not for retiring
  * an emergency exit (§4.6 / A-14 / M-10b).
  */
-function hintText(running, submitCount, glyphs, mode) {
+function hintText(running, submitCount, glyphs, mode, toggleKey) {
     const dot = ` ${glyphs.midDot} `;
     if (running) {
         return [`${glyphs.enterKey} steer`, 'esc abort', `ctrl+c${glyphs.times}2 exit`].join(dot);
@@ -40,7 +40,7 @@ function hintText(running, submitCount, glyphs, mode) {
     // The hint names the DESTINATION, not the current state — the correct label
     // for a toggle affordance, and the reason the mode word here is the OPPOSITE
     // of the one on the chip beside it.
-    const toggle = `shift+tab ${MODE_LABEL[nextMode(mode)].toLowerCase()}`;
+    const toggle = `${toggleKey} ${MODE_LABEL[nextMode(mode)].toLowerCase()}`;
     // The faded form KEEPS the mode toggle. Progressive disclosure exists to
     // retire things the user has demonstrably learned, and `submitCount` counts
     // submissions — a user can send fifty messages without ever discovering
@@ -56,7 +56,7 @@ function hintText(running, submitCount, glyphs, mode) {
         '? help',
     ].join(dot);
 }
-export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, theme, caps, onSubmit, onHelp, }) {
+export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, modeToggleKey = MODE_TOGGLE_KEYS.primary, popupMaxRows, theme, caps, onSubmit, onHelp, }) {
     const [hasDraft, setHasDraft] = useState(false);
     const onDraftChange = useCallback((next) => setHasDraft(next), []);
     // Plan mode inserts ONE branch, above `draft` and below `running`. The
@@ -76,5 +76,5 @@ export function Composer({ isActive, running, history, commands, cwd, showHint,
     return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsx(PromptInput, { isActive: isActive, running: running, history: history, commands: commands, cwd: cwd, theme: theme, caps: caps, popupMaxRows: popupMaxRows, onSubmit: onSubmit, onHelp: onHelp, agentMode: agentMode, bordered: { color: borderColor }, onDraftChange: onDraftChange }), visible && (
             // The chip rides the EXISTING hint row rather than adding one, so it
             // costs zero rows on a 24-row terminal.
-            _jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsx(Text, { children: '  ' }), _jsx(ModeChip, { mode: agentMode, theme: theme, caps: caps }), _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: hintText(running, submitCount, glyphs, agentMode) })] }))] }));
+            _jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsx(Text, { children: '  ' }), _jsx(ModeChip, { mode: agentMode, theme: theme, caps: caps }), _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: hintText(running, submitCount, glyphs, agentMode, modeToggleKey) })] }))] }));
 }

package/dist/ui/overlays/HelpOverlay.js

@@ -7,7 +7,13 @@ function keyRows(times) {
         ['Enter', 'Submit (idle) / queue steering (running); re-pins to the newest output'],
         ['Alt+Enter / Shift+Enter', 'Insert newline'],
         ['Esc', 'Abort run / close overlay'],
-        ['Shift+Tab', 'Toggle plan mode (same as /plan)'],
+        // BOTH KEYS ARE LISTED HERE, and this row is why (shift-tab-mode-toggle-
+        // still-dead-on-windows, review R-7). The hint row above the composer is the
+        // other place the fallback is named, and it has two off-switches - a short
+        // terminal (`showHint`) and `hints: false`. A key that only exists behind
+        // either of them is a key the affected user never learns about, which is the
+        // one-shot notice's failure repeated with a different switch.
+        ['Shift+Tab / Ctrl+P', 'Toggle plan mode (same as /plan)'],
         [`Ctrl+C ${times}2`, 'Exit'],
         ['Ctrl+L', 'Redraw the frame'],
         ['Ctrl+T', 'Show/hide thinking (off by default)'],
@@ -54,6 +60,11 @@ const SKILL_ROWS = [
 ];
 const PLAN_ROWS = [
     ['Shift+Tab / /plan', 'Switch between BUILD (do it now) and PLAN (research first)'],
+    // A ROW OF ITS OWN, not a third name on the line above: the reader who needs
+    // this one is the reader whose `Shift+Tab` does nothing, and what they need is
+    // the reason, not another synonym. Listing the key in both places instead just
+    // says it twice and explains it nowhere.
+    ['Ctrl+P', 'The same toggle, for Windows consoles that deliver Shift+Tab as a plain Tab'],
     ['In PLAN mode', 'write_file, edit_file, bash, skill_install and skill_create are refused'],
     ['bash', 'Refused in full, including git status - use read_file / glob / grep'],
     ['ask_user', 'The agent asks 1-5 multiple-choice questions; Enter takes the recommendation'],

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

@@ -12,6 +12,69 @@
  * not otherwise see — rather than belonging to the view.
  */
 import type { ViewAction } from '../agent/reducer.js';
+/**
+ * The revision of the text below that a user must have seen for this notice to
+ * stay quiet (`state.json::vtInputNoticeVersion`, `0` when absent).
+ *
+ * BUMP IT WHENEVER THE ADVICE CHANGES, and never for a rewording that leaves
+ * the recommended actions alone. The two failure modes sit on either side of
+ * this constant: leaving it alone after changing what the user is told to press
+ * makes the change inert for everyone who already ran the old build — which is
+ * the entire affected population, since the notice only appears on machines
+ * where the key has been broken all along — while dropping the gate altogether
+ * turns a one-shot into a banner on every launch.
+ *
+ * `1` = the first text naming `MODE_TOGGLE_KEYS.fallback`. `0` = the 0.6.1 text
+ * that offered only `/plan`, recorded back when this was a boolean.
+ */
+export declare const VT_INPUT_NOTICE_VERSION = 1;
+/**
+ * The `shift-tab-and-mouse-wheel-dead-on-some-terminals` notice (F1'). Shown at
+ * most once per `VT_INPUT_NOTICE_VERSION`, 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.
+ *
+ * THE FALLBACK KEY COMES BEFORE `/plan` IN BOTH BRANCHES, and it is named from
+ * `MODE_TOGGLE_KEYS` rather than spelled out, so the four consumers of that
+ * constant cannot drift apart. This notice is the last one of them to be wired
+ * up, and it is also the only channel that reaches the affected user without
+ * being asked to: the composer hint does not exist at all in inline mode and is
+ * switched off by a short terminal or `hints: false` in full-screen, and
+ * `/help` has to be typed by someone whose current belief is "the key does
+ * nothing" rather than "I should read the help". Ordering follows cost — one
+ * keystroke before four and a return.
+ *
+ * `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 +85,43 @@ 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 `VT_INPUT_NOTICE_VERSION` was shown (`state.json`). Called once,
+     * after dispatch — and it must write that constant, not `true`: the gate
+     * below compares against it, so a caller storing anything else either replays
+     * the notice forever or silences a future revision of the text.
+     */
+    onSeen: () => void;
+}
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions, vtInputNotice?: VtInputNoticeOptions): void;

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

@@ -12,8 +12,9 @@
  * not otherwise see — rather than belonging to the view.
  */
 import { useEffect, useRef } from 'react';
+import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
 import { readConfigFile } from '../config/store.js';
-import { getMouseNoticeSeen } from '../config/ui-state.js';
+import { getMouseNoticeSeen, getVtInputNoticeVersion } 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 +40,82 @@ 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 revision of the text below that a user must have seen for this notice to
+ * stay quiet (`state.json::vtInputNoticeVersion`, `0` when absent).
+ *
+ * BUMP IT WHENEVER THE ADVICE CHANGES, and never for a rewording that leaves
+ * the recommended actions alone. The two failure modes sit on either side of
+ * this constant: leaving it alone after changing what the user is told to press
+ * makes the change inert for everyone who already ran the old build — which is
+ * the entire affected population, since the notice only appears on machines
+ * where the key has been broken all along — while dropping the gate altogether
+ * turns a one-shot into a banner on every launch.
+ *
+ * `1` = the first text naming `MODE_TOGGLE_KEYS.fallback`. `0` = the 0.6.1 text
+ * that offered only `/plan`, recorded back when this was a boolean.
+ */
+export const VT_INPUT_NOTICE_VERSION = 1;
+/**
+ * The `shift-tab-and-mouse-wheel-dead-on-some-terminals` notice (F1'). Shown at
+ * most once per `VT_INPUT_NOTICE_VERSION`, 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.
+ *
+ * THE FALLBACK KEY COMES BEFORE `/plan` IN BOTH BRANCHES, and it is named from
+ * `MODE_TOGGLE_KEYS` rather than spelled out, so the four consumers of that
+ * constant cannot drift apart. This notice is the last one of them to be wired
+ * up, and it is also the only channel that reaches the affected user without
+ * being asked to: the composer hint does not exist at all in inline mode and is
+ * switched off by a short terminal or `hints: false` in full-screen, and
+ * `/help` has to be typed by someone whose current belief is "the key does
+ * nothing" rather than "I should read the help". Ordering follows cost — one
+ * keystroke before four and a return.
+ *
+ * `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. ';
+    const toggle = `Press ${MODE_TOGGLE_KEYS.fallback} to switch mode instead (or /plan)`;
+    if (!fullscreen) {
+        return (`${cause}Shift+Tab never arrives: it comes through as a PLAIN TAB - ${cost}` +
+            `${toggle}. 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}${toggle}, 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 +152,36 @@ 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.
+    //
+    // `>=`, not `!==`: a state file written by a NEWER build (a downgrade, or a
+    // shared home directory) has already told this user everything the text below
+    // says, so re-showing it would be noise rather than news.
+    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 (getVtInputNoticeVersion() >= VT_INPUT_NOTICE_VERSION)
+            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 —