@aragon-agent/cli 0.5.12 → 0.6.1

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(() => {
@@ -1434,6 +1450,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
@@ -1483,6 +1510,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/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;

package/dist/ui/win-vt-input.js

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+import { satisfiesNodeRange } from '../update/semver.js';
+/**
+ * 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 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 function supportsWindowsVtInput(platform, nodeVersion) {
+    if (platform !== 'win32')
+        return true;
+    return satisfiesNodeRange(WINDOWS_VT_INPUT_NODE_RANGE, nodeVersion);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.12",
+  "version": "0.6.1",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -15,7 +15,11 @@
     "anthropic",
     "openai",
     "google",
-    "aragonagent"
+    "aragonagent",
+    "exec",
+    "headless",
+    "automation",
+    "ci"
   ],
   "repository": {
     "type": "git",
@@ -52,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.12",
+    "@aragon-agent/core": "^0.2.13",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",