@cruxy/cli 1.5.0 → 1.6.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/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);

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,

package/dist/hooks/config.js

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { isReservedSlash } from "../cli/command-catalog.js";
 import { globalDir } from "../config/paths.js";
 import { COMMANDS_DIR_NAME, GLOBAL_DIR_NAME, HOOKS_FILE_NAME, } from "../constants.js";
 import { defaultBlocking, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, SlashFrontmatterSchema, } from "./types.js";
@@ -143,6 +144,23 @@ async function scanCommandsDir(source, dir, out, errors) {
             });
             continue;
         }
+        // A reserved name is refused HERE, at load, and excluded from the catalog
+        // (P10 track 0). Both halves matter. Loading it and letting it lose the
+        // race later is what shipped before: `commands/status.md` parsed, appeared
+        // in `cruxy hooks list` and in the palette, and could not run, because the
+        // shells dispatch `/status` themselves several branches before the custom
+        // catalogue is consulted. Nothing said so at load and nothing said so at
+        // use. Keeping it in the catalog with a warning would fix half of that and
+        // leave the palette advertising a command that does nothing.
+        if (isReservedSlash(name)) {
+            errors.push({
+                source,
+                file,
+                name,
+                message: `"/${name}" is a built-in command and cannot be overridden — rename this file`,
+            });
+            continue;
+        }
         let text;
         try {
             text = await fs.readFile(file, "utf8");

package/dist/hooks/index.js

@@ -2,6 +2,6 @@ export { HOOK_EVENTS, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, HooksFileSchema, S
 export { defaultHookSources, loadHookCatalog, } from "./config.js";
 export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPath, } from "./trust.js";
 export { HookRunner, } from "./runner.js";
-export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, } from "./slash.js";
+export { expandTemplate, resolveSlash } from "./slash.js";
 export { buildHooksService, } from "./service.js";
 export { buildHooksRouter, } from "./router.js";

package/dist/hooks/router.js

@@ -79,7 +79,7 @@ export async function buildHooksRouter(opts) {
     for (const root of opts.workspace.roots()) {
         const catalog = await loadCatalog(root);
         for (const err of catalog.errors) {
-            opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}" in ${root.name}: ${err.message}`);
+            opts.logger.warn(`ignoring ${err.source} hook/command "${err.name}" in ${root.name}: ${err.message}`);
         }
         // Each root's runner owns ONLY its project hooks. User hooks are global —
         // loaded once (from the primary, whose `sources.user` is identical for every

package/dist/hooks/service.js

@@ -5,15 +5,15 @@ import { defaultHookSources, loadHookCatalog, } from "./config.js";
 import { HookRunner } from "./runner.js";
 import { fileTrustStore } from "./trust.js";
 /**
- * Load the catalog and assemble the {@link HooksService}. Malformed definitions
- * are surfaced (never eval'd, never silently dropped) through the logger; the
- * valid ones proceed.
+ * Load the catalog and assemble the {@link HooksService}. Rejected definitions
+ * — malformed, or a command name the shells reserve — are surfaced (never
+ * eval'd, never silently dropped) through the logger; the valid ones proceed.
  */
 export async function buildHooksService(opts) {
     const sources = opts.sources ?? defaultHookSources(opts.cwd);
     const catalog = await loadHookCatalog(sources);
     for (const err of catalog.errors) {
-        opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}": ${err.message}`);
+        opts.logger.warn(`ignoring ${err.source} hook/command "${err.name}": ${err.message}`);
     }
     const trust = opts.trust ?? fileTrustStore();
     const runner = new HookRunner({

package/dist/hooks/slash.js

@@ -1,29 +1,13 @@
+import { isReservedSlash } from "../cli/command-catalog.js";
 /**
- * Custom slash-command resolution (C.19). Builtins are reserved and always win —
- * a custom command can never shadow `/help`, `/exit`, etc. A resolved custom
- * command is either a `prompt` (expanded to safe text fed to the agent) or a
- * `shell` binding (executed through the SAME gate + sandbox as everything else,
- * by the caller). Nothing here executes anything; it only resolves + expands.
- */
-/** The builtin slash commands (C.13) — reserved, not overridable. */
-export const BUILTIN_SLASH_COMMANDS = [
-    "help",
-    "clear",
-    "compact",
-    "reload",
-    "plan",
-    "exit",
-    "quit",
-];
-const BUILTINS = new Set(BUILTIN_SLASH_COMMANDS);
-/** Is `name` (no leading slash) a reserved builtin? */
-export function isBuiltinSlash(name) {
-    return BUILTINS.has(name);
-}
-/**
- * Resolve one input line. Non-slash input and unknown names → `none`. Builtins
- * short-circuit to `builtin` BEFORE the custom catalog is consulted, so a custom
- * command named after a builtin is inert (surfaced separately at load time).
+ * Resolve one input line. Non-slash input and unknown names → `none`. Reserved
+ * names short-circuit to `builtin` BEFORE the custom catalog is consulted.
+ *
+ * This is now belt-and-braces rather than the only guard: the loader refuses a
+ * command file whose name is reserved, so the colliding spec should never reach
+ * this catalogue at all. It stays because a caller may assemble a spec list by
+ * some other route, and the failure mode this prevents — a project-authored
+ * `shell` command answering to `/clear` — is not one to leave to a single check.
  */
 export function resolveSlash(line, commands) {
     const trimmed = line.trim();
@@ -34,7 +18,7 @@ export function resolveSlash(line, commands) {
     const args = space === -1 ? "" : trimmed.slice(space + 1).trim();
     if (name === "")
         return { kind: "none" };
-    if (isBuiltinSlash(name))
+    if (isReservedSlash(name))
         return { kind: "builtin", name };
     const spec = commands.find((c) => c.name === name);
     if (!spec)