@cruxy/cli 1.4.0 → 1.6.0

package/dist/cli/session-commands.js

@@ -1,14 +1,19 @@
 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";
+import { readDiskCapacitySync } from "../utils/disk.js";
 import { getGitInfo } from "../utils/git.js";
 import { currentBranch, diffAgainst, hasChanges } from "../vcs/git.js";
 import { MODEL_CHOICES, describeModelChoice, parseModelChoice, } from "../routing/index.js";
@@ -17,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
@@ -162,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 ")) {
@@ -177,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" };
@@ -373,7 +328,11 @@ function handleStatus(ctx) {
     //
     // Everything else comes from the shared builder, so this and the Overview
     // view cannot drift: they differ in exactly this argument and nowhere else.
-    const status = buildSessionStatus(session, (absPath) => getGitInfo(absPath));
+    const status = buildSessionStatus(session, (absPath) => getGitInfo(absPath), undefined, 
+    // Synchronous here for the same reason git is: the user asked. This one is
+    // a single syscall rather than two subprocesses, so it costs microseconds
+    // on any disk that is answering at all.
+    (path) => readDiskCapacitySync(path));
     for (const line of sessionStatusLines(status, out.theme)) {
         out.print(out.fit(line));
     }
@@ -386,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) {
@@ -423,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.
  *
@@ -558,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/errors/constructors.js

@@ -1,4 +1,4 @@
-import { ApiError, AuthError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { ApiError, AuthError, BudgetExhaustedError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
 import { scrubModelNames } from "../brand/index.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
@@ -223,15 +223,115 @@ export function apiOverloaded(underlying) {
         underlying,
     });
 }
+/**
+ * A wait, in the largest unit that stays honest: "4h", "12m", "18d".
+ *
+ * `apiRateLimit` renders seconds because a rate-limit wait IS seconds. A budget
+ * window is hours or days, and "~14400s" is a number a human has to do
+ * arithmetic on at the moment they are least inclined to.
+ */
+function humanWait(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${Math.max(1, minutes)}m`;
+    const hours = Math.round(minutes / 60);
+    return hours < 48 ? `${hours}h` : `${Math.round(hours / 24)}d`;
+}
+/**
+ * The weighted-pool gate refused the request (429 `budget_exhausted`).
+ *
+ * THIS IS THE POOL, AND ONLY THE POOL. The gateway spends separate codes on the
+ * things a user actually can pay their way out of — `credits_exhausted`,
+ * `key_spend_cap_exceeded`, `workspace_spend_cap_exceeded` — and none of them
+ * arrive here. So the advice this used to give ("top up or raise your budget,
+ * then retry") was wrong in both halves: there is nothing to top up on a
+ * subscription pool, and "retry" against a window that refills on a clock is an
+ * instruction to hammer a gate that will refuse again.
+ *
+ * That wording was harmless while it was unreachable from this CLI. cruxy-ai/api#174
+ * makes a CLI login mint a subscription credential, so it is now the message a
+ * blocked user actually reads — see cruxy-ai/cli#212.
+ *
+ * The error already carries everything needed to say something true, and all of
+ * it used to be discarded:
+ *
+ *  - `miraAvailable` — mira is exempt from the pool kill, so on most denials
+ *    there IS a way to keep working. It goes first: it is the only step that
+ *    unblocks someone now rather than telling them when to come back.
+ *  - `window` — "monthly" and "burst" are different waits (a calendar rollover
+ *    versus a trailing sum sliding back under its cap), so the wait is named.
+ *  - `resetAt` / `retryAfterMs` — WHEN, so the wait is a time rather than a
+ *    vague "later". The window length is deliberately not asserted here; the
+ *    server sends the recovery instant and this reports that.
+ */
 export function budgetExhausted(underlying) {
+    const err = underlying instanceof BudgetExhaustedError ? underlying : undefined;
+    const waitMs = err?.retryAfterMs ??
+        (err?.resetAt !== undefined ? msUntil(err.resetAt) : undefined);
+    const nextSteps = [];
+    // Mira stays available on an exhausted pool (it is the always-available
+    // floor), so when the gateway says so, the first step is the one that gets
+    // the user working again instead of waiting.
+    if (err?.miraAvailable) {
+        nextSteps.push("switch to the mira tier, which stays available: `/model mira`");
+    }
+    const window = err?.window === "burst" ? "burst" : err?.window;
+    const windowPhrase = window ? `your ${window} budget window` : "your budget";
+    nextSteps.push(waitMs !== undefined && waitMs > 0
+        ? `wait ~${humanWait(waitMs)} — ${windowPhrase} recovers then`
+        : `wait for ${windowPhrase} to recover`);
+    // Only where it is true. A subscription pool is not something a user can add
+    // to; a plan change is the only lever, and it is a different action from
+    // "top up" with a different place to do it.
+    nextSteps.push("or move to a higher plan for a larger allowance");
     return new CruxyError({
         code: ErrorCode.BudgetExhausted,
-        title: "your Cruxy budget is exhausted",
+        title: window
+            ? `your ${window} Cruxy budget is exhausted`
+            : "your Cruxy budget is exhausted",
         cause: scrubbedMessageOf(underlying),
-        nextSteps: ["top up or raise your budget, then retry"],
+        nextSteps,
         underlying,
+        meta: err
+            ? {
+                ...(err.window !== undefined ? { window: err.window } : {}),
+                ...(err.resetAt !== undefined ? { resetAt: err.resetAt } : {}),
+                ...(err.miraAvailable !== undefined
+                    ? { miraAvailable: err.miraAvailable }
+                    : {}),
+            }
+            : 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);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, at - Date.now());
+}
 // ── filesystem (exit 7) ───────────────────────────────────────────────────────
 export function fileNotFound(path, underlying) {
     return new CruxyError({
@@ -1309,12 +1409,14 @@ export function classifyProviderError(underlying) {
         return apiOverloaded(underlying);
     if (underlying instanceof NetworkError)
         return gatewayUnreachable(underlying);
-    if (underlying instanceof ApiError) {
-        // BudgetExhaustedError isn't exported by the SDK; match by name.
-        if (underlying.name === "BudgetExhaustedError") {
-            return budgetExhausted(underlying);
-        }
-        return apiError(underlying);
+    // Before the `ApiError` base it extends, like every other subclass here. The
+    // name check this replaces was a workaround for an export that exists — the
+    // SDK's barrel has always re-exported the class — and it silently stopped
+    // matching anything the moment a bundler minified the constructor name.
+    if (underlying instanceof BudgetExhaustedError) {
+        return budgetExhausted(underlying);
     }
+    if (underlying instanceof ApiError)
+        return apiError(underlying);
     return null;
 }

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,