@aragon-agent/cli 0.6.1 → 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, setVtInputNoticeSeen } 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';
@@ -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.
@@ -707,7 +707,10 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         ? { 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.
+    // 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
@@ -717,7 +720,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         ? {
             nodeVersion: vtInputWarning.nodeVersion,
             fullscreen,
-            onSeen: () => setVtInputNoticeSeen(true),
+            onSeen: () => setVtInputNoticeVersion(VT_INPUT_NOTICE_VERSION),
         }
         : undefined);
     // --- Exit snapshot: the only way state reaches cli.tsx (§4.4). ----------
@@ -1196,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()));
@@ -1496,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,

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,11 +12,27 @@
  * 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, 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.
+ * 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
@@ -25,6 +41,16 @@ import type { ViewAction } from '../agent/reducer.js';
  * 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
@@ -90,7 +116,12 @@ export interface VtInputNoticeOptions {
      * the renderer disagreeing about which mode is running.
      */
     fullscreen: boolean;
-    /** Record that it was shown (`state.json`). Called once, after dispatch. */
+    /**
+     * 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, getVtInputNoticeSeen } 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,11 +40,27 @@ function retainRaisedNotice(requested, resolved) {
         'so the whole scroll horizon stays reachable. Lower transcriptWindow too if you meant ' +
         'to cap memory.');
 }
+/**
+ * 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, 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.
+ * 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
@@ -52,6 +69,16 @@ function retainRaisedNotice(requested, resolved) {
  * 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
@@ -79,12 +106,13 @@ 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}` +
-            'Use /plan to switch mode instead. Node 22.17.0+ (or 24.2.0+) restores it.');
+            `${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}Use /plan to switch mode and Shift+Up / Shift+Down to scroll. ` +
+        `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) {
@@ -132,6 +160,10 @@ export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNo
     // 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;
@@ -140,7 +172,7 @@ export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNo
     useEffect(() => {
         if (vtNodeVersion === undefined || vtNoticeShown.current)
             return;
-        if (getVtInputNoticeSeen())
+        if (getVtInputNoticeVersion() >= VT_INPUT_NOTICE_VERSION)
             return;
         vtNoticeShown.current = true;
         dispatch({

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

@@ -0,0 +1,136 @@
+/**
+ * Turn `ENABLE_VIRTUAL_TERMINAL_INPUT` on for THIS console, from outside Node
+ * (shift-tab-mode-toggle-still-dead-on-windows, C1-M1).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope.
+ *
+ * `win-vt-input.ts` answers "will this console ever deliver `CSI Z`?". This
+ * module answers "can we MAKE it deliver one?", and the measured answer is yes.
+ * The bit is a property of the console input buffer, not of Node, so any process
+ * attached to the same console can set it - and libuv's pre-22.17 translator
+ * forwards whatever characters the console generates, `ESC` `[` `Z` included.
+ * On Node 20.19.0, in one run, one injected `Shift+Tab` went from `09` to
+ * `1b 5b 5a` the instant an outside process OR-ed `0x0200` in (analysis section
+ * 3.2; raw probe data under `docs/diagnoses/.../repro/`).
+ *
+ * Node ships no FFI, so the outside process is `powershell.exe` calling
+ * `SetConsoleMode` through P/Invoke. Measured cost end to end: 722 ms, roughly
+ * 280 ms of process start plus 300 ms of `Add-Type` compiling C# at run time
+ * (analysis section 3.4). That is the whole price of not adding a native
+ * dependency, and it is paid ONCE, only on an affected Windows console.
+ *
+ * THREE TRAPS ARE ENCODED HERE, all of them measured rather than imagined:
+ *
+ *  1. `windowsHide: true` maps to `CREATE_NO_WINDOW`, which hands the child its
+ *     OWN console. The helper then reads, sets and reports success against a
+ *     console nobody is typing into: exit code 0, `SetConsoleMode` true, log
+ *     clean, and no effect whatsoever - indistinguishable from "the fix was
+ *     never written" (analysis section 3.5). Hence `windowsHide: false`.
+ *  2. The helper must open `CONIN$` with `CreateFileW`, never
+ *     `GetStdHandle(STD_INPUT_HANDLE)`: it is spawned with stdin `ignore`, so
+ *     its standard input is `NUL`. Sharing the real stdin instead is not an
+ *     option - that handle is being reconfigured underneath it.
+ *  3. The `before` mode is the ONLY signal that distinguishes trap 1 from
+ *     success, so the helper reports it and `decideVtForceOutcome` checks it.
+ *     The check is a POSITIVE bitmask ("is this console already in raw mode"),
+ *     not `before !== 0x01F7`: that number is one machine's default and varies
+ *     with QuickEdit, with the host, and with a user who already turned VT input
+ *     on. A magic-number comparison passes silently on the first machine whose
+ *     default happens to differ, which puts trap 1 straight back (review R-3).
+ *
+ * WHAT UNDOES IT: `setRawMode(false)`. libuv rewrites the whole console mode on
+ * every raw-mode transition and its pre-22.17 path does not know about this bit,
+ * so one transition clears it (analysis section 3.3). That is why the caller
+ * must raise raw mode BEFORE calling this, and it is also the entire restore
+ * path - the bit outlives the process otherwise, and neither Windows nor the
+ * console clears it (analysis section 3.5b).
+ *
+ * FAILURE IS ALWAYS GRACEFUL. Constrained Language Mode disables `Add-Type`
+ * outright, and enterprise fleets ship it by policy - exactly the "another PC"
+ * population this bug is about. Every failure returns `ok: false` with a reason
+ * for the log and nothing else happens; the alternate mode-toggle key
+ * (`MODE_TOGGLE_KEYS.fallback`) is the rung below that needs none of this.
+ */
+/** Console input mode bits (`consoleapi.h`). */
+export declare const ENABLE_PROCESSED_INPUT = 1;
+export declare const ENABLE_LINE_INPUT = 2;
+export declare const ENABLE_ECHO_INPUT = 4;
+export declare const ENABLE_WINDOW_INPUT = 8;
+export declare const ENABLE_VIRTUAL_TERMINAL_INPUT = 512;
+/**
+ * The three bits a cooked console has and a raw one does not.
+ *
+ * This is the fingerprint of "libuv has already put this console in raw mode",
+ * and it is what tells the two measured samples apart: `0x0008` (the CLI's own
+ * console, raw) versus `0x01F7` (a fresh `CREATE_NO_WINDOW` console, cooked).
+ */
+export declare const COOKED_INPUT_BITS: number;
+export declare function isRawConsoleMode(mode: number): boolean;
+export type VtForceFailure = 'not_windows' | 'spawn_failed' | 'helper_failed' | 'no_before' | 'wrong_console' | 'bit_not_set';
+export interface VtForceResult {
+    ok: boolean;
+    /** Absent on success; a stable machine token on failure, for the log. */
+    reason?: VtForceFailure;
+    before?: number;
+    after?: number;
+    /** Free-form context for the log line. Never shown to the user. */
+    detail?: string;
+}
+/**
+ * The PowerShell side, as a string.
+ *
+ * A LITERAL HERE-STRING (`@'` ... `'@`) around the C# so PowerShell expands
+ * nothing inside it, and `'CONIN$'` in single quotes for the same reason - the
+ * `$` is part of the device name, not a variable.
+ *
+ * Shipped inline rather than as a `.ps1` next to the build output, and that is a
+ * capability difference rather than tidiness: ExecutionPolicy blocks script
+ * FILES and does not apply to `-EncodedCommand`, so a locked-down machine - the
+ * population this bug keeps landing on - can still run it. It also removes the
+ * "where did my file go after packaging" class of failure entirely.
+ */
+export declare function buildHelperScript(): string;
+/** `-EncodedCommand` takes base64 of UTF-16LE, which needs no shell quoting. */
+export declare function encodePowerShellCommand(script: string): string;
+/**
+ * Prefer the absolute path so a sanitized or hijacked `PATH` cannot decide what
+ * runs; fall back to the bare name, which is still better than not trying.
+ */
+export declare function resolvePowerShellExe(env?: NodeJS.ProcessEnv): string;
+/** Pull `before=` / `after=` back out of the helper's stdout. */
+export declare function parseConsoleModes(stdout: string): {
+    before?: number;
+    after?: number;
+};
+/**
+ * PURE, and the reason this feature is testable without a Windows box: every
+ * interesting outcome - including the `0x01F7` wrong-console trap that returns
+ * exit code 0 - is decided here from two strings and a number.
+ */
+export declare function decideVtForceOutcome(run: {
+    status: number | null;
+    stdout: string;
+    stderr?: string;
+}): VtForceResult;
+export interface VtForceOptions {
+    platform?: string;
+    timeoutMs?: number;
+    /** Injected by the tests; defaults to a real `spawnSync`. */
+    run?: (exe: string, args: string[]) => {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+}
+/**
+ * Set the bit on the console this process is attached to.
+ *
+ * SYNCHRONOUS on purpose. The caller has to know the answer before it decides
+ * whether the mouse can report and whether to warn the user, and at the one
+ * moment this runs - after raw mode is up, before Ink renders - there is nothing
+ * else for the event loop to do. An async version would buy nothing and would
+ * spread the ordering across two files.
+ *
+ * NEVER THROWS.
+ */
+export declare function forceWindowsVtInput(opts?: VtForceOptions): VtForceResult;