@cruxy/cli 1.9.0 → 1.11.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/command-catalog.js

@@ -94,7 +94,11 @@ export const COMMAND_CATALOG = [
         args: "[<n> | off]",
     },
     { name: "/jobs", summary: "list background jobs and their status" },
-    { name: "/logs", summary: "show a background job's log", args: "<id>" },
+    {
+        name: "/logs",
+        summary: "show a background job's log (falls back to a retained one on disk)",
+        args: "<id>",
+    },
     { name: "/cancel", summary: "cancel a background job", args: "<id>" },
     {
         name: "/add-root",

package/dist/cli/commands/config.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import { configKeyUnknown, shouldUseColor } from "../../errors/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { logger } from "../../utils/logger.js";
-import { loadConfig, getPath, setValue, initConfig, globalConfigPath, findProjectConfig, } from "../../config/index.js";
+import { cliConfigPathInEffect, loadConfig, getPath, setValue, initConfig, globalConfigPath, findProjectConfig, } from "../../config/index.js";
 export function configCommand() {
     const cmd = new Command("config").description("manage cruxy configuration");
     cmd
@@ -44,8 +44,23 @@ export function configCommand() {
         .action(() => {
         const t = themeForColor(shouldUseColor(process.stdout));
         const project = findProjectConfig();
-        logger.print(`${t.strong("global:")}  ${globalConfigPath()}`);
-        logger.print(`${t.strong("project:")} ${project ?? t.muted("(none found)")}`);
+        // Read the flag rather than calling `loadConfig`, deliberately: this is
+        // the command you run WHEN the config is broken, so it must stay total —
+        // loading here would make `cruxy config path` fail for exactly the
+        // invalid or unreadable file the user is trying to locate.
+        const explicit = cliConfigPathInEffect();
+        logger.print(`${t.strong("global:")}   ${globalConfigPath()}`);
+        logger.print(`${t.strong("project:")}  ${project === null
+            ? t.muted("(none found)")
+            : explicit === null
+                ? project
+                : // Discovery still FOUND it; the explicit file replaced it. Saying
+                    // so beats hiding the line, which would read as "no project
+                    // config exists" and send someone hunting for a file they have.
+                    `${project} ${t.muted("(superseded by --config)")}`}`);
+        if (explicit !== null) {
+            logger.print(`${t.strong("explicit:")} ${explicit}`);
+        }
     });
     cmd
         .command("init")

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/logs.js

@@ -0,0 +1,149 @@
+import { Command } from "commander";
+import { shouldUseColor, usageError } from "../../errors/index.js";
+import { INTERRUPTED, jobLogFilesByRecency, matchJobLogs, readJobLog, readJobLogTerminal, } from "../../jobs/log-store.js";
+import { relativeAge, shortId } from "../../session/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { formatBytes } from "../../utils/disk.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy logs` (#172 item 1) — read back what a background job said.
+ *
+ * ## Why this had to be a command and not just a nicer `/logs`
+ *
+ * Both existing readers — the in-session `/logs <id>` and the Tasks view — go
+ * through `JobManager.logs()` to the in-memory ring buffer, so both need a live
+ * `JobManager` holding the live job map. `requireJob` throws
+ * `CRUXY_E_JOB_NOT_FOUND` on anything else, which means neither surface can so
+ * much as NAME a job from a session that has ended. Persisting the log without
+ * a reader that works out of process would have been a writer talking to
+ * itself: the entire case this exists for is the session that is gone.
+ *
+ * ## It is a post-mortem. It is not a job that survived
+ *
+ * Say this plainly wherever a user can see it, because the alternative reading
+ * is the first bug someone files. A background job is an in-process agent loop;
+ * `run.ts` calls `cancelAll("session exit")` on the way out and `orphan.test.ts`
+ * pins that this kill-tree's the whole process group. Nothing resumes, nothing
+ * reattaches, and no job is running behind this command. What survived is the
+ * transcript of what the job said before it stopped.
+ *
+ * Shaped after `cruxy sessions`, and not by coincidence: same tree, same
+ * per-project scoping via `projectDir`, same cheap `readdir`+`stat` scan that
+ * bounds work before any file is opened, and the same id-prefix matcher, so an
+ * id that names a thing in one command names it in the other.
+ */
+export function logsCommand() {
+    const cmd = new Command("logs")
+        .argument("[id]", "job id, or an unambiguous prefix")
+        // The one-line description is bounded to 80 chars by the U.8 voice rule, so
+        // the caveat that actually matters lives in the help body below, where it
+        // has room to be unambiguous rather than merely short.
+        .description("read a finished background job's log — a post-mortem")
+        .addHelpText("after", "\nA background job never outlives the session that dispatched it: leaving a\n" +
+        "session cancels every live job and kills its process tree. These logs are\n" +
+        "what a job SAID before it stopped — nothing here is running, and nothing\n" +
+        "resumes. Failed and interrupted runs are kept; a job that finished cleanly\n" +
+        "has its log swept at the next start.\n")
+        .option("--all", "list every retained log, not just the newest 20")
+        .action((id, opts) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const cwd = process.cwd();
+        const refs = jobLogFilesByRecency(cwd);
+        if (id === undefined) {
+            listLogs(refs, Boolean(opts.all), t);
+            return;
+        }
+        const matches = matchJobLogs(refs, id);
+        if (matches.length > 1) {
+            throw usageError(`\`${id}\` matches more than one job log`, [
+                `did you mean one of: ${matches.map((m) => m.jobKey).join(", ")}?`,
+            ]);
+        }
+        if (matches.length === 0) {
+            throw usageError(`no retained log for job \`${id}\` in this project`, [
+                "run `cruxy logs` to see what is here",
+                "logs are per-directory; check you are in the right one",
+                "a job that finished cleanly has its log swept — only failed and interrupted runs are kept",
+            ]);
+        }
+        const log = readJobLog(matches[0].file);
+        if (log === null) {
+            throw usageError(`\`${matches[0].file}\` is not a readable job log`, [
+                "it may have been truncated before its first line was written",
+            ]);
+        }
+        printLog(log, t);
+    });
+    return cmd;
+}
+/** The listing: one row per retained log, newest first. */
+function listLogs(refs, all, t) {
+    if (refs.length === 0) {
+        logger.print(t.muted("no retained background-job logs for this project"));
+        printPolicy(t);
+        return;
+    }
+    // Bounded to 20 unless asked, matching `cruxy sessions`. The per-row cost
+    // here is a TAIL read and not a full one — the listing shows a status, not a
+    // transcript, and `readJobLogTerminal` is the whole of what that needs.
+    const shown = all ? refs : refs.slice(0, 20);
+    const total = refs.reduce((n, r) => n + r.size, 0);
+    for (const ref of shown) {
+        const status = readJobLogTerminal(ref.file);
+        logger.print(`${t.accent(ref.jobKey.padEnd(16))}  ${t.muted(shortId(ref.sessionKey).padEnd(8))}  ` +
+            // PAD FIRST, COLOUR SECOND. `padEnd` counts the escape bytes a themed
+            // string carries, so colouring before padding makes every coloured
+            // column a different width from the plain ones beside it.
+            `${statusText(status.padEnd(11), t)}  ` +
+            `${t.muted(relativeAge(new Date(ref.mtimeMs).toISOString()).padEnd(9))}  ` +
+            `${t.muted(formatBytes(ref.size).padStart(9))}`);
+    }
+    if (shown.length < refs.length) {
+        logger.print(t.muted(`\n… and ${refs.length - shown.length} more — pass \`--all\` to list every one`));
+    }
+    logger.print(t.muted(`\n${refs.length} log${refs.length === 1 ? "" : "s"}, ${formatBytes(total)}`));
+    printPolicy(t);
+}
+/** One log, in full. */
+function printLog(log, t) {
+    logger.print(`${t.strong(log.jobId)}  ${statusText(log.status, t)}  ${t.muted(log.label)}`);
+    logger.print(t.muted(`session ${shortId(log.sessionId)} · started ${relativeAge(log.startedAt)}` +
+        (log.endedAt !== undefined
+            ? ` · ended ${relativeAge(log.endedAt)}`
+            : "") +
+        (log.iterations !== undefined ? ` · ${log.iterations} turn(s)` : "")));
+    if (log.error !== undefined)
+        logger.print(t.danger(log.error));
+    logger.print("");
+    for (const line of log.lines) {
+        logger.print(line.stream === "err" ? t.danger(line.text) : line.text);
+    }
+    // The truncation notice belongs AFTER the lines, because that is where the
+    // truncation happened. Note what is NOT printed here: `/logs`'s "… N earlier
+    // line(s) rolled off". That sentence is true of the ring buffer and false of
+    // this file — streaming means everything up to the cap is present — and
+    // `PersistedJobLog` has no `dropped` field precisely so it cannot be said.
+    if (log.truncatedAt !== undefined) {
+        logger.print(t.muted(`\n… log capped at ${log.truncatedAt} lines (\`jobs.logFileLines\`) — later output was not recorded`));
+    }
+    if (log.status === INTERRUPTED) {
+        logger.print(t.muted("\n(interrupted — this log has no terminal record, so the process was " +
+            "killed while the job was still running; the job did not survive it)"));
+    }
+}
+/**
+ * A status, coloured by whether anyone needs to look at it. Accepts an
+ * already-padded string: see the call site for why the padding cannot come
+ * after the colour.
+ */
+function statusText(status, t) {
+    const bare = status.trim();
+    if (bare === "failed" || bare === INTERRUPTED)
+        return t.danger(status);
+    return t.accent(status);
+}
+/** What this directory keeps, so a listing explains itself. */
+function printPolicy(t) {
+    logger.print(t.muted("keeping failed and interrupted runs; a job that finished cleanly has its log swept at the next start"));
+    logger.print(t.muted("these are post-mortems — a background job never outlives the session that dispatched it"));
+}

package/dist/cli/commands/pr.js

@@ -1,10 +1,10 @@
 import { Command } from "commander";
 import { createProvider } from "@cruxy/sdk";
 import { logger } from "../../utils/logger.js";
-import { loadConfig, resolveApiKey } from "../../config/index.js";
+import { apiKeyEnvVar, 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,
@@ -83,12 +92,3 @@ export function prCommand() {
         logger.print(t.accent(outcome.url));
     });
 }
-/** Environment variable that holds the API key for a provider. */
-function apiKeyEnvVar(provider) {
-    switch (provider) {
-        case "openai":
-            return "OPENAI_API_KEY";
-        default:
-            return "CRUXY_API_KEY";
-    }
-}

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 { classifyCredentialLifetime, globalDir, loadConfig, readCredentialMeta, 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 { apiKeyEnvVar, classifyCredentialLifetime, configSourceFile, 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";
@@ -18,7 +24,7 @@ import { DEFAULT_MODE, } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
 import { ContextGauge, createKeyLease, createGitView, createOverviewView, createPermissionsView, createSettingsView, createTasksView, runTui, TuiRenderer, WorkspaceDiskCache, WorkspaceGitCache, } from "../../tui/index.js";
 import { buildAgentSession } from "../session-factory.js";
-import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
+import { maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
 import { connectMcpTools, deferredSiblingServers, resetMcpServices, } from "../../mcp/index.js";
 import { defaultPromptIO } from "../../approval/index.js";
@@ -129,7 +135,10 @@ export async function executeRun(promptParts, opts) {
     const { config, sources } = loaded;
     let apiKey = resolveApiKey(config.model.provider);
     logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
-    logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+    // `configSourceFile`, not `project ?? global`: with `--config` in play there
+    // is no project layer, so the old fallback printed the GLOBAL path — or
+    // "defaults" — for a file it had just loaded (#289).
+    logger.info(t.muted(`config:  ${configSourceFile(sources) ?? "defaults"}`));
     // Multi-root honesty (JC-6/C.26): reads fan every root. With per-root
     // checkpoints active (C.26 step 3), writes fan every root too — each is
     // checkpointed and rollback-able. With checkpoints DISABLED, a non-primary
@@ -340,11 +349,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);
     }