@cruxy/cli 1.9.0 → 1.10.0

package/dist/checkpoint/coverage.js

@@ -24,10 +24,13 @@ import { ALWAYS_IGNORE_DIRS, isSecretPath } from "../indexing/walker.js";
  * `classify` is a pure synchronous function by design (it runs on every action,
  * including the tier check in `approval/mutex.ts`). So a gitignored build
  * directory — `rm -rf dist` — is still classified reversible when it is not.
- * That residual is deliberate and bounded: the four classes below are the ones
- * whose loss is *permanent* (history, secrets, the checkpoint store itself),
- * while generic ignored output is regenerable. It is recorded in cli#241 rather
- * than papered over.
+ *
+ * That general residual is **accepted**, not pending: emulating `git
+ * check-ignore` from a pure path predicate is the wrong shape for this seam
+ * (cli#241 records the argument in full). What is not accepted is the subset
+ * whose loss is *permanent* — Terraform state, a local database, a `*.local.*`
+ * config — which {@link ceilingExclusion} refuses on the ceiling side without
+ * touching this function or the snapshot it filters.
  */
 export function captureExclusion(relPath) {
     const first = relPath.split("/")[0];
@@ -68,3 +71,143 @@ for (const name of ALWAYS_IGNORE_DIRS) {
             `every path the capturer skips must be one auto-approve refuses to treat as restorable`);
     }
 }
+// ── the ceiling-only strictness list (cli#241) ────────────────────────────────
+/**
+ * Why the **ceiling** refuses to call `relPath` restorable, or `null` when it has
+ * no objection. Same shape as {@link captureExclusion} — pure, synchronous,
+ * path-only, no I/O — because `classify` runs it on every action, including the
+ * tier check in `approval/mutex.ts`.
+ *
+ * It is {@link captureExclusion} **plus** {@link CEILING_ONLY}, and therefore
+ * strictly stricter. `classify` reads this one; `captureFiles` still reads
+ * `captureExclusion`. The two differ by exactly the paths a snapshot should keep
+ * taking and auto-approve should stop trusting.
+ *
+ * Returns a **predicate phrase** — the sentence minus its subject, so the caller
+ * supplies the label the user actually typed. The two halves are introduced
+ * differently on purpose: a capture exclusion is a fact ("is not captured"),
+ * while a ceiling-only class may well be sitting in the snapshot if the repo
+ * tracks it, and the prompt must not claim otherwise.
+ */
+export function ceilingExclusion(relPath) {
+    const notCaptured = captureExclusion(relPath);
+    if (notCaptured !== null) {
+        return `is not captured by the checkpoint — ${notCaptured}`;
+    }
+    for (const rule of CEILING_ONLY) {
+        if (rule.matches(relPath)) {
+            return `is not one the checkpoint can be relied on to restore — ${rule.reason}`;
+        }
+    }
+    return null;
+}
+/**
+ * Paths auto-approve refuses to treat as restorable **even though the capturer
+ * may well have snapshotted them**. This is the ceiling being stricter than the
+ * snapshot, deliberately and in one direction only.
+ *
+ * ── Why a second list, and not four more entries in `NEVER_CAPTURED_DIRS` ──
+ * That map is read by `captureFiles`. Adding `*.tfstate` there would stop the
+ * capturer from snapshotting a `terraform.tfstate` a repo tracks — turning a
+ * conservative extra prompt into an actual hole in the snapshot, in the name of
+ * closing one. The two lists exist because the two questions are different:
+ *
+ *   • `captureExclusion` — "must the snapshot refuse to hold this?" (secrets,
+ *     `.git/`, the checkpoint store itself). Excluding is a cost paid by restore.
+ *   • `CEILING_ONLY` — "may auto-approve assume a snapshot can put this back?"
+ *     Refusing costs one prompt and nothing else.
+ *
+ * So the safe drift direction is *into* this list, never out of it. The
+ * assertions below enforce both halves: `NEVER_CAPTURED ⊆ CEILING` (anything the
+ * snapshot skips, the ceiling must also refuse), and each rule here is witnessed
+ * to be outside the capture exclusion (anything filed here must genuinely be the
+ * ceiling being stricter, not a snapshot exclusion in the wrong file).
+ *
+ * ── The selection rule: permanent loss, not regenerable output ──
+ * The general problem — "is this path gitignored?" — is not decidable from a
+ * path alone and stays open (see {@link captureExclusion}). This list does not
+ * try to solve it. A class earns a place here only when destroying the file
+ * destroys **state that exists nowhere else**: not in a commit, not in a
+ * registry, not reproducible by re-running a build. That is what separates these
+ * from `dist/`, `.next/`, `coverage/`, `target/` — all of which are just as
+ * likely to be gitignored and just as absent from the snapshot, and all of which
+ * a build command puts back. The cost of being wrong is the whole selection
+ * criterion: a false positive here is one prompt, a false negative is a file
+ * nobody can reconstruct.
+ *
+ * Deliberately NOT here: anything decided by *content*, by repo layout, or by
+ * asking git. Each rule below is a fact about a filename.
+ */
+const CEILING_ONLY = [
+    {
+        // `terraform.tfstate`, `.tfstate.backup`, `terraform.tfstate.d/<ws>/...`.
+        // Matched on any segment so a workspace directory carries the exclusion to
+        // everything under it.
+        matches: (relPath) => relPath.split("/").some((seg) => seg.includes(".tfstate")),
+        reason: "a Terraform state file is the only record mapping the configuration to the real infrastructure it manages; it cannot be recomputed from the `.tf` files, and losing it orphans live resources",
+        witness: "infra/terraform.tfstate",
+    },
+    {
+        matches: (relPath) => isLocalDatabase(basename(relPath)),
+        reason: "a local database file holds rows that exist nowhere else — no build regenerates them, no registry re-serves them, and the checkpoint only captures it when the repo happens to track it",
+        witness: "data/app.sqlite",
+    },
+    {
+        // `settings.local.json`, `vite.config.local.ts`, `wrangler.local.toml`.
+        matches: (relPath) => basename(relPath).includes(".local."),
+        reason: "`*.local.*` is the convention for the machine-specific half of a config pair — the copy that is deliberately not in the repo, and so is in no commit and in no snapshot to restore from",
+        witness: ".claude/settings.local.json",
+    },
+];
+/** Extensions used by the embedded databases a project keeps in its own tree. */
+const LOCAL_DB_EXTENSIONS = new Set([
+    "sqlite",
+    "sqlite3",
+    "db",
+    "db3",
+    "duckdb",
+]);
+/**
+ * SQLite writes its rollback journal and WAL/shared-memory files *beside* the
+ * database as `<name>-journal` / `-wal` / `-shm`. Deleting one of those loses
+ * committed-but-uncheckpointed pages, so they are the same class as the file
+ * they sit next to.
+ */
+const DB_SIDECAR = /-(wal|shm|journal)$/;
+function isLocalDatabase(base) {
+    const name = base.replace(DB_SIDECAR, "");
+    const dot = name.lastIndexOf(".");
+    return dot > 0 && LOCAL_DB_EXTENSIONS.has(name.slice(dot + 1).toLowerCase());
+}
+/** Last segment of a project-relative POSIX path (the input contract everywhere here). */
+function basename(relPath) {
+    return relPath.split("/").pop() ?? "";
+}
+// NEVER_CAPTURED ⊆ CEILING. The same shape as the ALWAYS_IGNORE_DIRS assertion
+// above, one layer out: a path the snapshot cannot hold must be one the ceiling
+// refuses to call restorable. It holds by delegation today — `ceilingExclusion`
+// asks `captureExclusion` first — and is asserted so that it keeps holding if
+// that delegation is ever restructured, reordered, or "optimized" into a single
+// merged list. Drift is permitted in the safe direction only: the ceiling may
+// refuse more than the capturer skips, never less.
+for (const name of NEVER_CAPTURED_DIRS.keys()) {
+    if (ceilingExclusion(`${name}/probe`) === null) {
+        throw new Error(`checkpoint/coverage.ts: \`${name}/\` is never captured but the auto-approve ceiling ` +
+            `would call it restorable — the ceiling must refuse everything the snapshot skips`);
+    }
+}
+// …and STRICTLY stricter: every rule here must match its own witness, and that
+// witness must be a path the capturer still snapshots. The second half is the
+// load-bearing one — it fails the build if a class is moved into
+// `NEVER_CAPTURED_DIRS`/`isSecretPath` instead, which would close the prompt by
+// shrinking the snapshot rather than by tightening the ceiling.
+for (const rule of CEILING_ONLY) {
+    if (!rule.matches(rule.witness)) {
+        throw new Error(`checkpoint/coverage.ts: ceiling-only rule does not match its own witness \`${rule.witness}\``);
+    }
+    if (captureExclusion(rule.witness) !== null) {
+        throw new Error(`checkpoint/coverage.ts: \`${rule.witness}\` is already outside the capture set, so this ` +
+            `rule is not ceiling-only — an exclusion the capturer honors belongs in NEVER_CAPTURED_DIRS, ` +
+            `and moving it there would stop the snapshot taking a copy the repo may well track`);
+    }
+}

package/dist/cli/commands/limits.js

@@ -0,0 +1,76 @@
+import { Command } from "commander";
+import { LimitsClient } from "@cruxy/sdk";
+import { loadConfig, readCredentialMeta, resolveApiKey, } from "../../config/index.js";
+import { shouldUseColor } from "../../errors/index.js";
+import { LimitsCache } from "../../limits/index.js";
+import { limitsReportLines } from "../../render/limits-report.js";
+import { themeForColor } from "../../theme/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy limits` (cli#138) — what this account may spend, and how much is left,
+ * from outside a session.
+ *
+ * THE GAP THIS CLOSES IS THE SESSION, not the rendering. Both existing surfaces
+ * read the same cache and neither can run without one: the P9 panel is drawn by
+ * the interactive rail, and `/budget` is a slash command. "How much of my pool
+ * is left" was therefore unanswerable from a script, a prompt, or a CI step —
+ * for a figure that is about the ACCOUNT and has nothing to do with whether a
+ * session happens to be open.
+ *
+ * IT IS NOT A FLAG ON `cruxy usage`, and the reason is not tidiness. That
+ * command reads the local store and transmits nothing, a promise held by a
+ * runtime fetch spy and a static source guard. The number this one wants is on
+ * the server, so putting it there would mean deleting that guarantee to gain a
+ * figure that has its own home — and joining the two numerators would produce a
+ * ratio that reads as precise and is not (`render/limits-report.ts` carries the
+ * arithmetic). Two commands, two sources, and the boundary is legible from the
+ * name.
+ *
+ * Note for anyone extending this: the no-phone-home guard lists the files it
+ * covers by hand, and this one is deliberately absent from that list. That is
+ * correct — this command is supposed to make the call — but it does mean a green
+ * guard says nothing at all about this file. The boundary is the command split.
+ *
+ * THE READING COMES THROUGH `LimitsCache`, not through a bare client call, so
+ * this command and the rail reduce the same response the same way. The cache's
+ * other job — keeping a good reading through a failed refresh — is inert in a
+ * one-shot process with nothing prior to keep, which is exactly why the tri-state
+ * matters here: with no earlier answer to stand on, a failed probe IS the
+ * result, and the report says which failure it was.
+ */
+export function limitsCommand() {
+    return new Command("limits")
+        .description("show your plan's weighted-token pool and what is left of it")
+        .action(async () => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const provider = config.model.provider;
+        // ONLY ON THE CRUXY PROVIDER — now guaranteed by the schema rather than
+        // re-checked here. `/limits` is a cruxy gateway endpoint, and pointing it
+        // at someone else's base URL would be sending their credential to a
+        // stranger to ask a question their API was never going to answer. This
+        // used to be a runtime guard on `provider !== "cruxy"`; since #260 that
+        // is the only value `ProviderSchema` accepts, so a non-cruxy provider is
+        // refused at CONFIG LOAD (CRUXY_E_CONFIG_INVALID) — before this or any
+        // other command runs. The guarantee got earlier and wider, not weaker.
+        //
+        // NOTE what neither form covers: `cruxy.gatewayUrl` is configurable, so a
+        // cruxy-provider session can still be aimed at a non-cruxy host. That was
+        // true of the old guard too — it keyed on the provider id, not the URL.
+        const apiKey = resolveApiKey(provider);
+        // The stored expiry, read lazily and only while classifying a 401 — it is
+        // what lets an aged-out sign-in be reported as expired rather than as a
+        // key that was never any good. The gateway refuses both identically and
+        // will not say which.
+        const cache = new LimitsCache(apiKey === undefined
+            ? undefined
+            : (signal) => new LimitsClient({
+                apiKey,
+                gatewayUrl: config.cruxy.gatewayUrl,
+            }).read(signal), { credentialExpiresAt: () => readCredentialMeta(provider)?.expiresAt });
+        await cache.refresh();
+        for (const line of limitsReportLines(t, cache.current())) {
+            logger.print(line);
+        }
+    });
+}

package/dist/cli/commands/pr.js

@@ -4,7 +4,7 @@ import { logger } from "../../utils/logger.js";
 import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, shouldUseColor } from "../../errors/index.js";
 import { themeForColor } from "../../theme/index.js";
-import { ApprovalService } from "../../approval/index.js";
+import { ApprovalService, defaultPromptIO, InteractivePolicy, SessionAllowlist, } from "../../approval/index.js";
 import { resolveTaskModel, routerForConfig } from "../../routing/index.js";
 import { createForgeProvider, createPrService, generateWithLlm, loadCommitGuidance, resolveForgeToken, } from "../../vcs/index.js";
 /**
@@ -48,9 +48,18 @@ export function prCommand() {
         // resolveForgeToken throws CRUXY_E_FORGE_AUTH (exit 4) if none is found.
         const forge = createForgeProvider(resolveForgeToken());
         const guidance = await loadCommitGuidance(cwd);
+        // The allowlist here is provably inert, and stated rather than implied
+        // (cli#251). `cruxy pr` submits exactly one kind of action — `vcs` — and
+        // `vcsRequest` gives every one of them `scope: {kind: "none"}` and an
+        // unconditional `irreversible`. So it is never WRITTEN (`grant()` returns
+        // early on a `none` scope) and never READ (`allows()` refuses an
+        // irreversible request before it matches scopes at all, since cli#240).
+        // A fresh one each time is therefore the whole truth about this command:
+        // every PR is approved on its own, by design.
         const approval = new ApprovalService({
             cwd,
             interactive: Boolean(process.stdin.isTTY),
+            policy: new InteractivePolicy(new SessionAllowlist(), defaultPromptIO(shouldUseColor())),
         });
         const service = createPrService({
             cwd,

package/dist/cli/commands/rollback.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import { themeForColor } from "../../theme/index.js";
 import { loadConfig } from "../../config/index.js";
 import { CheckpointService, listSets, rollbackCheckpoint, rollbackSet, } from "../../checkpoint/index.js";
-import { ApprovalService, defaultPromptIO } from "../../approval/index.js";
+import { ApprovalService, defaultPromptIO, InteractivePolicy, SessionAllowlist, } from "../../approval/index.js";
 import { fuzzyFind, selectList } from "../../components/index.js";
 import { rollbackApprovalRequired, shouldUseColor, } from "../../errors/index.js";
 import { logger } from "../../utils/logger.js";
@@ -92,10 +92,18 @@ export function rollbackCommand() {
         const t = themeForColor(shouldUseColor(process.stdout));
         const { config } = loadConfig();
         const primaryRoot = process.cwd();
+        // Provably inert, and stated rather than implied (cli#251). `cruxy
+        // rollback` submits exactly one kind of action — `rollback` — and
+        // `rollbackRequest` gives every one of them `scope: {kind: "none"}` and an
+        // unconditional `irreversible` (`ROLLBACK_IRREVERSIBLE`). So this
+        // allowlist is never WRITTEN (`grant()` returns early on a `none` scope)
+        // and never READ (`allows()` refuses an irreversible request before it
+        // matches scopes at all, since cli#240). Every restore is a deliberate,
+        // one-off approval — which is the property, not an oversight.
         const approval = new ApprovalService({
             cwd: primaryRoot,
             interactive,
-            io: defaultPromptIO(shouldUseColor()),
+            policy: new InteractivePolicy(new SessionAllowlist(), defaultPromptIO(shouldUseColor())),
         });
         const deps = {
             config,

package/dist/cli/commands/run.js

@@ -5,7 +5,13 @@ import { LimitsCache } from "../../limits/index.js";
 import { logger } from "../../utils/logger.js";
 import { SessionLog, listSessions, loadResume, resolveSessionId, resumePicker, shortId, } from "../../session/index.js";
 /** Sessions shown in the TUI sidebar — the same depth as the resume picker. */
-const SIDEBAR_SESSIONS = 10;
+/**
+ * How many sessions the TUI sidebar lists. Exported so
+ * `session/retention-floor.test.ts` can pin `SESSION_RETENTION_FLOOR` against
+ * it — raising this surface without raising the floor would let the sidebar
+ * offer rows a later prune has already marked expendable (#257).
+ */
+export const SIDEBAR_SESSIONS = 10;
 import { classifyCredentialLifetime, globalDir, loadConfig, readCredentialMeta, resolveApiKey, } from "../../config/index.js";
 import { agentIncomplete, authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
@@ -340,11 +346,21 @@ export async function executeRun(promptParts, opts) {
         model: config.model.model,
         logger,
         currentRunId: () => checkpoints?.currentRunId(),
+        // Persistence and retention (#257). `enabled: false` makes this null and
+        // the session runs in memory; retention is enforced once, here, as the
+        // log opens — the same position `CheckpointService` prunes from.
+        sessions: config.sessions,
         ...(resumed ? { file: resumed.session.file } : {}),
     }) ?? undefined;
     // The TUI sidebar lists the same tree the `--resume` picker reads (P2).
-    // Populated AFTER the log is opened so the running session is itself listed —
-    // its meta line has to exist before `listSessions` can see it.
+    //
+    // A FRESH SESSION IS NOT IN ITS OWN SIDEBAR UNTIL TURN 1 (#257). This used to
+    // be populated after the log was opened precisely so the running session
+    // listed itself; the meta line is buffered now, so there is nothing on disk
+    // to list until something is said. That is the more honest reading — the
+    // sidebar and the `--resume` picker show the same tree, and a session with no
+    // conversation in it is not one the picker would offer either. The active id
+    // is still passed, so the row marks itself the moment it appears.
     if (renderer instanceof TuiRenderer) {
         renderer.setSessions(listSessions(primaryRoot, SIDEBAR_SESSIONS), sessionId);
     }

package/dist/cli/commands/sessions.js

@@ -0,0 +1,156 @@
+import { unlinkSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../../config/index.js";
+import { shouldUseColor, usageError } from "../../errors/index.js";
+import { SESSION_FILE_EXT, matchSessionRefs, listSessionRefs, pruneSessions, sessionFilesByRecency, shortId, summarizeSession, relativeAge, } from "../../session/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { formatBytes } from "../../utils/disk.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy sessions` (#257) — see and bound what `~/.cruxy/projects/<project>/`
+ * is holding.
+ *
+ * WHY THIS EXISTS AT ALL, when retention already runs on its own. Retention
+ * that only ever fires implicitly is retention nobody can audit before it eats
+ * something: the first prune after upgrading from a build that had none can
+ * remove months of sessions, and "trust me, the right ones went" is not a thing
+ * a user can check. `list` shows what is there and which rows the current
+ * bounds would take; `prune` runs the same policy on demand; `rm` is the
+ * escape hatch for one specific session.
+ *
+ * BYTES ARE REPORTED, NEVER PRUNED ON. `statSync` hands the size over for free
+ * in the same scan that orders by mtime, and seeing where the disk went is
+ * exactly what a report is for. Making it a BOUND is the part that would be
+ * wrong — whether your session survives should not depend on how chatty an
+ * unrelated one was.
+ */
+export function sessionsCommand() {
+    const cmd = new Command("sessions").description("manage this project's saved sessions — list, prune, delete");
+    cmd
+        .command("list", { isDefault: true })
+        .description("list saved sessions, newest first")
+        .option("--all", "list every session, not just the newest 20")
+        .action((opts) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const cwd = process.cwd();
+        const files = sessionFilesByRecency(cwd);
+        if (files.length === 0) {
+            logger.print(t.muted("no saved sessions for this project"));
+            printPolicy(config.sessions, t);
+            return;
+        }
+        // The listing is the one place that pays for a full read per row — it is
+        // showing titles and turn counts, which is the cost `summarizeSession`
+        // exists to charge. Bounded to 20 unless asked, for the same reason the
+        // picker is bounded to 10.
+        const shown = opts.all ? files : files.slice(0, 20);
+        const total = files.reduce((n, f) => n + f.size, 0);
+        for (const ref of shown) {
+            const summary = summarizeSession(ref.file);
+            const id = summary
+                ? shortId(summary.sessionId)
+                : shortId(path.basename(ref.file, SESSION_FILE_EXT));
+            // A file with no readable meta is SHOWN, not hidden. It is occupying
+            // disk and it is a thing prune will consider; a report that silently
+            // omitted it would be lying about what is there.
+            const title = summary ? summary.title : t.muted("(unreadable)");
+            const turns = summary
+                ? `${summary.turns} turn${summary.turns === 1 ? "" : "s"}`
+                : "—";
+            logger.print(`${t.accent(id.padEnd(8))}  ${t.muted(relativeAge(new Date(ref.mtimeMs).toISOString()).padEnd(9))}  ` +
+                `${t.muted(formatBytes(ref.size).padStart(9))}  ${t.muted(turns.padEnd(8))}  ${title}`);
+        }
+        if (shown.length < files.length) {
+            logger.print(t.muted(`\n… and ${files.length - shown.length} more — pass \`--all\` to list every one`));
+        }
+        logger.print(t.muted(`\n${files.length} session${files.length === 1 ? "" : "s"}, ${formatBytes(total)}`));
+        printPolicy(config.sessions, t);
+    });
+    cmd
+        .command("prune")
+        .description("clear sessions past sessions.retention / sessions.maxAgeDays")
+        .option("-n, --dry-run", "show what would be deleted, delete nothing")
+        .action((opts) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const cwd = process.cwd();
+        if (!config.sessions.enabled) {
+            logger.print(t.muted("session persistence is off (`sessions.enabled = false`) — nothing is being recorded to prune"));
+            return;
+        }
+        if (opts.dryRun) {
+            // The dry run must not go anywhere near `unlinkSync`, so it re-derives
+            // the doomed set from the SAME ordering and the same two bounds rather
+            // than sharing a code path with a delete in it behind a flag.
+            const now = Date.now();
+            const cutoff = now - config.sessions.maxAgeDays * 24 * 60 * 60 * 1000;
+            const doomed = sessionFilesByRecency(cwd).filter((ref, i) => ref.mtimeMs < cutoff || i >= config.sessions.retention);
+            if (doomed.length === 0) {
+                logger.print(t.muted("nothing to prune"));
+                return;
+            }
+            for (const ref of doomed) {
+                logger.print(`${t.muted("would delete")} ${shortId(path.basename(ref.file, SESSION_FILE_EXT))}  ` +
+                    `${t.muted(relativeAge(new Date(ref.mtimeMs).toISOString()))}  ${t.muted(formatBytes(ref.size))}`);
+            }
+            logger.print(t.muted(`\n${doomed.length} session${doomed.length === 1 ? "" : "s"}, ` +
+                `${formatBytes(doomed.reduce((n, f) => n + f.size, 0))} — run without \`--dry-run\` to delete`));
+            return;
+        }
+        // No `activeSessionId`: there is no session open in this process. That is
+        // the whole difference between running prune from here and running it
+        // from `SessionLog.open`.
+        const result = pruneSessions(cwd, { sessions: config.sessions });
+        if (result.removed.length === 0) {
+            logger.print(t.muted("nothing to prune"));
+        }
+        else {
+            logger.print(`${t.success("pruned")} ${result.removed.length} session${result.removed.length === 1 ? "" : "s"} ` +
+                `(${formatBytes(result.bytesFreed)}), ${result.kept} kept`);
+        }
+        if (result.failed > 0) {
+            logger.warn(`${result.failed} session file${result.failed === 1 ? "" : "s"} could not be deleted`);
+        }
+    });
+    cmd
+        .command("rm <id>")
+        .description("forget one session by id (or unambiguous id prefix)")
+        .action((id) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const cwd = process.cwd();
+        // Resolved through the SAME matcher `--resume` uses, so the id that names
+        // a session to resume is the id that names it to delete. An ambiguous
+        // prefix is refused rather than resolved to "the newest" — this is the
+        // one command here that cannot be undone.
+        const matches = matchSessionRefs(listSessionRefs(cwd), id);
+        if (matches.length > 1) {
+            throw usageError(`\`${id}\` matches more than one session`, [
+                `did you mean one of: ${matches.map((m) => shortId(m.sessionId)).join(", ")}?`,
+            ]);
+        }
+        if (matches.length === 0) {
+            throw usageError(`no session \`${id}\` in this project`, [
+                "run `cruxy sessions` to see what is here",
+                "sessions are per-directory; check you are in the right one",
+            ]);
+        }
+        try {
+            unlinkSync(matches[0].file);
+        }
+        catch (err) {
+            throw usageError(`could not delete session ${shortId(matches[0].sessionId)}`, [`${matches[0].file}: ${err.message}`]);
+        }
+        logger.print(`${t.success("deleted")} session ${shortId(matches[0].sessionId)}`);
+    });
+    return cmd;
+}
+/** The bounds in force, so a listing explains itself without a config read. */
+function printPolicy(sessions, t) {
+    if (!sessions.enabled) {
+        logger.print(t.muted("persistence is off (`sessions.enabled = false`) — nothing new is recorded"));
+        return;
+    }
+    logger.print(t.muted(`keeping the newest ${sessions.retention}, and anything touched in the last ${sessions.maxAgeDays} days`));
+}

package/dist/cli/program.js

@@ -19,8 +19,10 @@ import { rollbackCommand } from "./commands/rollback.js";
 import { testCommand } from "./commands/test.js";
 import { hooksCommand } from "./commands/hooks.js";
 import { memoryCommand } from "./commands/memory.js";
+import { limitsCommand } from "./commands/limits.js";
 import { usageCommand } from "./commands/usage.js";
 import { mcpCommand } from "./commands/mcp.js";
+import { sessionsCommand } from "./commands/sessions.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -54,7 +56,9 @@ export function buildProgram() {
     program.addCommand(hooksCommand());
     program.addCommand(memoryCommand());
     program.addCommand(usageCommand());
+    program.addCommand(limitsCommand());
     program.addCommand(mcpCommand());
+    program.addCommand(sessionsCommand());
     // Default action: bare `cruxy` opens the TUI; `cruxy <message>` opens it and
     // runs that message as the first turn. Operands reach here only when they
     // matched no subcommand, so a bare token is a MESSAGE by default — only a

package/dist/cli/repl.js

@@ -116,6 +116,28 @@ async function drainJobApprovals(session) {
     logger.print(theme.muted(`\n${theme.glyph.bullet} a background job needs your approval:`));
     await jobs.serviceApprovals();
 }
+/**
+ * Surface a pool denial a background job died on (cli#245) — the same idle
+ * point the approval drain uses, and for the same reason: the foreground owns
+ * the terminal here, with no live region painting and no readline interface
+ * holding stdin.
+ *
+ * WHY THE FOREGROUND IS TOLD AT ALL. A 429 is a statement about a denominator
+ * the job shares with this session's own next turn, so the job's death is
+ * already the answer to a question the user is about to ask. Without this the
+ * job fails off-screen — `/jobs` would show it, if the user thought to look —
+ * and the next turn walks into its own refusal, having been told nothing.
+ * Printed through the shared error formatter so `window`, when it recovers, and
+ * whether mira is still open all survive, exactly as they do on the foreground
+ * path.
+ */
+function drainJobPoolDenial(session) {
+    const denial = session.jobs?.takePoolDenial();
+    if (!denial)
+        return;
+    logger.print(theme.muted(`\n${theme.glyph.bullet} a background job stopped:`));
+    printCommandError(replOutput, denial);
+}
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
  * commands or run a turn, repeat. Assistant text and tool-call progress stream
@@ -143,6 +165,9 @@ async function replLoop(session, io, renderer, checkpoints, slashCommands = [])
         // prompt. Done here (foreground idle, no readline interface live) so a job's
         // prompt never contends with the line reader.
         await drainJobApprovals(session);
+        // Same point, same reason: a job the weighted pool refused (cli#245). The
+        // next turn is about to draw on the window that just refused it.
+        drainJobPoolDenial(session);
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
         if (line === null) {

package/dist/cli/session-factory.js

@@ -365,7 +365,8 @@ opts = {}) {
     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
+    // the orchestrator refuses to dispatch a fan-out (or a single spawn) it cannot
+    // cover; the job manager refuses a background job it cannot. Four
     // 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
@@ -378,6 +379,21 @@ opts = {}) {
     // Outside `resumeLineAfterApproval`, so the live region is restored
     // before a preview block is committed into it.
     previewSilentApprovals(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), renderer), checkpoints, workspace), approvalMutex, cwd);
+    // THE LATE-BINDING HANDLE FOR THE SESSION BUILT AT THE END OF THIS FUNCTION.
+    //
+    // Declared here, above the first construction that needs it, rather than down
+    // beside the plan wiring it was written for. Three things now late-bind to the
+    // session — the approval policy's live mode read, and (cli#244) the job
+    // manager's session id — and the session cannot exist yet because it needs the
+    // ctx, the orchestrator and the job manager that are built between here and
+    // there.
+    //
+    // `autoApprove`: the policy has to read the LIVE mode, since the user can
+    // leave auto-approve between two actions of a single turn. Before the session
+    // exists there is nothing to approve, so the `false` fallback is a closed door
+    // rather than a gap.
+    const holder = {};
+    const autoApprove = () => holder.session?.getAutoApprove() ?? false;
     // Subagent orchestration (C.14): spawn_subagent goes on the main registry
     // only when depth allows (maxDepth 0 disables the feature structurally).
     // Registered before the plan wiring so plan-mode execution steps can
@@ -406,7 +422,6 @@ opts = {}) {
         makeChildApproval: () => gate(new ApprovalService({
             cwd,
             interactive: ttyInteractive,
-            io,
             policy: new InteractivePolicy(new SessionAllowlist(), io, autoApprove),
         })),
     });
@@ -432,6 +447,20 @@ opts = {}) {
             approvalMutex,
             foregroundInteractive: ttyInteractive,
             promptIO: io,
+            // The SAME budget the turn and the fan-out seam ask (cli#245). A job
+            // drawing on the weighted pool with no admission check was the last
+            // surface running `runAgent` that neither asked it nor moved it.
+            budget: sessionBudget,
+            // ...and the SAME usage sink the session's turns publish through
+            // (cli#244), so a job's spend is counted by `/usage` and not only by
+            // `/budget`. A job gets a record of its own because it can outlive the
+            // turn that launched it; see the note on `JobManagerDeps.onRunUsage`.
+            onRunUsage,
+            // Read lazily: the session is constructed below and does not exist yet.
+            // Without this the job's record persists with no `sessionId` and is then
+            // invisible to in-session `/usage` and to `--session` — on disk, and
+            // unreadable by the two surfaces most likely to look for it.
+            sessionId: () => holder.session?.sessionId,
         })
         : undefined;
     const jobTool = jobManager ? makeRunInBackgroundTool(jobManager) : undefined;
@@ -465,19 +494,11 @@ opts = {}) {
     // One allowlist shared by the plan-approval prompt and the per-action gate, so
     // a grant recorded during execution is honored by U.3's own check.
     const allowlist = new SessionAllowlist();
-    // Late-bound to the session constructed below. The policy has to read the LIVE
-    // mode — the user can leave auto-approve between two actions of a single turn
-    // — and the session cannot exist yet because it needs the ctx this policy is
-    // wired into. Before it exists there is nothing to approve, so the `false`
-    // fallback is a closed door rather than a gap.
-    const holder = {};
-    const autoApprove = () => holder.session?.getAutoApprove() ?? false;
     const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io, autoApprove));
     const approval = new ApprovalService({
         cwd,
         interactive: ttyInteractive,
         policy: planPolicy,
-        io,
     });
     const ctx = {
         cwd,