@cruxy/cli 1.2.0 → 1.3.0

package/dist/cli/session-commands.js

@@ -0,0 +1,755 @@
+import { MODE_LABELS, SESSION_MODES, modeDescription, modeFromFlags, parseMode, } from "../agent/index.js";
+import { existsSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { contextReport, readContext } from "../agent/context.js";
+import { scaffoldProjectInstructions } from "../config/index.js";
+import { resolveSlash } from "../hooks/index.js";
+import { contextReportLines } from "../render/context-view.js";
+import { renderUnifiedDiff } from "../render/index.js";
+import { sessionStatusLines } from "../render/status-view.js";
+import { defaultExportName, exportMarkdown } from "../session/index.js";
+import { getGitInfo } from "../utils/git.js";
+import { currentBranch, diffAgainst, hasChanges } from "../vcs/git.js";
+import { MODEL_CHOICES, describeModelChoice, parseModelChoice, } from "../routing/index.js";
+import { loadUsage, runCountLabel, selectRuns, usageReport, } from "../usage/index.js";
+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.
+ */
+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" },
+];
+/**
+ * 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
+ * conversation — but still bounded, and the marker says how many were dropped.
+ */
+const DIFF_MAX_LINES = 400;
+/** Just the names — the Tab-completion candidate set. */
+export const SHARED_COMMANDS = COMMAND_CATALOG.map((c) => c.name);
+/** Render one catalogue entry as a `/help` row, aligned on a fixed gutter. */
+export function helpRow(command, gutter = 18) {
+    const left = command.args ? `${command.name} ${command.args}` : command.name;
+    return `  ${left.padEnd(gutter)} ${command.summary}`;
+}
+/** The shared half of `/help`, minus each shell's own additions. */
+export const SHARED_HELP = COMMAND_CATALOG.map((c) => helpRow(c));
+/**
+ * Dispatch one submitted line.
+ *
+ * Returns `{kind:"turn"}` for anything this does not own — including an unknown
+ * `/…` string, which falls through to the model exactly as it always has rather
+ * than being rejected. A user who types a command that does not exist gets an
+ * answer, not a scolding.
+ */
+export async function dispatchCommand(input, ctx) {
+    const trimmed = input.trim();
+    const { session, out } = ctx;
+    const t = out.theme;
+    if (trimmed === "")
+        return { kind: "handled" };
+    if (trimmed === "/exit" || trimmed === "/quit")
+        return { kind: "exit" };
+    if (trimmed === "/clear") {
+        session.clear();
+        out.print(t.muted("history cleared"));
+        return { kind: "handled" };
+    }
+    if (trimmed === "/compact") {
+        try {
+            const n = await session.compact();
+            out.print(t.muted(n ? `compacted ${n} older messages` : "nothing to compact yet"));
+        }
+        catch (err) {
+            printCommandError(out, err);
+        }
+        return { kind: "handled" };
+    }
+    if (trimmed === "/reload") {
+        const loaded = session.reloadProjectInstructions();
+        out.print(t.muted(loaded
+            ? "reloaded project instructions (CRUXY.md)"
+            : "no project instructions found"));
+        return { kind: "handled" };
+    }
+    if (trimmed === "/plan") {
+        // Toggling plan is a MOVE within the mode ring, not a boolean flip: it
+        // preserves whatever the auto-approve half was, so leaving plan mode from
+        // `full-auto` lands on `auto-approve` rather than silently re-arming every
+        // prompt the user had turned off.
+        announceMode(out, session.setMode(modeFromFlags(!session.getPlanMode(), session.getAutoApprove())));
+        return { kind: "handled" };
+    }
+    if (trimmed === "/mode" || trimmed.startsWith("/mode ")) {
+        handleMode(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/model" || trimmed.startsWith("/model ")) {
+        await handleModel(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/init") {
+        handleInit(ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/status") {
+        handleStatus(ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/diff" || trimmed.startsWith("/diff ")) {
+        handleDiff(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/export" || trimmed.startsWith("/export ")) {
+        handleExport(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/context") {
+        handleContext(ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/usage" || trimmed.startsWith("/usage ")) {
+        handleUsage(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/jobs") {
+        handleJobsList(ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/logs" || trimmed.startsWith("/logs ")) {
+        handleJobLogs(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/cancel" || trimmed.startsWith("/cancel ")) {
+        await handleJobCancel(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    if (trimmed === "/add-root" || trimmed.startsWith("/add-root ")) {
+        await handleAddRoot(trimmed, ctx);
+        return { kind: "handled" };
+    }
+    // Custom slash commands (C.19) — consulted AFTER builtins, so a custom
+    // command can never shadow /help, /exit, etc. A `prompt` command expands to
+    // text fed to the agent (safe); a `shell` command runs through the SAME gate
+    // + sandbox as any command (never a bypass). Unknown "/…" input falls through
+    // to a normal turn, preserving prior behaviour.
+    const slash = resolveSlash(trimmed, ctx.slashCommands);
+    if (slash.kind === "prompt")
+        return { kind: "turn", text: slash.prompt };
+    if (slash.kind === "shell") {
+        await runSlashShell(slash.spec, ctx);
+        return { kind: "handled" };
+    }
+    return { kind: "turn", text: input };
+}
+/**
+ * Say what the mode now IS and what it will do.
+ *
+ * The description is not decoration. The objection to an auto-approve config
+ * flag was that it disarmed the gate with nothing on screen; a runtime mode
+ * announcing itself only as "auto-approve on" would reproduce that, slower.
+ */
+export function announceMode(out, mode) {
+    out.print(out.theme.muted(`mode: ${MODE_LABELS[mode]} — ${modeDescription(mode)}`));
+}
+/** `/mode` (show + list) and `/mode <name>` (set). */
+function handleMode(input, ctx) {
+    const { out, session } = ctx;
+    const arg = input.slice("/mode".length).trim();
+    if (arg === "") {
+        announceMode(out, session.getMode());
+        out.print(out.theme.muted(`  available: ${SESSION_MODES.join(" · ")}`));
+        return;
+    }
+    const want = parseMode(arg);
+    if (want === null) {
+        // Never a guess: a typo must not silently arm auto-approve.
+        out.print(out.theme.muted(`unknown mode "${arg}" — try ${SESSION_MODES.join(" | ")}`));
+        return;
+    }
+    const effective = session.setMode(want);
+    if (effective !== want) {
+        // Say so rather than reporting the request as if it took.
+        out.print(out.theme.muted(`plan mode is unavailable in this session — using ${effective}`));
+    }
+    announceMode(out, effective);
+}
+/**
+ * Say what the model now IS, and — once the choice has actually taken — what
+ * that means. `auto` gets its explanation every time rather than only on the
+ * first set: it is the one choice whose visible value will not match what runs,
+ * and a user who reads `model: auto` and then sees `mira` in the rail has to be
+ * able to connect the two without going looking.
+ */
+function announceModel(out, choice) {
+    out.print(out.theme.muted(`model: ${choice} — ${describeModelChoice(choice)}`));
+}
+/**
+ * `/model` (show, or pick), `/model <name>` (set).
+ *
+ * The choice is SESSION state, never written to config — the same rule P5
+ * track 3 applied to auto-approve, and for a weaker but real version of the
+ * same reason: a setting persisted from a file re-applies itself to every
+ * future session with nothing on screen saying it did. `config.model.model`
+ * stays the durable knob and the starting value.
+ */
+async function handleModel(input, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const model = session.model;
+    // No tiers to choose between. Said plainly rather than by offering a menu
+    // that could not take effect — and WITHOUT naming the configured upstream
+    // model, which is the one string the U.8 gag exists to keep off screen.
+    if (!model) {
+        out.print(t.muted("this session runs on a bring-your-own provider, which has no cruxy tiers to choose between — " +
+            "set `model.model` in your config to change it"));
+        return;
+    }
+    const arg = input.slice("/model".length).trim();
+    if (arg === "") {
+        // No argument: offer the picker when the shell can host one, else say what
+        // is set and what else is available. Both paths end at the same place — a
+        // user who cannot get a picker can still type `/model kavi`.
+        const picked = await ctx.pick?.(MODEL_CHOICES, {
+            title: "model",
+            toLabel: (choice) => `${choice} — ${describeModelChoice(choice)}`,
+            initialIndex: MODEL_CHOICES.indexOf(model.current()),
+        });
+        if (picked == null) {
+            announceModel(out, model.current());
+            for (const choice of MODEL_CHOICES) {
+                if (choice === model.current())
+                    continue;
+                out.print(out.fit(t.muted(`  ${choice} — ${describeModelChoice(choice)}`)));
+            }
+            return;
+        }
+        applyModel(ctx, picked);
+        return;
+    }
+    const want = parseModelChoice(arg);
+    if (want === null) {
+        // Never a nearest match: silently routing a user to a tier they did not
+        // name is exactly the substitution `ConfigRouter` refuses to make.
+        out.print(t.muted(`unknown model "${arg}" — try ${MODEL_CHOICES.join(" | ")}`));
+        return;
+    }
+    applyModel(ctx, want);
+}
+/** Adopt a picked choice and report it — including the case where nothing moved. */
+function applyModel(ctx, choice) {
+    const { out, session } = ctx;
+    const model = session.model;
+    if (!model.set(choice)) {
+        out.print(out.theme.muted(`model is already ${choice}`));
+        return;
+    }
+    announceModel(out, choice);
+    // A configured routing table is quietly bypassed by an explicit pick, so say
+    // so. The user asked for one model; the table would have sent some task
+    // classes elsewhere, and finding that out from a usage breakdown later is
+    // worse than one line here.
+    if (choice !== "auto" && model.hasRoutingTable) {
+        out.print(out.theme.muted("  (overrides your configured routing table for this session)"));
+    }
+}
+/**
+ * `/init` (P6 track 4) — scaffold a project `CRUXY.md` and load it immediately.
+ *
+ * NOT a reuse of `cruxy init`. That command is an onboarding flow: it acquires
+ * an API key if one is missing, offers a scaffold, and offers a first-win demo
+ * run — none of which makes sense inside a session that is already
+ * authenticated and already running. The one genuinely shared piece is the
+ * template and the write, which now live in `config/project.ts`.
+ *
+ * The `/reload` afterwards is what makes this useful rather than ceremonial:
+ * project instructions are folded into every turn's system prompt and read once
+ * at session start, so a `CRUXY.md` written mid-session would otherwise sit
+ * there doing nothing until the next launch.
+ */
+function handleInit(ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const outcome = scaffoldProjectInstructions(session.toolContext.cwd);
+    if (outcome.kind === "exists") {
+        // Never overwrites — and says which file already covers it, since the
+        // loader honours CRUXY.md or AGENTS.md and the user may have forgotten
+        // which one this project uses.
+        out.print(t.muted("project instructions already exist here — edit them and run /reload"));
+        return;
+    }
+    if (outcome.kind === "failed") {
+        out.print(t.danger(`could not write CRUXY.md — ${outcome.message}`));
+        return;
+    }
+    out.print(t.muted(`wrote ${outcome.file}`));
+    session.reloadProjectInstructions();
+    out.print(t.muted("loaded into this session — it is a skeleton, so fill it in and /reload"));
+}
+/**
+ * `/status` (P6 track 4) — what this session is set up to do, in one screen.
+ *
+ * The facts exist; they are just scattered. The mode is a chip on the input row,
+ * the model and git live in rail panels the REPL does not have, the multi-root
+ * banner is printed once at startup and then gone, and whether a sandbox is
+ * actually engaged is visible nowhere after the first line of output. The two
+ * that matter most for safety are exactly the two with no persistent surface in
+ * the REPL at all.
+ *
+ * Every value is read from the object that owns it rather than re-derived, so
+ * this can never disagree with the surface it summarises.
+ */
+function handleStatus(ctx) {
+    const { out, session } = ctx;
+    const toolCtx = session.toolContext;
+    const config = toolCtx.config;
+    const mode = session.getMode();
+    // A real user turn is `role: "user"` with STRING content — tool results are
+    // also role "user" but carry blocks, so this counts what the human said.
+    const turns = session.messages.filter((m) => m.role === "user" && typeof m.content === "string").length;
+    const roots = toolCtx.workspace.roots().map((r) => {
+        // A synchronous probe, on an explicitly-requested command. The rail's rule
+        // (never probe on the paint path) is about frames, not about a user who
+        // just asked; there is no frame budget to blow here.
+        const git = getGitInfo(r.absPath);
+        return {
+            name: r.name,
+            path: r.absPath,
+            primary: r.primary,
+            ...(git === null ? {} : { branch: git.branch, changed: git.changed }),
+        };
+    });
+    const jobs = session.jobs?.list();
+    for (const line of sessionStatusLines({
+        sessionId: session.sessionId,
+        turns,
+        mode,
+        modeDescription: modeDescription(mode),
+        ...(session.model ? { model: session.model.current() } : {}),
+        provider: config.model.provider,
+        roots,
+        context: readContext(session.messages, config.context),
+        sandboxEnabled: Boolean(toolCtx.sandbox),
+        ...(toolCtx.sandbox
+            ? { sandboxRuntime: toolCtx.sandbox.runtimeName }
+            : {}),
+        checkpoints: Boolean(toolCtx.checkpointsActive),
+        ...(jobs
+            ? {
+                jobs: {
+                    total: jobs.length,
+                    running: jobs.filter((j) => j.status === "running").length,
+                    needingApproval: jobs.filter((j) => j.pendingApproval).length,
+                },
+            }
+            : {}),
+        tools: toolCount(ctx),
+    }, out.theme)) {
+        out.print(out.fit(line));
+    }
+}
+/** Tools advertised to the model this session — the registry the loop dispatches against. */
+function toolCount(ctx) {
+    return ctx.session.toolRegistry.list().length;
+}
+/**
+ * `/diff` (P6 track 4) — what has changed on disk, without leaving the session.
+ *
+ * Defaults to the working tree against `HEAD`: mid-session, the question is
+ * almost always "what has this run actually done to my files", and uncommitted
+ * changes are that answer. `/diff <ref>` widens it to any commit-ish, which is
+ * how you see a whole branch's worth.
+ *
+ * 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) {
+    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) {
+        if (roots.length > 1)
+            out.print(t.strong(`${root.name}`));
+        // `null` branch means not a repo (or detached) — either way there is
+        // nothing to diff against, and saying so beats an empty block.
+        if (currentBranch(root.absPath) === null && !hasChanges(root.absPath)) {
+            out.print(t.muted("  not a git repo (or nothing to compare)"));
+            continue;
+        }
+        const diff = diffAgainst(root.absPath, ref);
+        if (diff.trim() === "") {
+            out.print(t.muted(`  no changes against ${ref}`));
+            continue;
+        }
+        any = true;
+        for (const line of renderUnifiedDiff(diff, t, {
+            maxLines: DIFF_MAX_LINES,
+        })) {
+            out.print(out.fit(line));
+        }
+    }
+    if (any) {
+        // A working-tree diff says nothing about what has been committed or pushed,
+        // and a reader who has just watched an agent work may assume otherwise.
+        out.print(t.muted(`(working tree vs ${ref} — commits, pushes and PRs are not shown)`));
+    }
+}
+/**
+ * `/export` (P6 track 4) — write this conversation to a Markdown file.
+ *
+ * REFUSES TO OVERWRITE, always, with no `--force`. The whole value of an export
+ * is that it is a record; a command that can silently replace one is a command
+ * that can destroy the thing it exists to produce. Picking a new name is one
+ * keystroke; recovering a clobbered transcript is not possible.
+ *
+ * This writes a file WITHOUT going through the approval gate, and that is
+ * correct rather than an omission: the gate exists to put a human between the
+ * MODEL and the filesystem, and the model cannot reach slash commands — they are
+ * dispatched from the input loop, never from the tool registry. `/add-root`
+ * makes the same argument for the same reason.
+ */
+function handleExport(input, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const cwd = session.toolContext.cwd;
+    const arg = input.slice("/export".length).trim();
+    const target = resolve(cwd, arg === "" ? defaultExportName(session.sessionId) : arg);
+    if (existsSync(target)) {
+        out.print(t.muted(`${target} already exists — pass a different path to /export`));
+        return;
+    }
+    const document = exportMarkdown(session.messages, {
+        sessionId: session.sessionId,
+        exportedAt: new Date().toISOString(),
+        cwd,
+        provider: session.toolContext.config.model.provider,
+        ...(session.model ? { model: session.model.current() } : {}),
+    });
+    try {
+        writeFileSync(target, document, "utf8");
+    }
+    catch (err) {
+        out.print(t.danger(`could not write ${target} — ${err.message}`));
+        return;
+    }
+    out.print(t.muted(`wrote ${target} (${session.messages.length} message${session.messages.length === 1 ? "" : "s"})`));
+}
+/**
+ * `/context` (P6 track 3) — the detail view behind the rail's two numbers.
+ *
+ * Deliberately NOT a text copy of the panel. The panel's doc comment argues
+ * that two plain numbers are the honest presentation and a progress bar is not,
+ * and reproducing it here in a wider space would be the same claim with more
+ * room to look authoritative. What this adds is the two things a 24-column strip
+ * genuinely cannot carry: where the tokens are, and what compaction would drop —
+ * the latter computed by the same `findCut` the seam uses.
+ */
+function handleContext(ctx) {
+    const { out, session } = ctx;
+    const report = contextReport(session.messages, session.toolContext.config.context);
+    for (const line of contextReportLines(report, out.theme)) {
+        out.print(out.fit(line));
+    }
+}
+/**
+ * `/usage` (P6 track 2) — the richest data cruxy holds, and until now the only
+ * way to see it was to leave the session and run a second process.
+ *
+ * `/usage` scopes to THIS session, `/usage all` to everything retained, and
+ * `/usage last <n>` to the newest N runs. The session scope is exact rather than
+ * inferred: `cruxy usage --session` has to guess the session from the newest run
+ * in the store, because a command line has none of its own — which quietly
+ * reports someone else's runs as soon as two sessions interleave. Here the id is
+ * known, so it is used.
+ *
+ * The report is the SAME renderer `cruxy usage` prints, deliberately including
+ * the paragraph explaining what the weighted figure is and is not. That copy is
+ * load-bearing — a weighted total read as a remaining balance is a correct
+ * number that has misled someone — so it is not abbreviated for being in-session.
+ */
+function handleUsage(input, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const arg = input.slice("/usage".length).trim().toLowerCase();
+    let scope;
+    let scopeLabel;
+    if (arg === "" || arg === "session") {
+        scope = { sessionId: session.sessionId };
+        scopeLabel = "this session";
+    }
+    else if (arg === "all") {
+        scope = {};
+        scopeLabel = "all retained runs";
+    }
+    else if (arg.startsWith("last")) {
+        const n = Number(arg.slice("last".length).trim());
+        if (!Number.isInteger(n) || n <= 0) {
+            out.print(t.muted("usage: /usage last <n>  (n a positive integer)"));
+            return;
+        }
+        scope = { last: n };
+        scopeLabel = `last ${runCountLabel(n)}`;
+    }
+    else {
+        out.print(t.muted("usage: /usage [all | last <n>]"));
+        return;
+    }
+    const { data, error } = loadUsage();
+    if (error) {
+        // A corrupt store is a warning here, never fatal: `cruxy usage` can exit on
+        // it, but a shell must survive a failed command and return to the prompt.
+        printCommandError(out, error);
+        return;
+    }
+    const runs = selectRuns(data.runs, scope);
+    const enabled = session.toolContext.config.usage.enabled;
+    // Nothing on disk for this session, but the run that just finished is still
+    // in memory. Showing it beats the literal-but-useless "no usage recorded yet"
+    // — that answer is only the whole truth when tracking is ON.
+    if (runs.length === 0 && !enabled && session.lastRun) {
+        for (const line of usageReport([session.lastRun], t, {
+            scopeLabel: "the last run (not being recorded)",
+            trackingEnabled: enabled,
+        })) {
+            for (const row of line.split("\n"))
+                out.print(out.fit(row));
+        }
+        out.print(t.muted("usage tracking is off (usage.enabled = false) — nothing is saved"));
+        return;
+    }
+    const config = session.toolContext.config.usage;
+    for (const line of usageReport(runs, t, {
+        scopeLabel,
+        trackingEnabled: enabled,
+        legacyPriceConfig: config.currency !== undefined || config.prices !== undefined,
+    })) {
+        // The report's paragraphs carry their own newlines; each row is fitted
+        // separately so the REPL truncates per LINE rather than mangling a block.
+        for (const row of line.split("\n"))
+            out.print(out.fit(row));
+    }
+}
+/** Render the background-job list (`/jobs`). */
+function handleJobsList(ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const jobs = session.jobs;
+    if (!jobs) {
+        out.print(t.muted("background jobs are disabled — enable with `cruxy config set jobs.enabled true`"));
+        return;
+    }
+    const list = jobs.list();
+    if (list.length === 0) {
+        out.print(t.muted("no background jobs this session"));
+        return;
+    }
+    for (const j of list) {
+        const status = j.status === "failed" ? t.danger(j.status) : t.accent(j.status);
+        const pending = j.pendingApproval
+            ? t.muted(` — needs approval: ${j.pendingApproval}`)
+            : "";
+        const err = j.error ? t.muted(` (${j.error})`) : "";
+        // Fit id-first so the job id + status always survive; the label/notes tail
+        // truncates with an honest ellipsis at narrow width (U.12).
+        out.print(out.fit(`${t.strong(j.id)}  ${status}  ${j.label}${pending}${err}`));
+    }
+}
+/** Print one job's log (`/logs <id>`). */
+function handleJobLogs(input, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    const jobs = session.jobs;
+    if (!jobs) {
+        out.print(t.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/logs".length).trim();
+    if (!id) {
+        out.print(t.muted("usage: /logs <id>"));
+        return;
+    }
+    try {
+        const log = jobs.logs(id);
+        if (log.dropped > 0) {
+            out.print(t.muted(`… ${log.dropped} earlier line(s) rolled off`));
+        }
+        for (const line of log.lines) {
+            out.print(out.fit(line.stream === "err" ? t.danger(line.text) : line.text));
+        }
+        out.print(t.muted(`(${log.status})`));
+    }
+    catch (err) {
+        printCommandError(out, err);
+    }
+}
+/** Cancel a job (`/cancel <id>`). */
+async function handleJobCancel(input, ctx) {
+    const { out, session } = ctx;
+    const jobs = session.jobs;
+    if (!jobs) {
+        out.print(out.theme.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/cancel".length).trim();
+    if (!id) {
+        out.print(out.theme.muted("usage: /cancel <id>"));
+        return;
+    }
+    try {
+        const cancelled = jobs.cancel(id);
+        out.print(out.theme.muted(cancelled
+            ? `cancelling ${id} (its process tree is killed; any checkpoint survives for rollback)`
+            : `${id} is already finished`));
+    }
+    catch (err) {
+        printCommandError(out, err);
+    }
+}
+/**
+ * `/add-root <name> <path>` (C.26 step 5) — an explicit, human-only way to
+ * declare another workspace root. This is a shell command, NOT a model tool: the
+ * model can only reach the tool registry, and nothing named `add_root` is
+ * registered there, so the allowlist argument is unchanged. It validates the
+ * addition (TTY-only; same existence/name/overlap refusal as `--root`) and, on
+ * success, tells the user to relaunch with `--root` to activate it — a
+ * mid-session hot-swap would leave the checkpoint gate + hook router (both wired
+ * from the session-start workspace) half-attributed, so activation is deferred
+ * to a clean relaunch. A newly declared root always starts untrusted.
+ */
+async function handleAddRoot(input, ctx) {
+    const { out, session } = ctx;
+    const parts = input
+        .slice("/add-root".length)
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+    if (parts.length !== 2) {
+        out.print(out.theme.muted("usage: /add-root <name> <path>"));
+        return;
+    }
+    const [name, rootPath] = parts;
+    const toolCtx = session.toolContext;
+    try {
+        const next = await addRootToWorkspace(toolCtx.workspace, { name, path: rootPath }, { cwd: toolCtx.cwd, tty: ctx.tty });
+        const abs = next.rootByName(name).absPath;
+        out.print(out.theme.muted(`validated root "${name}" (${abs}). relaunch with \`--root ${name}=${rootPath}\` to activate it — ` +
+            `it starts untrusted (its hooks and project memory stay inert until you run \`cruxy hooks/memory trust\`).`));
+    }
+    catch (err) {
+        printCommandError(out, err);
+    }
+}
+/**
+ * Run a shell-bound custom slash command (C.19) through the SAME gated +
+ * sandboxed path as `run_command` (`runGatedShell` over the session's tool
+ * context) — never a privileged route. Prints the result like a shell run; a
+ * gate rejection or a thrown coded error (e.g. sandbox) is surfaced, not fatal.
+ */
+async function runSlashShell(spec, ctx) {
+    const { out, session } = ctx;
+    const t = out.theme;
+    out.print(t.muted(`running /${spec.name}${t.glyph.ellipsis}`));
+    try {
+        const outcome = await runGatedShell(spec.command ?? "", session.toolContext);
+        if (!outcome.approved) {
+            out.print(t.muted(outcome.rejection ?? "command denied by the user"));
+            return;
+        }
+        const e = outcome.exec;
+        if (e.timedOut) {
+            out.print(t.warning("timed out"));
+            return;
+        }
+        if (e.spawnError !== undefined) {
+            out.print(t.danger(e.spawnError));
+            return;
+        }
+        for (const line of `exit code ${e.exitCode ?? e.signal ?? "unknown"}\n${e.output}`.split("\n")) {
+            out.print(line);
+        }
+    }
+    catch (err) {
+        printCommandError(out, err);
+    }
+}
+/**
+ * Render a non-fatal error inline (classified + formatted, the same 4-part
+ * shape as the fatal boundary) and return to the prompt — a shell must survive
+ * a failed command rather than exit.
+ */
+export function printCommandError(out, err) {
+    const cruxy = fromUnknown(err);
+    const text = formatError(cruxy, {
+        verbose: isVerbose(),
+        color: out.theme.color,
+    });
+    for (const line of text.split("\n"))
+        out.print(line);
+}