@cruxy/cli 1.6.0 → 1.7.0

package/README.md

@@ -143,6 +143,122 @@ default 10; disable with `checkpoint.enabled = false`).
 **Boundary:** checkpoints cover working-tree files only. Commits, pushes, and
 PRs made during a run are never undone — the rollback preview says so.
 
+## Terminal & accessibility
+
+Cruxy probes the terminal once per run and reduces it to a handful of
+capabilities — color, unicode, cursor control, motion, screen-reader mode, size
+— which every rendered surface resolves a theme from. That is why degradation is
+consistent: there is one place that decides, not one decision per panel.
+
+Each axis has an environment override, and **the axes are independent**. Turning
+color off does not change which glyphs are used; asking for ASCII glyphs does not
+turn color off. A `NO_COLOR` terminal still gets `✓`, a colored `CRUXY_ASCII`
+terminal gets a green `[ok]`.
+
+### Color
+
+| Variable      | Effect                                                           |
+| ------------- | ---------------------------------------------------------------- |
+| `NO_COLOR`    | No ANSI color anywhere. Not muted color — **zero** escape bytes. |
+| `FORCE_COLOR` | Keep color even when stdout is a pipe or a file.                 |
+
+Color is on by default only when the stream is a TTY. `TERM=dumb` forces it off
+regardless.
+
+### Glyphs
+
+| Variable      | Effect                                                                                    |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `CRUXY_ASCII` | Use the ASCII glyph table: `[ok]` `[x]` `[ ]` `->` `...` in place of `✓` `✗` `○` `→` `…`. |
+
+Also implied by `TERM=dumb`. Piped output keeps unicode — writing `✓` to a file
+is fine, and forcing ASCII there would change long-standing behaviour for
+everything that already parses cruxy's output.
+
+### Screen readers
+
+| Variable              | Effect                                         |
+| --------------------- | ---------------------------------------------- |
+| `CRUXY_SCREEN_READER` | Screen-reader mode.                            |
+| `ACCESSIBLE`          | The same thing, under the ecosystem-wide name. |
+
+In this mode:
+
+- **status glyphs become words** — `✓ read_file` is announced as `done
+read_file`, and `◐` / `○` become `working` / `pending`, so a status mark is
+  never read out as bare punctuation;
+- **decorative marks collapse to nothing** — the `↻` cache marker, the text
+  cursor bar, and the cells of a progress bar all render as empty, because a run
+  of block characters announces as noise and the percentage beside it already
+  carries the whole meaning;
+- **animation is off** — screen-reader mode implies reduced motion, since a
+  spinner has no live region to animate into.
+
+**It is opt-in and never inferred.** Cruxy has no way to detect a screen reader,
+and inferring one from a non-TTY stdout would reword every piped and CI run in
+the world:
+
+```bash
+export CRUXY_SCREEN_READER=1
+```
+
+### Motion
+
+| Variable               | Effect                                         |
+| ---------------------- | ---------------------------------------------- |
+| `NO_MOTION`            | The ecosystem-wide reduced-motion signal.      |
+| `CRUXY_REDUCED_MOTION` | The explicit cruxy knob.                       |
+| `CRUXY_NO_SPINNER`     | Kept as an alias; flows through the same axis. |
+
+Any of them disables the frame clock outright — nothing is scheduled and no
+frame ever ticks, so every animation collapses to its static end-state, drawn
+once. Reduced motion is also implied by screen-reader mode.
+
+### The alternate screen
+
+| Variable              | Effect                                                                         |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `CRUXY_NO_ALT_SCREEN` | Keep the full-screen TUI in the normal buffer instead of the alternate screen. |
+
+By default the TUI runs on the terminal's alternate screen — the second buffer
+`less` and `vim` use. Leaving it restores the normal buffer byte for byte, so
+the prompt you started cruxy from comes back exactly as it was, with no
+frame-shaped hole in your scrollback.
+
+On a clean exit the last dozen lines of the conversation are echoed into the
+normal buffer, so the session survives in the shell's scrollback rather than
+being discarded with the alternate screen. The full transcript is the session
+log; this is the tail.
+
+The opt-out exists because the alternate screen is not universally available or
+wanted — multiplexers and emulators can be configured to refuse it, some
+capture-and-replay tooling reads only the normal buffer, and you may simply
+prefer your shell to keep the frame. It changes nothing else about the TUI, and
+it is ignored where the TUI does not run at all (a pipe, a screen reader,
+`TERM=dumb`).
+
+However cruxy exits — quit, `kill -TERM`, a hangup when the window closes, an
+uncaught error — the terminal is handed back: the frame erased, the cursor
+shown, the alternate screen left.
+
+### Size
+
+| Variable  | Effect                                       |
+| --------- | -------------------------------------------- |
+| `COLUMNS` | Terminal width, overriding what it reports.  |
+| `LINES`   | Terminal height, overriding what it reports. |
+
+These win over the stream's own values, which is what makes
+`COLUMNS=100 cruxy …` work in CI where the terminal reports no size at all. They
+fall back to 80 × 24. Unlike the flags above they take a **positive integer**; a
+value that is not one is ignored rather than treated as "set".
+
+### The "set" convention
+
+Every variable except `COLUMNS` / `LINES` follows the `NO_COLOR` rule: **any
+non-empty value counts as set.** `CRUXY_ASCII=1` and `CRUXY_ASCII=false` both
+enable ASCII glyphs — to turn one off, unset it or set it to the empty string.
+
 ## Errors & exit codes
 
 Every user-facing error prints a title, the cause (when known), concrete next

package/dist/agent/session.js

@@ -10,7 +10,7 @@ import { UsageCollector, accumulateCacheTokens, } from "../usage/index.js";
 import { Budget } from "./budget.js";
 import { estimateTokens, findCut } from "./context.js";
 import { runAgent, } from "./loop.js";
-import { DEFAULT_MODE, modeAutoApproves, modePlans, nextMode, parseMode, } from "./mode.js";
+import { DEFAULT_MODE, modeAutoApproves, modePlans, parseMode, } from "./mode.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
  * Re-exported from `agent/context.ts`, where the estimate now lives beside the
@@ -189,10 +189,6 @@ export class Session {
         this.args.recorder?.mode(this.mode);
         return this.mode;
     }
-    /** Advance one step around the mode ring (Shift+Tab). Returns the new mode. */
-    cycleMode() {
-        return this.setMode(nextMode(this.mode));
-    }
     /** Whether this session proposes a plan before executing (C.31). */
     getPlanMode() {
         return modePlans(this.mode);

package/dist/components/frame.js

@@ -4,9 +4,15 @@ import { resolveTheme } from "../theme/index.js";
 const CLEAR_LINE = "\r\x1b[2K";
 /** Move the cursor up one row. */
 const CURSOR_UP = "\x1b[1A";
+/** Erase the whole row the cursor is on, wherever the cursor is in it. */
+const ERASE_ROW = "\x1b[2K";
+/** Park the cursor at row 1, column 1. */
+const CURSOR_HOME = "\x1b[H";
+/** Park the cursor at the start of an absolute row (1-based). */
+const cursorToRow = (row) => `\x1b[${row};1H`;
 /** The visible text of a possibly-styled row (re-exported from the U.12 home). */
 export { stripAnsi };
-export function createFrame(write, caps) {
+export function createFrame(write, caps, opts = {}) {
     let drawn = 0;
     let lastLines = [];
     const ellipsis = resolveTheme(caps).glyph.ellipsis;
@@ -20,6 +26,16 @@ export function createFrame(write, caps) {
     const erase = () => {
         if (drawn === 0)
             return;
+        if (opts.absolute) {
+            // Every row named, then home — nothing is inferred from where the cursor
+            // happens to be, which is the whole point of the mode.
+            let out = "";
+            for (let row = 1; row <= drawn; row++)
+                out += cursorToRow(row) + ERASE_ROW;
+            write(out + CURSOR_HOME);
+            drawn = 0;
+            return;
+        }
         // Cursor sits at the end of the last drawn row: clear it, then walk up
         // clearing each prior row, ending at column 0 of the first frame row.
         let out = CLEAR_LINE;
@@ -28,7 +44,29 @@ export function createFrame(write, caps) {
         write(out);
         drawn = 0;
     };
+    const paintAbsolute = (lines) => {
+        // NO ERASE PASS. Each row is cleared as part of being rewritten, so the
+        // screen never passes through a blank intermediate state — which is both
+        // one fewer write and one fewer chance to flicker.
+        let out = "";
+        for (const [index, line] of lines.entries()) {
+            out += cursorToRow(index + 1) + ERASE_ROW + fitRow(line);
+        }
+        // Rows the previous paint used and this one does not. A shorter frame must
+        // not leave its own tail on screen.
+        for (let row = lines.length + 1; row <= drawn; row++) {
+            out += cursorToRow(row) + ERASE_ROW;
+        }
+        if (out !== "")
+            write(out);
+        drawn = lines.length;
+    };
     const paint = (lines) => {
+        if (opts.absolute) {
+            lastLines = lines;
+            paintAbsolute(lines);
+            return;
+        }
         erase();
         lastLines = lines;
         if (lines.length === 0)

package/dist/errors/constructors.js

@@ -657,15 +657,29 @@ export function gitPushFailed(branch, stderr) {
     });
 }
 // ── plan mode (exit 2 / 10) ───────────────────────────────────────────────────
-/** The agent's proposed plan was missing or malformed (plan mode, C.31). */
+/**
+ * The agent's proposed plan was MALFORMED (plan mode, C.31).
+ *
+ * Malformed, and only malformed. A turn that ends with no plan at all is not
+ * this: the propose phase is read-only plus `submit_plan`, so the model cannot
+ * have acted, and a plain answer to a plain question is an ordinary completed
+ * turn — `runPlanSession` returns it rather than raising here.
+ *
+ * The next steps say `/mode manual` because that is the lever a user in a
+ * planning mode actually has. Shift+Tab is how most people arrive at `plan` and
+ * `full-auto` in the first place, and there is no flag on the running session to
+ * take back; `--plan` only chooses what mode a fresh `cruxy run` STARTS in, so it
+ * is named last and only for that case.
+ */
 export function planInvalid(reason) {
     return new CruxyError({
         code: ErrorCode.PlanInvalid,
         title: "the agent did not produce a valid plan",
         cause: reason,
         nextSteps: [
-            "retry the task — the model must call `submit_plan` with at least one step",
-            "or run without `--plan` to execute directly",
+            "retry the task — a plan needs at least one step, each with a title and a rationale",
+            "or leave planning for this session: `/mode manual` (Shift+Tab cycles the same ring)",
+            "for a one-shot `cruxy run`, drop `--plan` / `agent.planMode` to execute directly",
         ],
         meta: { reason },
     });
@@ -678,7 +692,10 @@ export function planRevisionLimit(limit) {
         cause: "the revision limit was reached without an approved plan",
         nextSteps: [
             "restate the task more concretely, or split it into smaller tasks",
-            "run without `--plan` to execute directly",
+            // Same lever as planInvalid's, for the same reason: the session was most
+            // likely cycled into a planning mode with Shift+Tab, and there is no flag
+            // on it to drop.
+            "or leave planning for this session: `/mode manual` (Shift+Tab cycles the same ring)",
         ],
         meta: { limit },
     });

package/dist/lsp/index.js

@@ -1,5 +1,5 @@
 export * from "./types.js";
-export { DEFAULT_SPECS, EXT_TO_LANGUAGE, LspRegistry, binaryOnPath, languageForFile, } from "./registry.js";
+export { DEFAULT_SPECS, EXT_TO_LANGUAGE, LspRegistry, binaryOnPath, languageForFile, resolveBinary, } from "./registry.js";
 export { StdioTransport, TransportTimeoutError, killTree, } from "./transport.js";
 export { Server } from "./server.js";
 export { LspPool } from "./pool.js";

package/dist/lsp/registry.js

@@ -58,27 +58,45 @@ export function languageForFile(filePath) {
     return EXT_TO_LANGUAGE[ext] ?? null;
 }
 /**
- * Default binary-presence check: resolves `command` the way a shell would.
+ * Resolve `command` to an executable FILE, the way a shell would, or `null`.
+ *
  * An absolute/relative path is tested directly; a bare name is searched across
- * `PATH` (with `PATHEXT` on win32). Pure filesystem probing — never spawns.
- * Injectable via {@link LspRegistry} so tests can force present/absent.
+ * `PATH`. On win32 each candidate is also tried with every `PATHEXT` suffix,
+ * which is the only way `pnpm` finds `pnpm.cmd` — Windows installs almost every
+ * npm-shipped tool as a `.cmd` shim, and a lookup that tries the bare name alone
+ * reports a globally installed binary as absent.
+ *
+ * Pure filesystem probing — never spawns. THE ONLY PATH RESOLVER in the CLI
+ * besides `tools/shell/resolve-shell.ts`'s win32 shell hunt, deliberately: a
+ * third one would be a third place for the PATHEXT rule to be forgotten.
  */
-export const binaryOnPath = (command) => {
+export function resolveBinary(command, dirs = (process.env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)) {
+    // An explicit path names the file outright — nothing to search.
     if (command.includes(path.sep) || command.includes("/")) {
-        return isExecutable(command);
+        return isExecutable(command) ? command : null;
     }
-    const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    // PATHEXT only, never a bare `command` fallback on win32: a directory that
+    // holds `pnpm.cmd` usually holds an extensionless `pnpm` beside it (the sh
+    // shim npm installs for Git Bash), and that one cannot be spawned there.
     const exts = process.platform === "win32"
         ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
         : [""];
     for (const dir of dirs) {
         for (const ext of exts) {
-            if (isExecutable(path.join(dir, command + ext)))
-                return true;
+            const candidate = path.join(dir, command + ext);
+            if (isExecutable(candidate))
+                return candidate;
         }
     }
-    return false;
-};
+    return null;
+}
+/**
+ * Default binary-presence check — {@link resolveBinary} reduced to a yes/no.
+ * Injectable via {@link LspRegistry} so tests can force present/absent.
+ */
+export const binaryOnPath = (command) => resolveBinary(command) !== null;
 function isExecutable(candidate) {
     try {
         const stat = fs.statSync(candidate);

package/dist/plan/service.js

@@ -10,6 +10,9 @@ import { makeSubmitPlanTool } from "./submit-plan.js";
  * read-only + `submit_plan` registry so the agent cannot act before approval;
  * execution runs with the full registry, one step at a time, per-action U.3
  * gating intact.
+ *
+ * A propose phase that ends with NO plan is a completed conversational turn, not
+ * an error — see the `!holder.plan` branch below.
  */
 /** Default cap on plan revisions before failing loud. */
 export const MAX_PLAN_REVISIONS = 3;
@@ -81,9 +84,31 @@ export async function runPlanSession(args) {
             onRequestUsage: args.onRequestUsage,
         }));
         if (!holder.plan) {
-            throw planInvalid("the model ended its turn without calling submit_plan");
+            // NO PLAN IS NOT A FAILURE. The propose phase's registry is read-only plus
+            // `submit_plan`, so a turn that ends without a plan has structurally not
+            // ACTED — it has ANSWERED. "what does this function do?" is a perfectly
+            // ordinary thing to type while a planning mode is on, and the model
+            // replying to it is the correct outcome, not a malformed plan.
+            //
+            // Throwing here was also silently LOSING that reply. The session records
+            // the user's turn before the runner is called and adopts the returned
+            // history after it returns, so an exception left the question on disk with
+            // no answer beside it — a transcript that is wrong, not merely unhelpful.
+            // Returning the accumulated history keeps the answer in both.
+            //
+            // This holds on a revision pass too: a model that answers a piece of
+            // feedback with a question instead of a new plan is asking the user
+            // something, and the user can now answer it on the next turn.
+            return finish();
         }
         const plan = holder.plan;
+        // The one thing that IS invalid: a plan object with nothing executable in
+        // it. `submit_plan` rejects this to the model's face, so reaching it means
+        // something set the holder directly — fail loud rather than run an empty
+        // approval prompt over zero steps.
+        if (plan.steps.length === 0) {
+            throw planInvalid("submit_plan produced a plan with no steps");
+        }
         const decision = await promptPlanDecision(plan, args.io);
         if (decision.kind === "abort") {
             // Committed output goes through the renderer, not the prompt io (P3):

package/dist/plan/submit-plan.js

@@ -38,6 +38,17 @@ export function makeSubmitPlanTool(holder) {
             if (input.steps.length === 0) {
                 return { ok: false, error: "a plan must have at least one step" };
             }
+            // `min(1)` counts characters, so a title of `" "` clears zod and then
+            // trims to nothing — a step that renders as an empty row in the approval
+            // prompt and as an empty instruction during execution. Rejected the same
+            // way as any other tool-input error, so the model resubmits.
+            const blank = input.steps.findIndex((s) => s.title.trim() === "" || s.rationale.trim() === "");
+            if (blank !== -1) {
+                return {
+                    ok: false,
+                    error: `step ${blank + 1} has a blank title or rationale — every step needs both`,
+                };
+            }
             const steps = input.steps.map((s, i) => ({
                 id: String(i + 1),
                 title: s.title.trim(),

package/dist/render/capabilities.js

@@ -1,7 +1,14 @@
 import { shouldUseColor } from "../errors/index.js";
 import { detectScreenReader, detectUnicode } from "../theme/index.js";
-/** Set-and-non-empty (the NO_COLOR convention): any non-empty value counts. */
-function isSet(value) {
+/**
+ * Set-and-non-empty (the NO_COLOR convention): any non-empty value counts.
+ *
+ * Exported so every cruxy env flag reads the SAME rule. The README states it
+ * once for all of them — `CRUXY_ASCII=false` enables ASCII — and a flag that
+ * quietly parsed its value instead would make that documentation wrong for one
+ * variable with nothing to point at.
+ */
+export function isSet(value) {
     return value !== undefined && value !== "";
 }
 /** Fallback width when the terminal reports none (non-TTY, pipe, unknown). */

package/dist/render/index.js

@@ -8,7 +8,7 @@ import { TtyRenderer } from "./tty-renderer.js";
 import { TuiRenderer } from "../tui/renderer.js";
 import { GitStatusCache } from "../tui/git-status.js";
 import { ToolVersions } from "../tui/tool-versions.js";
-import { supportsTui } from "../tui/supports.js";
+import { supportsTui, usesAltScreen } from "../tui/supports.js";
 export { detectCapabilities, detectReducedMotion, resolveColumns, resolveRows, DEFAULT_COLUMNS, DEFAULT_ROWS, } from "./capabilities.js";
 export { attachResize, processResizeSignal, } from "./resize.js";
 export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, } from "./layout.js";
@@ -53,6 +53,11 @@ export function createRenderer(out = process.stdout, err = process.stderr, env =
             // Constructed, not started: `ToolVersions` probes nothing until the
             // renderer paints the panel, so this costs an object and no subprocess.
             tools: new ToolVersions(),
+            // Resolved against THIS factory's env (Q4 track 3), not `process.env`.
+            // The renderer's own default reads the real environment, which is right
+            // for a direct construction and wrong here: an injected env exists
+            // precisely so a caller can describe a terminal that is not this one.
+            altScreen: usesAltScreen(caps, env),
         });
     }
     return caps.cursor

package/dist/tui/app.js

@@ -5,6 +5,7 @@ import { TUI_ONLY_COMMANDS } from "../cli/command-catalog.js";
 import { selectList } from "../components/select.js";
 import { viewLabel, viewOrder } from "./views.js";
 import { canOverlay, createKeyLease, createOverlayIO, } from "./overlay.js";
+import { ModeRing } from "./mode-ring.js";
 import { openPalette } from "./palette.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { CLOSABLE_PANELS, columnOf, RAIL_PANELS, } from "./layout.js";
@@ -263,7 +264,11 @@ async function readLine(keys, renderer, hooks) {
                     // Mode is a property of the session, not of the message — losing a
                     // half-written prompt to a mode switch would make the binding one
                     // people learn not to press.
-                    hooks.cycleMode();
+                    //
+                    // The chip moves on this keypress; the session hears about it when the
+                    // ring stops turning (Q5). Passing `paint` gives the ring a way to
+                    // correct the chip if the settle resolves somewhere else.
+                    hooks.cycleMode(paint);
                     paint();
                     break;
                 case "page-up":
@@ -302,6 +307,11 @@ async function readLine(keys, renderer, hooks) {
         }
     }
     finally {
+        // The line is over — by Enter, by EOF, by Ctrl+C. Whatever the ring stopped
+        // on is what the user chose, and it is committed and announced HERE rather
+        // than a debounce later, so the mode is in force before the turn it was
+        // chosen for runs and its log event lands ahead of that turn's messages.
+        hooks.settleMode();
         keys.restore();
     }
 }
@@ -476,9 +486,14 @@ export async function runTui(session, renderer, opts = {}) {
         theme: renderer.theme,
         fit: (line) => line,
     };
+    // The mode ring (Q5). The chip follows every press; the session is told once,
+    // when the presses stop — see `mode-ring.ts` for why passing through a mode is
+    // not the same as choosing it.
+    const ring = new ModeRing(session, (mode) => announceMode(out, mode), opts.modeSettleMs);
     const hooks = {
-        mode: () => session.getMode(),
-        cycleMode: () => announceMode(out, session.cycleMode()),
+        mode: () => ring.current(),
+        cycleMode: (repaint) => ring.advance(repaint),
+        settleMode: () => ring.settle(),
         openPalette: () => openPalette(renderer, lease, opts.slashCommands ?? []),
     };
     // The TUI's picker (P6 track 1): an overlay drawer on the SAME reader this

package/dist/tui/index.js

@@ -8,9 +8,10 @@ export { createOverviewView } from "./overview.js";
 export { createGitView, gitViewLines, GIT_VIEW_MAX_FILES, } from "./git-view.js";
 export { createTasksView, tasksViewLines, TASKS_VIEW_MAX_JOBS, TASKS_VIEW_TAIL, } from "./tasks-view.js";
 export { createSettingsView, settingsViewLines, formatSettingValue, } from "./settings-view.js";
-export { TuiRenderer, PAINT_INTERVAL_MS, VIEW_PULSE_MS, SCROLL_PAGE_OVERLAP, SCROLLBACK_LINES, } from "./renderer.js";
+export { TuiRenderer, EXIT_TAIL_LINES, PAINT_INTERVAL_MS, VIEW_PULSE_MS, SCROLL_PAGE_OVERLAP, SCROLLBACK_LINES, } from "./renderer.js";
 export { CONVERSATION_VIEW, cycleView, navLines, viewLabel, viewOrder, } from "./views.js";
 export { runTui, renderInput, TUI_COMMANDS } from "./app.js";
 export { openPalette, paletteItems, paletteInsertion, paletteLabel, } from "./palette.js";
 export { canOverlay, createKeyLease, createOverlayFrame, createOverlayIO, } from "./overlay.js";
-export { supportsTui } from "./supports.js";
+export { supportsTui, usesAltScreen } from "./supports.js";
+export { installScreenGuard, restoreAllScreens, screenGuardCount, RESTORE_SIGNALS, SIGNAL_EXIT_CODES, } from "./restore.js";

package/dist/tui/mode-ring.js

@@ -0,0 +1,84 @@
+import { nextMode } from "../agent/index.js";
+/**
+ * The Shift+Tab mode ring, debounced (Q5).
+ *
+ * Shift+Tab walks a four-entry cycle, so reaching `full-auto` from `manual`
+ * means passing THROUGH `auto-approve` and `plan`. Every press used to be a
+ * commit: three `setMode` calls, three `mode` events appended to the session
+ * log, and three announcements — two of them for modes the user was not stopping
+ * on and never saw. The log then read as a session that deliberately chose
+ * auto-approve, then planning, then full-auto, which is not what happened; and
+ * the conversation column filled with descriptions of modes that were already
+ * gone by the time they were painted.
+ *
+ * So the ring turns freely and commits once. `current()` is the mode the ring is
+ * POINTING AT — the chip reads it, so every press still lands instantly on
+ * screen, which is the feedback the keypress owes the user. The session only
+ * hears about it once the presses stop, and that single commit is what gets
+ * announced and journaled.
+ *
+ * The chip is not a promise. `setMode` returns the EFFECTIVE mode (a session
+ * with no plan runner cannot enter a planning mode), so a settle that resolves
+ * elsewhere corrects the chip and announces where it actually landed.
+ */
+/** Quiet period after the last press before the ring is taken as settled. */
+export const MODE_SETTLE_MS = 400;
+export class ModeRing {
+    session;
+    announce;
+    settleMs;
+    /** Where the ring is pointing, or null when it matches the committed mode. */
+    pending = null;
+    timer = null;
+    /** Repaint for a settle that lands on the timer rather than on a key. */
+    repaint;
+    constructor(session, announce, settleMs = MODE_SETTLE_MS) {
+        this.session = session;
+        this.announce = announce;
+        this.settleMs = settleMs;
+    }
+    /** The mode to SHOW. Pure — safe on the paint path, called every keystroke. */
+    current() {
+        return this.pending ?? this.session.getMode();
+    }
+    /**
+     * One press of Shift+Tab: advance the ring and restart the quiet period.
+     * `repaint` runs after a settle that lands on the timer, because the input
+     * row's chip is a stored string and a correction to it needs a new paint.
+     */
+    advance(repaint) {
+        this.pending = nextMode(this.current());
+        this.repaint = repaint;
+        this.arm();
+    }
+    /**
+     * Commit what the ring stopped on, now — the caller knows the turn is over
+     * (Enter, EOF) and will not wait out the timer. A no-op when nothing is
+     * pending, so it is safe in a `finally` on every line.
+     */
+    settle() {
+        this.disarm();
+        const want = this.pending;
+        if (want === null)
+            return;
+        this.pending = null;
+        this.announce(this.session.setMode(want));
+    }
+    arm() {
+        this.disarm();
+        const timer = setTimeout(() => {
+            this.timer = null;
+            this.settle();
+            this.repaint?.();
+        }, this.settleMs);
+        // A decorative debounce must never be the reason a process stays alive.
+        timer.unref?.();
+        this.timer = timer;
+    }
+    disarm() {
+        if (this.timer === null)
+            return;
+        clearTimeout(this.timer);
+        this.timer = null;
+    }
+}

package/dist/tui/renderer.js

@@ -12,6 +12,8 @@ import { budgetColumns, bodyRows, composeScreen, droppedForWidth, fitOverlay, ov
 import { CONVERSATION_VIEW, cycleView, navLines, } from "./views.js";
 import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelLines, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
 import { limitsPanelLines } from "./limits-panel.js";
+import { installScreenGuard, } from "./restore.js";
+import { usesAltScreen } from "./supports.js";
 /**
  * The full-viewport renderer (P1) — the fourth {@link StreamRenderer}, and the
  * only one that owns the whole screen rather than a single managed line.
@@ -35,8 +37,36 @@ import { limitsPanelLines } from "./limits-panel.js";
  *    Paints are marked dirty and flushed at most every {@link PAINT_INTERVAL_MS},
  *    which keeps streaming smooth without a redraw per token.
  */
+/**
+ * Enter the alternate screen buffer and hide the cursor (Q4 track 3), and the
+ * exact inverse. Emitted as one pair by one object, in one order, so there is
+ * no arrangement of them that can leave a terminal half-restored.
+ *
+ * The cursor is hidden because this renderer DRAWS its caret (see
+ * `renderInput`): the real cursor parks wherever the last painted row ended,
+ * which is a second, wrong caret blinking somewhere in the frame.
+ */
+const ENTER_ALT_SCREEN = "\x1b[?1049h\x1b[?25l";
+const LEAVE_ALT_SCREEN = "\x1b[?25h\x1b[?1049l";
 /** Coalescing window for repaints (~30fps). */
 export const PAINT_INTERVAL_MS = 33;
+/**
+ * Logical lines of the conversation echoed into the NORMAL buffer when the TUI
+ * exits cleanly (Q4 track 3).
+ *
+ * The alternate screen is discarded when it is left — that is the whole point
+ * of it, and it is why the shell comes back exactly as it was. It also means
+ * the session the user just had would be gone the instant they typed `/exit`:
+ * no transcript in the scrollback, nothing to copy an error message out of,
+ * nothing to page back through. Losing that is a real regression, and an env
+ * knob nobody finds is not a fix for it.
+ *
+ * A dozen lines is chosen to be a REMINDER rather than a transcript. It is
+ * enough to carry the last answer and the command that produced it, and short
+ * enough that quitting a long session does not dump a screenful into the shell.
+ * The session log is the transcript; this is the tail.
+ */
+export const EXIT_TAIL_LINES = 12;
 /**
  * How often a selected view that reports itself {@link ViewSource.live} gets
  * repainted with no other event to prompt it (P7 track 5).
@@ -57,6 +87,18 @@ export class TuiRenderer {
     theme;
     out;
     frame;
+    /**
+     * The process-level restore backstop (Q4 track 1). Installed at construction
+     * — the moment this renderer starts owning the screen — and dropped in
+     * {@link close}, so a process with no TUI up carries no handlers.
+     */
+    guard;
+    /** Whether this renderer took the alternate screen and owes the inverse. */
+    altScreen;
+    /** Lines the opening banner occupies — the buffer's contents at construction. */
+    openingLines;
+    /** Logical lines committed since construction, INCLUDING ones rolled off. */
+    committed = 0;
     /** Committed conversation content, UNWRAPPED — wrapped fresh at each paint. */
     buffer = [];
     /** The streamed line still being assembled (no newline seen yet). */
@@ -149,7 +191,35 @@ export class TuiRenderer {
         this.initialModel = opts.model;
         this.tools = opts.tools;
         this.buffer = mainWelcome(this.theme, "/help for commands · /exit to quit");
-        this.frame = createFrame((text) => this.out.write(text), caps);
+        this.openingLines = this.buffer.length;
+        // THE ALTERNATE SCREEN (Q4 track 3), taken before a single byte is painted.
+        //
+        // This is what makes track 2's absolute addressing safe to use here. Rows
+        // land at screen positions 1..n, so without a buffer of its own the shell
+        // would overwrite whatever the terminal was showing — the user's last
+        // screenful of shell history, gone rather than scrolled into scrollback.
+        // On the alternate screen there is nothing to overwrite, and leaving it
+        // restores the normal buffer byte for byte: the prompt cruxy was started
+        // from comes back exactly as it was, with no frame-shaped hole in it.
+        //
+        // The inverse is owed from this line onward, which is why track 1 landed
+        // first: `close()` is not the only way out of this constructor's reach.
+        this.altScreen = opts.altScreen ?? usesAltScreen(caps);
+        if (this.altScreen)
+            out.write(ENTER_ALT_SCREEN);
+        // ABSOLUTE rows (Q4 track 2). This renderer owns the viewport outright, so
+        // it has no reason to infer where its rows are from where the cursor was
+        // left — and every reason not to. A frame this tall repaints thirty times a
+        // second; one cursor position the walk got wrong (a stray byte, a soft-wrap
+        // the width math did not predict, a scroll) would put every subsequent
+        // paint one row further off, with no paint able to recover. Row 1 is row 1.
+        this.frame = createFrame((text) => this.out.write(text), caps, {
+            absolute: true,
+        });
+        // Installed here, not in `close()`'s vicinity, because the window it covers
+        // opens with the first paint: from this line on there is a shell on screen
+        // that only this object knows how to take down.
+        this.guard = installScreenGuard(() => this.releaseScreen(), opts.signals);
         // The single shared clock (U.10): an inert clock under reduced motion, so
         // the spinner is drawn once statically and no timer is ever scheduled.
         this.clock = createFrameClock(caps.spinner);
@@ -763,11 +833,78 @@ export class TuiRenderer {
         this.unsubscribeResize = null;
         this.unsubscribeModel?.();
         this.unsubscribeModel = null;
-        // Erase the whole shell: after the TUI exits the terminal holds zero
-        // leftover bytes from it, exactly like a resolved component frame.
-        this.frame.clear();
+        // Erase the whole shell through the SAME path a signal takes (Q4 track 1),
+        // so a clean exit and a killed one leave the terminal in one state rather
+        // than two that drift apart the next time either is edited. The guard is
+        // idempotent, so the two can also race harmlessly.
+        this.guard.restoreScreen();
+        this.guard.dispose();
+        // AFTER the screen is handed back, so this lands in the normal buffer and
+        // survives in the shell's scrollback (Q4 track 3). On the clean path only:
+        // a signal handler's job is to give the terminal up, not to write a report
+        // into a shell the user may not be looking at.
+        this.printExitTail();
     }
     // ── internals ─────────────────────────────────────────────────────────────
+    /**
+     * Hand the terminal back (Q4 track 1): everything {@link close} does to the
+     * SCREEN, and nothing it does to the session. This is what the signal and
+     * exit handlers run, so it must be safe from a context where nothing async
+     * can be awaited and nothing that throws will be reported.
+     *
+     * After the TUI releases the screen the terminal holds zero leftover bytes
+     * from it, exactly like a resolved component frame.
+     *
+     * `closed` is set here rather than only in `close()`: on the signal path this
+     * is the last thing that runs before `process.exit`, and a repaint scheduled
+     * in between would draw a shell back onto a terminal that has just been
+     * handed over.
+     */
+    releaseScreen() {
+        this.closed = true;
+        this.frame.clear();
+        // The exact inverse of the constructor's pair, and the last bytes this
+        // renderer ever writes to the managed screen.
+        if (this.altScreen)
+            this.out.write(LEAVE_ALT_SCREEN);
+    }
+    /**
+     * Echo the tail of the conversation into the normal buffer (Q4 track 3).
+     *
+     * The alternate screen is discarded when it is left, so without this the
+     * session would vanish the moment the user typed `/exit` — no transcript in
+     * the scrollback, no error message left to copy, nothing to page back
+     * through. That is a regression the alternate screen would otherwise trade
+     * for a clean prompt, and it is not a trade worth making silently.
+     *
+     * Nothing is printed for a session that produced nothing: opening the shell
+     * and quitting leaves the terminal exactly as it was found, which is what the
+     * alternate screen is for. When some output DID roll past the tail, the count
+     * says so — and it counts every line ever committed, including the ones that
+     * rolled off the scrollback buffer entirely, so the number is the true amount
+     * hidden rather than the amount this object still happens to remember.
+     *
+     * Lines go out unwrapped and untruncated. The normal buffer soft-wraps them,
+     * which is right: this is the copy the user keeps, and nothing in it should be
+     * cut to a width the terminal is no longer being managed at.
+     */
+    printExitTail() {
+        if (this.committed === 0)
+            return;
+        const shown = this.buffer.slice(Math.max(0, this.buffer.length - EXIT_TAIL_LINES));
+        if (shown.length === 0)
+            return;
+        const hidden = this.openingLines + this.committed - shown.length;
+        const notice = hidden > 0
+            ? [
+                this.theme.muted(`… ${hidden} earlier line${hidden === 1 ? "" : "s"} not shown`),
+            ]
+            : [];
+        // Leading and trailing blank rows: this is a quotation dropped into the
+        // shell, and it needs to read as separate from both the prompt above it and
+        // whatever the exit path prints below.
+        this.out.write(["", ...notice, ...shown, ""].join("\n"));
+    }
     newPrinter() {
         return createStreamPrinter((text) => {
             this.commit(this.highlighter.push(text));
@@ -814,6 +951,10 @@ export class TuiRenderer {
             this.scrollOffset += added;
         }
         this.buffer.push(...lines);
+        // Counted here rather than measured off the buffer at exit, because the
+        // buffer forgets: `committed` has to keep counting past the roll-off below
+        // for the exit tail's "N earlier lines" to be a true number.
+        this.committed += lines.length;
         if (this.buffer.length > SCROLLBACK_LINES) {
             this.buffer = this.buffer.slice(this.buffer.length - SCROLLBACK_LINES);
         }

package/dist/tui/restore.js

@@ -0,0 +1,137 @@
+/**
+ * The terminal-restore backstop (Q4 track 1).
+ *
+ * `TuiRenderer.close()` hands the terminal back — it erases the frame, and from
+ * track 3 on it also leaves the alternate screen and shows the cursor again.
+ * That covers exactly one way a run ends: the orderly one. Every other way, the
+ * process dies with the shell still painted and the terminal still configured
+ * the way the TUI left it, and the user's next prompt lands in the middle of a
+ * frame that nothing will ever erase. `kill -TERM`, a hangup when the terminal
+ * window closes, an `ssh` session dropping, `kill -INT` from another pane — all
+ * of them terminate the process by DEFAULT DISPOSITION, which runs no JavaScript
+ * at all.
+ *
+ * So the restore is registered with the process rather than left to the caller:
+ *
+ * - **`SIGINT` / `SIGTERM` / `SIGHUP`** — restore, then exit with the shell's
+ *   conventional 128 + signal code. `process.exit` rather than re-raising is
+ *   deliberate: Node restores the original termios (`ResetStdio`, an `atexit`
+ *   hook) on a normal exit but not when the default disposition fells the
+ *   process, and the TUI holds stdin in RAW MODE for most of its life. Dying
+ *   from the signal itself would leave a terminal with no echo and no line
+ *   editing — a worse outcome than the painted frame this module exists to
+ *   clean up.
+ * - **`exit`** — the last line, for the paths no signal handler sees: an
+ *   uncaught throw, an explicit `process.exit` somewhere else, and the signal
+ *   handlers that other modules install first ({@link ../utils/child-tree.js}
+ *   registers `SIGINT` too, and whichever ran first calls `process.exit`
+ *   straight away). Synchronous work only, which a write to a TTY is.
+ *
+ * Handlers are installed on the FIRST registration and removed when the last
+ * guard goes away, so a closed TUI leaves the process exactly as it found it and
+ * N renderers (a test file builds dozens) still cost one listener per event.
+ * This is the same shape as the child-process exit backstop in
+ * {@link ../utils/child-tree.js}, for the same reason.
+ */
+/** Signals that end a run before the normal teardown gets a turn. */
+export const RESTORE_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/**
+ * The exit code a shell reports for a process felled by each signal: 128 + n.
+ * Stated rather than inherited, because these handlers exit explicitly (see the
+ * raw-mode note above) and an exit code of 0 after a `kill -TERM` would tell
+ * every script that reads one that the run succeeded.
+ */
+export const SIGNAL_EXIT_CODES = {
+    SIGINT: 130,
+    SIGTERM: 143,
+    SIGHUP: 129,
+};
+/** Live guards, in registration order. Each entry is its own idempotent runner. */
+const guards = new Set();
+/** The installed listeners, or null when no guard is registered. */
+let handlers = null;
+/**
+ * Run every registered restore, once each. Exported because it IS what the
+ * handlers run: a test that calls this is testing the real path rather than a
+ * reimplementation of it.
+ *
+ * Iterates a copy — a restore deregisters itself as it runs — and a restore
+ * that throws does not stop the others. There is nowhere to report an error
+ * from here (the process is on its way out, and the screen is the thing that
+ * would show it), and one guard failing must not leave the next one's terminal
+ * in the alternate screen forever.
+ */
+export function restoreAllScreens() {
+    for (const run of [...guards])
+        run();
+}
+function installHandlers(host) {
+    if (handlers !== null)
+        return;
+    const entries = [
+        ["exit", restoreAllScreens],
+        ...RESTORE_SIGNALS.map((signal) => [
+            signal,
+            () => {
+                restoreAllScreens();
+                host.exit(SIGNAL_EXIT_CODES[signal]);
+            },
+        ]),
+    ];
+    for (const [event, listener] of entries)
+        host.on(event, listener);
+    handlers = { host, entries };
+}
+function removeHandlers() {
+    if (handlers === null)
+        return;
+    for (const [event, listener] of handlers.entries) {
+        handlers.host.off(event, listener);
+    }
+    handlers = null;
+}
+/**
+ * Register `restore` to run if the process is signalled or exits, and return the
+ * handle that also lets the owner run it directly.
+ *
+ * The first registration installs the handlers; the last one to go removes
+ * them. `host` is read only on that first call — it names the process the
+ * handlers are installed on, and there is only ever one.
+ */
+export function installScreenGuard(restore, host = process) {
+    let restored = false;
+    let live = true;
+    const deregister = () => {
+        if (!live)
+            return;
+        live = false;
+        guards.delete(run);
+        if (guards.size === 0)
+            removeHandlers();
+    };
+    const run = () => {
+        if (restored)
+            return;
+        restored = true;
+        // Deregistered BEFORE the restore runs, so a throwing restore still gives
+        // the handlers up rather than pinning them for the life of the process.
+        deregister();
+        try {
+            restore();
+        }
+        catch {
+            // See `restoreAllScreens`: there is no surface left to report on.
+        }
+    };
+    guards.add(run);
+    installHandlers(host);
+    return {
+        restoreScreen: run,
+        restored: () => restored,
+        dispose: deregister,
+    };
+}
+/** Guards currently registered — for tests, the way `trackedTreeCount` is. */
+export function screenGuardCount() {
+    return guards.size;
+}

package/dist/tui/supports.js

@@ -1,3 +1,4 @@
+import { isSet } from "../render/capabilities.js";
 /**
  * Whether the environment can host the full-viewport TUI.
  *
@@ -18,3 +19,24 @@
 export function supportsTui(caps) {
     return caps.interactive && !caps.screenReader;
 }
+/**
+ * Whether the TUI runs on the ALTERNATE SCREEN (Q4 track 3) — the terminal's
+ * second buffer, the one `less` and `vim` use.
+ *
+ * Gated on {@link supportsTui} and nothing new: a terminal that cannot host the
+ * shell has no business being switched to another buffer, and the two questions
+ * have exactly one answer between them. Adding a second capability check here
+ * would only create a state where the TUI runs but its screen management does
+ * not — which is the drift the one gate exists to prevent.
+ *
+ * `CRUXY_NO_ALT_SCREEN` opts out, following the same set-and-non-empty rule as
+ * every other cruxy flag. The opt-out exists because the alternate screen is not
+ * universally available or wanted: multiplexers and terminal emulators can be
+ * configured to refuse it, some capture-and-replay tooling reads only the normal
+ * buffer, and a user who prefers the shell to keep the frame in its scrollback
+ * should not have to stop using the TUI to get that. Opting out changes nothing
+ * else — the shell, the row addressing and the restore backstop are unaffected.
+ */
+export function usesAltScreen(caps, env = process.env) {
+    return supportsTui(caps) && !isSet(env.CRUXY_NO_ALT_SCREEN);
+}

package/dist/tui/tool-versions.js

@@ -1,4 +1,9 @@
 import { execFile } from "node:child_process";
+import path from "node:path";
+// The concrete module, not `lsp/index.js`: that barrel pulls in the transport,
+// the pool and the client, and this panel exists to keep cost off the startup
+// path. `resolveBinary` is a leaf over `node:fs`.
+import { resolveBinary } from "../lsp/registry.js";
 /**
  * Host tool versions for the rail (P4 track 5).
  *
@@ -20,9 +25,82 @@ import { execFile } from "node:child_process";
  * DAEMON and reports a stopped Docker as absent. This panel is reporting what
  * is INSTALLED, so it asks the client (`docker --version`), which answers with
  * the daemon down.
+ *
+ * WHICH tsc, though. The panel sits beside a repo, and the toolchain that
+ * matters there is the repo's: a project pinning TypeScript 5.4 in its
+ * devDependencies was being reported at whatever version happens to be global,
+ * or as "not found" when nothing is global at all — the ordinary case, since
+ * `pnpm`/`npx` run these out of `node_modules/.bin` and most people never
+ * install them globally. So each tool is looked for in `node_modules/.bin`,
+ * walking up from the working directory the way Node's own resolution does,
+ * before falling back to `PATH`.
+ *
+ * That lookup is {@link resolveBinary}, the LSP registry's — which also fixes a
+ * latent Windows bug this module had on the PATH half. Windows installs
+ * npm-shipped tools as `.cmd` shims, and `execFile("tsc")` there resolves
+ * nothing: `tsc.cmd` needs the `PATHEXT` sweep the registry already does by
+ * stat, and then needs `cmd.exe` to run it at all.
  */
 /** Hard ceiling on one probe; a hung binary must never wedge the panel. */
 const PROBE_TIMEOUT_MS = 5000;
+/**
+ * Every `node_modules/.bin` from `from` up to the filesystem root, nearest
+ * first — the same walk Node's module resolution does, and the same order
+ * `pnpm`/`npx` pick a binary in. Directories that do not exist cost nothing:
+ * `resolveBinary` stats the candidate and moves on.
+ */
+export function binDirsFrom(from) {
+    const dirs = [];
+    let dir = path.resolve(from);
+    for (;;) {
+        dirs.push(path.join(dir, "node_modules", ".bin"));
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return dirs;
+        dir = parent;
+    }
+}
+/**
+ * Where a probe should actually spawn `bin` from: the nearest project-local
+ * copy, else whatever `PATH` offers, else `null` — which is an ANSWER ("not
+ * installed"), reached without spawning anything.
+ */
+export function resolveToolBinary(bin, from) {
+    return resolveBinary(bin, binDirsFrom(from)) ?? resolveBinary(bin);
+}
+/**
+ * How to invoke a resolved binary.
+ *
+ * On win32 a `.cmd`/`.bat` is a script, not an image: `CreateProcess` cannot run
+ * one, and Node has REFUSED to try since the CVE-2024-27980 fix — it throws
+ * EINVAL rather than silently handing the arguments to a shell. So a shim is run
+ * through `cmd.exe` explicitly. Everything else is spawned directly, unchanged.
+ *
+ * THE DOUBLE WRAP IS NOT A TYPO, and it is the whole reason this is a named
+ * function with its own tests. cmd.exe strips the first and last quote of the
+ * `/c` string when the string both begins and ends with one. Quoting only the
+ * path gives `cmd /c "C:\Program Files\x\t.cmd"` — begins and ends with a quote,
+ * so cmd removes both and then tries to run `C:\Program`. Appending `--version`
+ * happens to hide it (the string no longer ends in a quote), which is the worst
+ * kind of working: it breaks the day a probe takes no arguments, and every tool
+ * here is one `args: []` away from that.
+ *
+ * Wrapping the whole command line in a second pair makes `/s` the rule instead
+ * of an accident: `/s` strips exactly the outer pair and preserves the rest
+ * verbatim, so the inner quotes reach the parser intact either way. Node must
+ * not re-quote on top, hence `windowsVerbatimArguments` at the spawn.
+ */
+export function invocationFor(file, args, platform = process.platform, comSpec = process.env.ComSpec ?? "cmd.exe") {
+    if (platform === "win32" && /\.(cmd|bat)$/i.test(file)) {
+        const line = [`"${file}"`, ...args].join(" ");
+        return {
+            file: comSpec,
+            args: ["/d", "/s", "/c", `"${line}"`],
+            verbatim: true,
+        };
+    }
+    return { file, args: [...args], verbatim: false };
+}
 /**
  * Pull a semantic version out of a tool's `--version` line.
  *
@@ -35,24 +113,47 @@ const PROBE_TIMEOUT_MS = 5000;
 export function parseVersion(output) {
     return /\d+\.\d+\.\d+(?:[-+][\w.]+)?/.exec(output)?.[0] ?? null;
 }
-/** Default probe: spawn, capture, and treat any failure as "not installed". */
-const spawnProbe = (bin, args) => new Promise((resolve) => {
-    try {
-        execFile(bin, [...args], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS, windowsHide: true }, (err, stdout, stderr) => {
-            // Some tools print their version to stderr; a non-zero exit with a
-            // parseable version still tells us the tool is there.
-            const text = `${stdout ?? ""}${stderr ?? ""}`;
-            if (err && text.trim() === "")
-                resolve(null);
-            else
-                resolve(text);
-        });
-    }
-    catch {
-        // execFile can throw synchronously on a malformed binary path.
-        resolve(null);
-    }
-});
+/**
+ * The default probe: resolve, spawn, capture — and treat any failure as "not
+ * installed". Resolution comes first, so a tool that is nowhere costs a few
+ * `stat` calls rather than a process that has to fail.
+ *
+ * `from` exists so the win32 e2e can point a real probe at a real `.cmd` shim in
+ * a temp project. Left unset it reads `process.cwd()` PER CALL, never once at
+ * module load — the panel must follow the session's directory, not the one the
+ * process happened to start in.
+ */
+export function makeSpawnProbe(from) {
+    return (bin, args) => new Promise((resolve) => {
+        const resolved = resolveToolBinary(bin, from ?? process.cwd());
+        if (resolved === null) {
+            resolve(null);
+            return;
+        }
+        const call = invocationFor(resolved, args);
+        try {
+            execFile(call.file, call.args, {
+                encoding: "utf8",
+                timeout: PROBE_TIMEOUT_MS,
+                windowsHide: true,
+                ...(call.verbatim ? { windowsVerbatimArguments: true } : {}),
+            }, (err, stdout, stderr) => {
+                // Some tools print their version to stderr; a non-zero exit with a
+                // parseable version still tells us the tool is there.
+                const text = `${stdout ?? ""}${stderr ?? ""}`;
+                if (err && text.trim() === "")
+                    resolve(null);
+                else
+                    resolve(text);
+            });
+        }
+        catch {
+            // execFile can throw synchronously on a malformed binary path.
+            resolve(null);
+        }
+    });
+}
+const spawnProbe = makeSpawnProbe();
 /**
  * The tools reported, in display order.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {