@cruxy/cli 1.6.0 → 1.7.1

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
@@ -159,7 +275,7 @@ branch on them:
 | `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                                                                                                     |
 | `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                                                                                                             |
 | `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                                                             |
-| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                                                   |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_REQUEST_REJECTED`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                   |
 | `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`, `CRUXY_E_CHECKPOINT_FAILED`                                                                                            |
 | `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                            |
 | `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                                                   |

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

@@ -1,4 +1,4 @@
-import { ApiError, AuthError, BudgetExhaustedError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { ApiError, AuthError, BudgetExhaustedError, InvalidRequestError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
 import { scrubModelNames } from "../brand/index.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
@@ -199,6 +199,91 @@ export function apiError(underlying) {
         meta: status ? { status } : undefined,
     });
 }
+/**
+ * The gateway REJECTED what we sent (400/422) — it never reached a model.
+ *
+ * Everything else `classifyProviderError` produces says, in one wording or
+ * another, "wait and try again", because everything else IS a condition that
+ * passes. This one is not, and saying so is the entire point. The gateway parsed
+ * the request, found it invalid, and answered before any upstream call. The
+ * payload is built from this build's own code — the tool harness, the message
+ * shaping — so it is deterministic: a retry sends byte-identical content and
+ * earns a byte-identical refusal. There is no outage, nothing recovers on a
+ * clock, and no amount of patience helps.
+ *
+ * It follows that this is a DEFECT IN CRUXY and the only thing that fixes it is
+ * a code change. So the next steps say that instead of a soothing "retry in a
+ * moment", and they point at the issue tracker with a code to quote, because a
+ * report is the one action that actually moves this forward.
+ *
+ * The gateway's message names the offending tool when a tool is at fault (its
+ * validator emits `tool "<name>": ...`), and that name is the single most useful
+ * token in the whole error — it turns "cruxy is broken" into a filed issue
+ * someone can act on. It is lifted out of the SCRUBBED message, never the raw
+ * one, so the U.8 gag can never be undone by this path.
+ */
+export function apiRequestRejected(underlying) {
+    const status = underlying instanceof ApiError ? underlying.status : undefined;
+    const cause = scrubbedMessageOf(underlying);
+    const tool = toolNamedIn(cause);
+    return new CruxyError({
+        code: ErrorCode.ApiRequestRejected,
+        title: tool
+            ? `the provider rejected this request — the \`${tool}\` tool definition cruxy sent is invalid`
+            : "the provider rejected this request — cruxy sent something invalid",
+        cause,
+        nextSteps: [
+            // First, because it pre-empts the reflex the other API errors trained.
+            "retrying will NOT help: the same request would be sent again and refused identically",
+            "this is a defect in cruxy, not a provider outage — nothing recovers on its own",
+            tool
+                ? `report it at ${ISSUE_URL} with this code and the tool name \`${tool}\``
+                : `report it at ${ISSUE_URL} with this code and the cause line above`,
+        ],
+        underlying,
+        meta: {
+            ...(status !== undefined ? { status } : {}),
+            ...(tool !== undefined ? { tool } : {}),
+        },
+    });
+}
+/**
+ * The tool name in a gateway rejection, if it named one.
+ *
+ * The gateway's tool-schema validator prefixes its complaint with the offending
+ * function — `tool "apply_patch": parameters nests deeper than 8 levels` — so
+ * one quoted token after the word `tool` is the whole pattern. Anything else
+ * yields `undefined` and the caller falls back to generic wording: a WRONG tool
+ * name in a bug report is worse than none, so this never guesses.
+ *
+ * ── TEMPORARY COUPLING, AND IT IS THE WRONG KIND ────────────────────────────
+ *
+ * This reads the gateway's `error` MESSAGE, and the gateway's own contract
+ * (cruxy-ai/api, `internal/httpx/errcode.go`) says the message MAY change while
+ * the `code` MAY NOT. So this parses the half that is explicitly allowed to move
+ * under us — the exact coupling the code/message split exists to prevent.
+ *
+ * It is deliberate and bounded: today the code is the generic `invalid_request`,
+ * shared with bad JSON, a missing field and an unknown model, so the message is
+ * the ONLY thing distinguishing "this build's tool harness is permanently
+ * unusable" from "this one request was malformed". The tool name is the single
+ * most actionable token in the error and it is worth having; a regex that fails
+ * closed is the cheapest way to have it.
+ *
+ * Failing closed is what makes the risk acceptable. If the gateway rewords, this
+ * returns `undefined`, the caller drops to generic wording, and the error is
+ * still correct — less specific, never wrong. Nothing downstream branches on it.
+ *
+ * The real fix is server-side and filed as cruxy-ai/api#183: a distinct 400 code
+ * for harness-bound rejections (the `invalid_schema` precedent already exists
+ * for `response_format`), with the tool name as a STRUCTURED FIELD rather than a
+ * message prefix. When that lands, match on the code, read the field, and delete
+ * this function — do not "improve" the regex.
+ */
+function toolNamedIn(message) {
+    const match = /\btool "([^"]+)"/.exec(message ?? "");
+    return match?.[1];
+}
 export function apiRateLimit(underlying) {
     const retryAfterMs = underlying instanceof RateLimitError ? underlying.retryAfterMs : undefined;
     return new CruxyError({
@@ -657,15 +742,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 +777,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 },
     });
@@ -1416,6 +1518,14 @@ export function classifyProviderError(underlying) {
     if (underlying instanceof BudgetExhaustedError) {
         return budgetExhausted(underlying);
     }
+    // Also before the `ApiError` base. Without this arm a rejected request lands
+    // on the generic `apiError`, whose only next step is "retry in a moment; if it
+    // persists, check the provider's status" — advice that is wrong twice over for
+    // a 400: retrying re-sends the identical payload, and the provider's status
+    // page has nothing to say about a request it correctly refused.
+    if (underlying instanceof InvalidRequestError) {
+        return apiRequestRejected(underlying);
+    }
     if (underlying instanceof ApiError)
         return apiError(underlying);
     return null;

package/dist/errors/types.js

@@ -44,6 +44,18 @@ export const ErrorCode = {
     GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED",
     // api (exit 6)
     Api: "CRUXY_E_API",
+    /**
+     * The gateway REJECTED the request (400/422) rather than failing to serve it.
+     *
+     * A DISTINCT CODE from {@link Api} because the two are opposite kinds of fact
+     * and take opposite advice. `Api` covers a provider that could not serve a
+     * valid request — a condition, which passes, so "retry in a moment" is sound.
+     * This one covers a request the gateway parsed, judged invalid, and refused
+     * before any upstream call. The payload is deterministic: a retry sends
+     * identical bytes and earns an identical refusal. Telling someone to wait out
+     * a rejection is telling them to wait for a defect in cruxy to fix itself.
+     */
+    ApiRequestRejected: "CRUXY_E_API_REQUEST_REJECTED",
     ApiRateLimit: "CRUXY_E_API_RATE_LIMIT",
     ApiOverloaded: "CRUXY_E_API_OVERLOADED",
     BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED",
@@ -289,6 +301,11 @@ const EXIT_CODES = {
     [ErrorCode.GatewayUnreachable]: 5,
     [ErrorCode.GitPushFailed]: 5,
     [ErrorCode.Api]: 6,
+    // Still the API exit class: the failure arrived from the gateway, and a script
+    // wrapping cruxy should treat it the same way it treats any other API failure.
+    // The difference this code carries is what a HUMAN should do about it, which
+    // is the next steps, not the exit status.
+    [ErrorCode.ApiRequestRejected]: 6,
     [ErrorCode.ApiRateLimit]: 6,
     [ErrorCode.ApiOverloaded]: 6,
     [ErrorCode.BudgetExhausted]: 6,

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