@cruxy/cli 1.5.0 → 1.7.0

package/dist/cli/session-commands.js

@@ -1,11 +1,15 @@
 import { MODE_LABELS, SESSION_MODES, modeDescription, modeFromFlags, parseMode, } from "../agent/index.js";
 import { existsSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { COMMAND_CATALOG } from "./command-catalog.js";
 import { contextReport } from "../agent/context.js";
 import { buildSessionStatus } from "../agent/status.js";
+import { resolveCheckpointDiff } from "../checkpoint/diff.js";
+import { rollbackLatestRun } from "../checkpoint/run-rollback.js";
 import { scaffoldProjectInstructions } from "../config/index.js";
 import { resolveSlash } from "../hooks/index.js";
 import { contextReportLines } from "../render/context-view.js";
+import { compactTokens } from "../render/units.js";
 import { renderUnifiedDiff } from "../render/index.js";
 import { sessionStatusLines } from "../render/status-view.js";
 import { defaultExportName, exportMarkdown } from "../session/index.js";
@@ -18,73 +22,11 @@ import { runGatedShell } from "../tools/shell/exec.js";
 import { addRootToWorkspace } from "../workspace/index.js";
 import { formatError, fromUnknown, isVerbose } from "../errors/index.js";
 /**
- * The commands shared by both shells, in the order `/help` lists them.
- *
- * ONE catalogue, three consumers: the help text, Tab completion, and the
- * command palette. They used to be three hand-maintained lists — which is how
- * the TUI ended up exporting a command list nothing consumed while advertising
- * a help text that named commands it could not run.
- *
- * Panel commands (`/close`, `/open`) are the TUI's alone and live in
- * `tui/app.ts`; they have no meaning in a shell with no panels.
+ * Re-exported so the many callers that already reach for the catalogue through
+ * this module keep working; the data itself lives in the leaf `command-catalog`
+ * so `hooks/` can read the reserved set without closing an import cycle.
  */
-export const COMMAND_CATALOG = [
-    { name: "/help", summary: "show this help" },
-    {
-        name: "/clear",
-        summary: "clear the conversation history (keep the session)",
-    },
-    {
-        name: "/compact",
-        summary: "summarize older history to free up context now",
-    },
-    { name: "/init", summary: "scaffold a project CRUXY.md and load it" },
-    { name: "/reload", summary: "re-read project instructions (CRUXY.md)" },
-    { name: "/status", summary: "show what this session is set up to do" },
-    {
-        name: "/diff",
-        summary: "show uncommitted changes in the workspace",
-        args: "[ref]",
-    },
-    {
-        name: "/export",
-        summary: "write this conversation to a markdown file",
-        args: "[path]",
-    },
-    {
-        name: "/plan",
-        summary: "toggle plan mode (propose a plan before executing)",
-    },
-    {
-        name: "/mode",
-        summary: "show or set the session mode",
-        args: "[manual | auto-approve | plan | full-auto]",
-    },
-    {
-        name: "/model",
-        summary: "show or set the model for this session",
-        args: "[auto | kavi | vaani | mira]",
-    },
-    {
-        name: "/context",
-        summary: "show where the context budget is going, and what compaction would drop",
-    },
-    {
-        name: "/usage",
-        summary: "show token usage, weighted tokens and cost",
-        args: "[all | last <n>]",
-    },
-    { name: "/jobs", summary: "list background jobs and their status" },
-    { name: "/logs", summary: "show a background job's log", args: "<id>" },
-    { name: "/cancel", summary: "cancel a background job", args: "<id>" },
-    {
-        name: "/add-root",
-        summary: "declare another workspace root",
-        args: "<name> <path>",
-    },
-    { name: "/exit", summary: "leave cruxy" },
-    { name: "/quit", summary: "leave cruxy" },
-];
+export { COMMAND_CATALOG };
 /**
  * Line cap for `/diff`. Generous compared to a preview block — this is a command
  * whose entire purpose is the diff, not a block competing for space with a
@@ -163,7 +105,15 @@ export async function dispatchCommand(input, ctx) {
         return { kind: "handled" };
     }
     if (trimmed === "/diff" || trimmed.startsWith("/diff ")) {
-        handleDiff(trimmed, ctx);
+        await handleDiff(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/undo-last") {
+        await handleUndoLast(ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/redact") {
+        handleRedact(ctx);
         return { kind: "handled" };
     }
     if (trimmed === "/export" || trimmed.startsWith("/export ")) {
@@ -178,6 +128,10 @@ export async function dispatchCommand(input, ctx) {
         handleUsage(trimmed, ctx);
         return { kind: "handled" };
     }
+    if (trimmed === "/budget" || trimmed.startsWith("/budget ")) {
+        handleBudget(trimmed, ctx);
+        return { kind: "handled" };
+    }
     if (trimmed === "/jobs") {
         handleJobsList(ctx);
         return { kind: "handled" };
@@ -391,14 +345,29 @@ function handleStatus(ctx) {
  * changes are that answer. `/diff <ref>` widens it to any commit-ish, which is
  * how you see a whole branch's worth.
  *
+ * `/diff --since [id]` (P10 track 2) narrows it the other way — to one RUN, which
+ * is the thing `HEAD` cannot express. `HEAD` answers "since my last commit", and
+ * mid-session that is usually several runs ago and includes work the user did by
+ * hand. A checkpoint is the only marker that means "before the agent started
+ * this". Resolution is `resolveCheckpointDiff`; from there this function is
+ * unchanged — the same `git diff` against the same renderer.
+ *
  * EVERY ROOT, not just the primary (C.26). Writes fan every declared root when
  * checkpoints are on, so a diff that showed only the primary would under-report
  * exactly the multi-root case that is hardest to keep track of by hand.
  */
-function handleDiff(input, ctx) {
+async function handleDiff(input, ctx) {
+    const arg = input.slice("/diff".length).trim();
+    if (arg === "--since" || arg.startsWith("--since ")) {
+        await diffSinceCheckpoint(arg.slice("--since".length).trim(), ctx);
+        return;
+    }
+    diffAgainstRef(arg || "HEAD", ctx);
+}
+/** `/diff [ref]` — every root's working tree against one commit-ish. */
+function diffAgainstRef(ref, ctx) {
     const { out, session } = ctx;
     const t = out.theme;
-    const ref = input.slice("/diff".length).trim() || "HEAD";
     const roots = session.toolContext.workspace.roots();
     let any = false;
     for (const root of roots) {
@@ -428,6 +397,172 @@ function handleDiff(input, ctx) {
         out.print(t.muted(`(working tree vs ${ref} — commits, pushes and PRs are not shown)`));
     }
 }
+/**
+ * `/diff --since [id]` — every root the checkpoint (or run) covers, against the
+ * tree that checkpoint captured. A bare `--since` means the most recent run,
+ * matching `/undo-last`'s default: the two commands answer "what would this undo"
+ * and "undo it", and they must not disagree about which run they mean.
+ *
+ * A root whose checkpoint has no tree-ish (a shadow-store snapshot, or objects
+ * git has since pruned) says so IN PLACE and the other roots still render. This
+ * command changes nothing, so there is no reason for one gap to withhold the
+ * rest — the opposite of the validate-all rule rollback is held to.
+ */
+async function diffSinceCheckpoint(id, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const toolCtx = session.toolContext;
+    let scope;
+    try {
+        scope = await resolveCheckpointDiff(toolCtx.workspace.roots().map((r) => ({
+            name: r.name,
+            absPath: r.absPath,
+            primary: r.primary,
+        })), id === "" ? undefined : id, toolCtx.config);
+    }
+    catch (err) {
+        printCommandError(out, err);
+        return;
+    }
+    if (scope.kind === "none") {
+        out.print(t.muted(toolCtx.config.checkpoint.enabled
+            ? "no checkpoints yet — nothing has been recorded to diff against"
+            : "checkpoints are disabled (checkpoint.enabled = false), so there is nothing to diff against"));
+        return;
+    }
+    if (scope.kind === "not-found") {
+        // Never a nearest match: silently diffing against a checkpoint the user did
+        // not name is the same substitution `/model` refuses to make.
+        out.print(t.muted(`no run or checkpoint named "${scope.id}" — see \`cruxy rollback\` for the ids`));
+        return;
+    }
+    const label = scope.kind === "run"
+        ? `run ${scope.runId}`
+        : `checkpoint ${scope.targets[0].checkpointId}`;
+    const multi = scope.targets.length > 1;
+    let any = false;
+    for (const target of scope.targets) {
+        if (multi)
+            out.print(t.strong(target.rootName));
+        if (target.unavailable !== undefined) {
+            out.print(out.fit(t.muted(`  ${target.unavailable}`)));
+            continue;
+        }
+        const diff = diffAgainst(target.rootPath, target.treeish);
+        if (diff.trim() === "") {
+            out.print(t.muted(`  no changes since ${target.checkpointId}`));
+            continue;
+        }
+        any = true;
+        for (const line of renderUnifiedDiff(diff, t, {
+            maxLines: DIFF_MAX_LINES,
+        })) {
+            out.print(out.fit(line));
+        }
+    }
+    if (any) {
+        out.print(t.muted(`(working tree vs ${label} — commits, pushes and PRs are not shown)`));
+    }
+}
+/**
+ * `/undo-last` (P10 track 1) — roll back the most recent run's file changes
+ * without leaving the session.
+ *
+ * NOT a new capability, and deliberately not a new mechanism: `cruxy rollback`
+ * has done exactly this since C.32, and everything it needs — the set manifests,
+ * validate-all, the combined preview, the sequential apply — is on disk and
+ * root-relative rather than process-relative. What was missing was reachability.
+ * Undoing a run meant leaving the session that had just produced it, which is
+ * both the moment you most want to undo and the moment leaving costs most.
+ *
+ * So this is `rollbackLatestRun` with the newest set already chosen. THE GATE IS
+ * THE CONFIRMATION: the operation goes through the same U.3 destructive-tier
+ * approval as every other rollback, showing the same per-root preview, and there
+ * is no `--force`, no grant, and no picker. A user who typed `/undo-last`
+ * meaning something else sees exactly what it would do and says no.
+ *
+ * Two things it does not touch, both said out loud rather than assumed:
+ * the conversation (the transcript still describes changes that are no longer on
+ * disk, so the next turn is told), and anything that already left the working
+ * tree (commits, pushes, PRs — the shared caveat).
+ */
+async function handleUndoLast(ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const toolCtx = session.toolContext;
+    // Refused before anything is computed, for the same reason `cruxy rollback`
+    // refuses: this is a deliberate, interactive act and the gate cannot ask.
+    if (!ctx.tty) {
+        out.print(t.muted("/undo-last needs a terminal — it must ask before it restores"));
+        return;
+    }
+    if (!toolCtx.config.checkpoint.enabled) {
+        // Say which knob, because the answer is otherwise indistinguishable from
+        // "this run changed nothing".
+        out.print(t.muted("checkpoints are disabled — nothing was recorded to roll back to " +
+            "(enable with `cruxy config set checkpoint.enabled true`)"));
+        return;
+    }
+    try {
+        const outcome = await rollbackLatestRun(toolCtx.workspace.primary().absPath, {
+            config: toolCtx.config,
+            requestApproval: (action) => toolCtx.requestApproval(action),
+            interactive: ctx.tty,
+            report: { print: (line) => out.print(out.fit(line)), theme: t },
+        });
+        if (outcome === null) {
+            out.print(t.muted("nothing to undo — no run has changed a file yet"));
+            return;
+        }
+        if (outcome.kind === "applied") {
+            // The one thing the out-of-session command never has to say. History is
+            // not rewound with the files, so the model's next turn would otherwise
+            // reason from a working tree that no longer exists.
+            out.print(t.muted("the conversation still describes those changes — say so in your next " +
+                "message, or /clear if you are starting over"));
+        }
+    }
+    catch (err) {
+        // Includes the two coded set errors (INCOMPLETE before anything is applied,
+        // PARTIAL after a stop-on-failure): both name exactly what was restored and
+        // what was not, and neither may take the shell down.
+        printCommandError(out, err);
+    }
+}
+/**
+ * `/redact` (P10 track 5) — mask secrets in this conversation so the model stops
+ * seeing them.
+ *
+ * THE ONE THING IT PROMISES AND THE ONE THING IT DOES NOT, both said on screen
+ * every time. It removes the matched text from the live history and from every
+ * future replay of this session. It does NOT remove it from the `.jsonl` on
+ * disk: that file is append-only, which is what makes a crash mid-turn cost a
+ * torn last line rather than the whole conversation, and a redaction is
+ * therefore a new event that changes how earlier lines are read. A user who
+ * needs the bytes gone needs the session file deleted, and is told so rather
+ * than left with a command that sounds like it did more than it did.
+ *
+ * The detector is `memory/secrets.ts` — the SAME denylist that refuses to write
+ * a secret into memory. Two lists would mean two answers about what counts, and
+ * the weaker one would be the one someone discovered the hard way. It is a
+ * guardrail against accidental exposure, not a guarantee, and the message says
+ * that too: a value with no recognisable shape is not found by either.
+ */
+function handleRedact(ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const { kinds, count } = session.redact();
+    if (count === 0) {
+        out.print(t.muted("no recognisable secrets in this conversation"));
+        // Said on the empty result too — "nothing found" must not be heard as
+        // "nothing is there".
+        out.print(out.fit(t.muted("  (a denylist of known shapes, not a guarantee — a value with no telltale form is not matched)")));
+        return;
+    }
+    out.print(t.muted(`masked ${count} value${count === 1 ? "" : "s"} (${kinds.join(", ")}) — the model no longer sees ${count === 1 ? "it" : "them"}`));
+    out.print(out.fit(t.warning("the session file still holds the original text: this appends a redaction, it does not rewrite history")));
+    out.print(out.fit(t.muted("  rotate anything that leaked, and delete the session file if the bytes must be gone")));
+}
 /**
  * `/export` (P6 track 4) — write this conversation to a Markdown file.
  *
@@ -563,6 +698,117 @@ function handleUsage(input, ctx) {
             out.print(out.fit(row));
     }
 }
+/**
+ * `/budget` (P10 track 3) — read or set this session's cap, in weighted tokens.
+ *
+ * WEIGHTED, not raw, because that is the only unit anything enforces: the
+ * gateway meters `(billable_input + output) × multiplier`, so 100k tokens on
+ * mira and 100k on kavi differ by 3.8× in what is actually deducted. `/usage`
+ * already reports in this unit and the rail's limits panel already draws the
+ * server's windows in it; a third unit here would be a third answer.
+ *
+ * IT IS THE SAME OBJECT that bounds parallel fan-out (cli#212). This command is
+ * the readable face of an admission check that would otherwise be invisible —
+ * which matters, because the check can narrow a fan-out from five children to
+ * one, and a user who cannot see the ceiling cannot understand why.
+ *
+ * THREE NUMBERS, THREE SOURCES, deliberately not merged into one bar:
+ *   • what this session has drawn — local, exact, and only this process;
+ *   • the cap the user set, if any — local, and clearable;
+ *   • the server's binding window — inclusive of every other surface on the
+ *     account, and the only place headroom may honestly come from.
+ * A session that has spent 40k of its own 200k may still be blocked by a burst
+ * window three other devices drained, and a single merged figure could not say
+ * so.
+ *
+ * SESSION STATE, never written to config — the rule `/model` and `/mode` follow,
+ * for the strongest version of the reason: a cap silently re-applied from a file
+ * would eventually refuse a turn with nothing on screen explaining why.
+ */
+function handleBudget(input, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const budget = session.budget;
+    const arg = input.slice("/budget".length).trim().toLowerCase();
+    if (!budget) {
+        // Not a failure to report later: a session with no budget wired has none to
+        // read either, and saying which is more useful than an empty report.
+        out.print(t.muted("this session has no budget to set"));
+        return;
+    }
+    if (arg !== "") {
+        if (arg === "off" || arg === "none" || arg === "0") {
+            budget.setLimit(null);
+            out.print(t.muted("budget cleared — this session has no local cap"));
+            // The server's window is untouched by clearing a local cap, and a user who
+            // has just removed one limit should not be left thinking they removed all.
+            printServerHeadroom(out, budget);
+            return;
+        }
+        const wanted = parseWeighted(arg);
+        if (wanted === null) {
+            out.print(t.muted("usage: /budget [<weighted tokens> | off]  (e.g. `/budget 2M`, `/budget 500k`)"));
+            return;
+        }
+        budget.setLimit(wanted);
+        // Report against what is ALREADY spent, because a cap set mid-session can be
+        // below it — and a budget that is already used up the moment it is set must
+        // say so now rather than at the next turn.
+        const left = budget.remaining() ?? 0;
+        out.print(t.muted(`budget: ${compactTokens(wanted)} weighted tokens for this session — ` +
+            `${compactTokens(budget.spent)} already drawn, ${compactTokens(left)} left`));
+        if (left === 0) {
+            out.print(t.warning("that is at or below what this session has already spent"));
+        }
+        printServerHeadroom(out, budget);
+        return;
+    }
+    // No argument: report.
+    const limit = budget.limit;
+    out.print(t.muted(`this session has drawn ${compactTokens(budget.spent)} weighted tokens`));
+    if (budget.unweighable > 0) {
+        // Never folded into the total as zero — the same discipline `/usage` holds
+        // to. An unweighable request is one this build cannot price, not a free one.
+        out.print(t.muted(`  (${budget.unweighable} request${budget.unweighable === 1 ? "" : "s"} could not be weighed and are not in that figure)`));
+    }
+    out.print(t.muted(limit === null
+        ? "no session cap set — `/budget <n>` sets one"
+        : `session cap ${compactTokens(limit)}, ${compactTokens(budget.remaining() ?? 0)} left`));
+    printServerHeadroom(out, budget);
+}
+/**
+ * The server's half of the denominator. Said in its own sentence rather than
+ * merged with the local figures, and said even when unreadable — "we could not
+ * read your ceiling" must never be silence, which reads as "you have none".
+ */
+function printServerHeadroom(out, budget) {
+    const t = out.theme;
+    const headroom = budget.serverHeadroom();
+    if (headroom.kind === "window") {
+        out.print(out.fit(t.muted(`your ${headroom.name === "burst" ? "12h burst" : "monthly"} window: ` +
+            `${compactTokens(headroom.remaining)} of ${compactTokens(headroom.cap)} left ` +
+            `(shared with every other surface on your account)`)));
+        return;
+    }
+    if (headroom.kind === "uncapped") {
+        out.print(t.muted("your account has no weighted-pool ceiling"));
+        return;
+    }
+    out.print(out.fit(t.muted(`server headroom unknown — ${headroom.why}`)));
+}
+/**
+ * `500000`, `500k`, `2M` → weighted tokens. Rejects everything else rather than
+ * guessing: a mistyped budget that silently becomes a very small or very large
+ * number is a command that refuses turns, or fails to.
+ */
+function parseWeighted(arg) {
+    const match = /^(\d+(?:\.\d+)?)([km])?$/.exec(arg);
+    if (!match)
+        return null;
+    const scale = match[2] === "m" ? 1_000_000 : match[2] === "k" ? 1_000 : 1;
+    const value = Number(match[1]) * scale;
+    return Number.isFinite(value) && value > 0 ? Math.round(value) : null;
+}
 /** Render the background-job list (`/jobs`). */
 function handleJobsList(ctx) {
     const { out, session } = ctx;

package/dist/cli/session-factory.js

@@ -3,6 +3,7 @@ import { loadProjectInstructions } from "../config/index.js";
 import { logger } from "../utils/logger.js";
 import { getGitInfo } from "../utils/git.js";
 import { ApprovalMutex, ApprovalService, InteractivePolicy, SessionAllowlist, defaultPromptIO, serializeGate, } from "../approval/index.js";
+import { SessionBudget } from "../budget/index.js";
 import { withCheckpointGate } from "../checkpoint/index.js";
 // Re-exported for back-compat: the checkpoint hook moved to the checkpoint
 // package (so the subagent orchestrator and C.28 jobs can compose it without
@@ -362,6 +363,16 @@ opts = {}) {
     // each. The ONE pending-approval queue background jobs produce onto is created
     // here too, so foreground servicing and job production share it.
     const executionSemaphore = new Semaphore(config.subagent.maxConcurrency);
+    // The ONE weighted-token budget for the whole session (P10 track 3 / cli#212).
+    // `/budget` reads and sets it; `Session` narrows each turn's token guard by it;
+    // the orchestrator refuses to dispatch a fan-out it cannot cover. Three
+    // consumers, one object — a session cap and a fan-out bound that could disagree
+    // would be the failure this exists to prevent. Its server denominator is
+    // attached later (see `attachLimits`), because the limits cache does not exist
+    // yet at this point in the wiring.
+    const sessionBudget = new SessionBudget({
+        maxTokensPerTurn: config.agent.maxTokensPerTurn,
+    });
     const approvalQueue = new ApprovalQueue();
     const gate = (approval) => serializeGate(withCheckpointGate(
     // Outside `resumeLineAfterApproval`, so the live region is restored
@@ -385,6 +396,7 @@ opts = {}) {
         sandbox,
         checkpointsActive,
         executionSemaphore,
+        budget: sessionBudget,
         // A child gets the parent's MODE but not its grants (P5 track 3). The two
         // are different kinds of thing: a scoped session grant is consent to one
         // command in one root, and widening it to a child would be authority the
@@ -508,6 +520,7 @@ opts = {}) {
         // note on `SessionArgs.model`.
         ...(sessionModel ? { model: sessionModel } : {}),
         onRunUsage,
+        budget: sessionBudget,
         jobs: jobManager,
         recorder: opts.recorder,
         restore: opts.restore,

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

@@ -303,6 +303,28 @@ export function budgetExhausted(underlying) {
             : undefined,
     });
 }
+/**
+ * The session's own `/budget` refused the turn (P10 track 3).
+ *
+ * Every next step is a lever the user has RIGHT HERE, which is the whole reason
+ * this is not {@link budgetExhausted}: nothing here involves waiting for a window
+ * to refill or changing a plan, because the ceiling is one the user set on this
+ * process a moment ago. `reason` comes from `SessionBudget` and already names
+ * which denominator bound — the session cap or the server window — so it is
+ * carried verbatim rather than re-phrased.
+ */
+export function sessionBudgetExhausted(reason) {
+    return new CruxyError({
+        code: ErrorCode.SessionBudgetExhausted,
+        title: "this session's budget is used up",
+        cause: reason,
+        nextSteps: [
+            "raise it: `/budget <weighted tokens>`",
+            "or clear it: `/budget off`",
+            "`/usage` shows what this session has actually drawn",
+        ],
+    });
+}
 /** Milliseconds until an ISO instant, or `undefined` if it is absent/unparseable. */
 function msUntil(iso) {
     const at = Date.parse(iso);
@@ -635,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 },
     });
@@ -656,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/errors/types.js

@@ -47,6 +47,18 @@ export const ErrorCode = {
     ApiRateLimit: "CRUXY_E_API_RATE_LIMIT",
     ApiOverloaded: "CRUXY_E_API_OVERLOADED",
     BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED",
+    /**
+     * The SESSION's own `/budget` is used up (P10 track 3) — a cap this user set
+     * on this process, not the gateway refusing anything.
+     *
+     * A DISTINCT CODE from {@link BudgetExhausted} because the two need opposite
+     * advice and have opposite blast radius. The gateway's exhaustion is a shared
+     * sliding window that refills by trickle and cannot be raised from here; this
+     * one is a number the user typed thirty seconds ago and can change with
+     * `/budget`. Collapsing them would tell a user to wait twelve hours for a
+     * ceiling they could lift immediately.
+     */
+    SessionBudgetExhausted: "CRUXY_E_SESSION_BUDGET_EXHAUSTED",
     ForgeApi: "CRUXY_E_FORGE_API",
     // filesystem (exit 7)
     FileNotFound: "CRUXY_E_FILE_NOT_FOUND",
@@ -280,6 +292,9 @@ const EXIT_CODES = {
     [ErrorCode.ApiRateLimit]: 6,
     [ErrorCode.ApiOverloaded]: 6,
     [ErrorCode.BudgetExhausted]: 6,
+    // A cap this invocation set on itself is usage, not an API failure — the same
+    // exit class as any other "you asked for something out of bounds".
+    [ErrorCode.SessionBudgetExhausted]: 2,
     [ErrorCode.ForgeApi]: 6,
     [ErrorCode.FileNotFound]: 7,
     [ErrorCode.PermissionDenied]: 7,