@cruxy/cli 1.8.1 → 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/login.js

@@ -5,15 +5,27 @@ import { logger } from "../../utils/logger.js";
 import { loadConfig } from "../../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
 /**
- * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
- * of onboarding (always, even if a key already resolves — this is how you
- * re-key / switch), validates it live, and persists it to the credentials store.
+ * `cruxy login` — sign in and persist a credential on demand (U.6). Runs the key
+ * step of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch) and persists the result to the credentials store.
  * Non-interactive invocations fail loud rather than hang.
+ *
+ * THE DEFAULT IS THE DEVICE FLOW: approve in a browser, and the gateway mints a
+ * subscription-bucket credential that draws on the plan pool the same human's
+ * web chat and desktop already use. A pasted key cannot be one — the admin
+ * issue-key route it comes from refuses to produce that kind — so the paste path
+ * is kept as a fallback rather than the front door.
+ *
+ * `--paste` keeps that fallback reachable, because the device flow cannot serve
+ * every case: an air-gapped machine has no browser to approve in, and someone
+ * deliberately using a long-lived admin key does not want a 90-day device
+ * credential written over it.
  */
 export function loginCommand() {
     return new Command("login")
-        .description("set or replace your API key (validated, saved to ~/.cruxy)")
-        .action(async () => {
+        .description("set or replace your cruxy credential (saved to ~/.cruxy)")
+        .option("--paste", "paste an existing API key instead of approving in a browser")
+        .action(async (opts) => {
         const t = themeForColor(shouldUseColor(process.stdout));
         if (!process.stdin.isTTY) {
             logger.print(t.muted("cruxy login is interactive — run it in a terminal, or export your key as an environment variable."));
@@ -27,6 +39,7 @@ export function loginCommand() {
             forceKey: true,
             offerFirstWin: false,
             offerScaffold: false,
+            preferPaste: opts.paste === true,
             io: defaultOnboardingIO(),
             deps: createDefaultDeps({ config, cwd: process.cwd() }),
         });

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,8 +5,14 @@ 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;
-import { globalDir, loadConfig, resolveApiKey } from "../../config/index.js";
+/**
+ * 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";
 import { themeForColor } from "../../theme/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);
     }
@@ -388,13 +404,26 @@ export async function executeRun(promptParts, opts) {
     // The cache is still attached without a key so the panel can say "not signed
     // in" — a fact worth stating, and one that costs no request to establish.
     const limitsKey = config.model.provider === "cruxy" ? apiKey : undefined;
+    // The stored expiry of the credential in use, read lazily. It is what lets a
+    // 401 be reported as "your sign-in expired" instead of "your key is wrong" —
+    // the gateway refuses both identically and will not say which.
+    const credentialExpiresAt = () => readCredentialMeta(config.model.provider)?.expiresAt;
     const limits = new LimitsCache(limitsKey === undefined
         ? undefined
         : (signal) => new LimitsClient({
             apiKey: limitsKey,
             gatewayUrl: config.cruxy.gatewayUrl,
-        }).read(signal));
+        }).read(signal), { credentialExpiresAt });
     tui?.attachLimits(limits);
+    // Say it BEFORE the session starts, while a re-login is a 30-second detour
+    // rather than an interruption. A device credential is minted with a finite
+    // lifetime and the gateway echoes it back precisely so a client can do this;
+    // the alternative is the user meeting their expiry mid-turn, as a 401.
+    //
+    // Only when we actually know: an absent or unparseable expiry classifies as
+    // `unknown` and says nothing, which is the right answer for every pasted key
+    // and every credential stored before expiries were recorded.
+    noteCredentialExpiry(credentialExpiresAt());
     // The SAME cache backs the session's weighted-token budget (P10 track 3), so
     // the rail's headroom bar and `/budget`'s server line are one reading rather
     // than two probes that can disagree — and so admission control at the fan-out
@@ -535,3 +564,24 @@ function printRunUsage(record) {
     const t = themeForColor(shouldUseColor(process.stdout));
     logger.print(renderSummary(summarizeRuns([record]), t));
 }
+/**
+ * Warn, once per run and before the session starts, that the stored credential
+ * is about to expire.
+ *
+ * ONLY IN THE `expiring` WINDOW. `live` is silent because a warning 80 days out
+ * is noise that trains people to ignore the line, and `expired` is silent here
+ * because a request is about to fail with a far better message than a preamble
+ * could give — `authExpired` names the date and the fix. `unknown` is silent
+ * because it is the honest state for every pasted key and every credential
+ * stored before expiries were recorded, and nagging those users about a lifetime
+ * nobody ever stated is exactly the false alarm this whole distinction exists to
+ * avoid.
+ */
+function noteCredentialExpiry(expiresAt) {
+    const lifetime = classifyCredentialLifetime(expiresAt);
+    if (lifetime.state !== "expiring")
+        return;
+    const t = themeForColor(shouldUseColor(process.stdout));
+    const days = Math.max(1, Math.round(lifetime.msRemaining / 86_400_000));
+    logger.print(t.warning(`your cruxy sign-in expires in ${days} day${days === 1 ? "" : "s"}`) + t.muted(" — run `cruxy login` to renew it"));
+}

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) {