@cruxy/cli 1.9.0 → 1.11.0

package/dist/cli/commands/sessions.js

@@ -0,0 +1,181 @@
+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("no sessions to prune"));
+                printJobLogCaveat(t);
+                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`));
+            printJobLogCaveat(t);
+            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("no sessions to prune"));
+        }
+        else {
+            logger.print(`${t.success("pruned")} ${result.removed.length} session${result.removed.length === 1 ? "" : "s"} ` +
+                `(${formatBytes(result.bytesFreed)}), ${result.kept} kept`);
+        }
+        // REPORTED SEPARATELY, and reported at all, because this run deletes
+        // them: `pruneSessions` sweeps the job logs a session no longer needs
+        // (#172 item 1), and a prune that removed files while printing "nothing
+        // to prune" would be exactly the unauditable retention `cruxy sessions`
+        // exists to prevent. Counted apart from sessions rather than folded in —
+        // a job log is not a conversation, and one number for both would make it
+        // impossible to tell which was taken.
+        if (result.jobLogsRemoved > 0) {
+            logger.print(`${t.success("swept")} ${result.jobLogsRemoved} background-job log${result.jobLogsRemoved === 1 ? "" : "s"} ` +
+                `(${formatBytes(result.jobLogBytesFreed)})`);
+        }
+        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;
+}
+/**
+ * What the dry run does NOT show.
+ *
+ * The preview re-derives the doomed sessions from the same two bounds without
+ * going near a delete, which is the point of it — but the job-log sweep lives
+ * inside `pruneSessions`, so there is no way to preview it that does not either
+ * duplicate its rules or run them. Saying so is better than a preview that
+ * quietly under-reports what the real run will remove.
+ */
+function printJobLogCaveat(t) {
+    logger.print(t.muted("\nbackground-job logs are swept by the same run and are not previewed here — `cruxy logs` lists them"));
+}
+/** 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/onboard.js

@@ -9,15 +9,6 @@ import { buildAgentSession } from "./session-factory.js";
  * `run`/`program`/`login`/`init` thin: they decide *when* to onboard; this builds
  * the production wiring (live validation, credential persistence, first-win run).
  */
-/** The env var that holds the key for a provider (for the fail-loud message). */
-export function apiKeyEnvVar(provider) {
-    switch (provider) {
-        case "openai":
-            return "OPENAI_API_KEY";
-        default:
-            return "CRUXY_API_KEY";
-    }
-}
 /** Run one first-win task end-to-end against the just-saved key. */
 export async function runFirstWinTask(config, cwd, prompt) {
     const apiKey = resolveApiKey(config.model.provider);

package/dist/cli/program.js

@@ -19,9 +19,12 @@ 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 { loadConfig } from "../config/index.js";
+import { logsCommand } from "./commands/logs.js";
+import { sessionsCommand } from "./commands/sessions.js";
+import { loadConfig, setCliConfigPath } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
     const program = new Command();
@@ -34,12 +37,24 @@ export function buildProgram() {
         .option("--verbose", "shorthand for --log-level debug")
         .option("--resume [id]", "resume a saved session by id; omit the id to pick from recent sessions");
     // Apply global options as early as possible.
+    //
+    // This hook is registered on the ROOT program, so `thisCommand` is the root
+    // whichever subcommand is running, and it fires before every action handler —
+    // including the root's own. That makes it the one place a global option can
+    // be applied once and be true for the whole invocation.
     program.hook("preAction", (thisCommand) => {
         const opts = thisCommand.opts();
         if (opts.verbose)
             logger.setLevel("debug");
         else if (opts.logLevel)
             logger.setLevel(opts.logLevel);
+        // `--config` was parsed and dropped here until #289: the flag reached
+        // `GlobalOpts` and `--help` and nothing else, so a user pointing it at a
+        // file got default behaviour and no signal. Recording it makes every
+        // `loadConfig()` in this process resolve that file — including the reads
+        // that cannot be passed one (see `setCliConfigPath`). Cleared when absent,
+        // so a program rebuilt in-process does not inherit a stale path.
+        setCliConfigPath(opts.config ?? null);
     });
     program.addCommand(runCommand());
     program.addCommand(configCommand());
@@ -54,7 +69,10 @@ export function buildProgram() {
     program.addCommand(hooksCommand());
     program.addCommand(memoryCommand());
     program.addCommand(usageCommand());
+    program.addCommand(limitsCommand());
     program.addCommand(mcpCommand());
+    program.addCommand(sessionsCommand());
+    program.addCommand(logsCommand());
     // 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-commands.js

@@ -14,7 +14,8 @@ import { compactTokens } from "../render/units.js";
 import { renderUnifiedDiff } from "../render/index.js";
 import { permissionsReportLines } from "../render/permissions-view.js";
 import { sessionStatusLines } from "../render/status-view.js";
-import { defaultExportName, exportMarkdown } from "../session/index.js";
+import { INTERRUPTED, jobLogFilesByRecency, matchJobLogs, readJobLog, } from "../jobs/log-store.js";
+import { defaultExportName, exportMarkdown, shortId, } from "../session/index.js";
 import { readDiskCapacitySync } from "../utils/disk.js";
 import { getGitInfo } from "../utils/git.js";
 import { currentBranch, diffAgainst, hasChanges } from "../vcs/git.js";
@@ -22,7 +23,7 @@ import { MODEL_CHOICES, describeModelChoice, parseModelChoice, } from "../routin
 import { loadUsage, runCountLabel, selectRuns, usageReport, } from "../usage/index.js";
 import { runGatedShell } from "../tools/shell/exec.js";
 import { addRootToWorkspace } from "../workspace/index.js";
-import { formatError, fromUnknown, isVerbose } from "../errors/index.js";
+import { CruxyError, ErrorCode, formatError, fromUnknown, isVerbose, } from "../errors/index.js";
 /**
  * Re-exported so the many callers that already reach for the catalogue through
  * this module keep working; the data itself lives in the leaf `command-catalog`
@@ -910,6 +911,8 @@ function handleJobLogs(input, ctx) {
     try {
         const log = jobs.logs(id);
         if (log.dropped > 0) {
+            // TRUE OF THE RING BUFFER, and said only here. The persisted log below
+            // streams, so this sentence is false about a file — see `JobLog.dropped`.
             out.print(t.muted(`… ${log.dropped} earlier line(s) rolled off`));
         }
         for (const line of log.lines) {
@@ -918,9 +921,49 @@ function handleJobLogs(input, ctx) {
         out.print(t.muted(`(${log.status})`));
     }
     catch (err) {
+        // FALL BACK TO DISK on an id this session has never heard of (#172 item 1).
+        // The live map only holds jobs THIS session dispatched, so after a
+        // `--resume` the ids a user is most likely to type are exactly the ones
+        // that miss — the job ran in the process that is now gone. Only
+        // JOB_NOT_FOUND falls through: a real failure must still fail loud.
+        if (CruxyError.is(err) &&
+            err.code === ErrorCode.JobNotFound &&
+            printPersistedJobLog(id, ctx)) {
+            return;
+        }
         printCommandError(out, err);
     }
 }
+/**
+ * Print a job log read back from disk, or report that there is none.
+ *
+ * Returns false when nothing on disk matches, so the caller can surface the
+ * original live-lookup error rather than replacing a precise "no such job in
+ * this session" with a vaguer one.
+ */
+function printPersistedJobLog(id, ctx) {
+    const { out } = ctx;
+    const t = out.theme;
+    const matches = matchJobLogs(jobLogFilesByRecency(process.cwd()), id);
+    if (matches.length !== 1)
+        return false;
+    const log = readJobLog(matches[0].file);
+    if (log === null)
+        return false;
+    out.print(t.muted(`(from disk — job ${log.jobId} ran in session ${shortId(log.sessionId)})`));
+    for (const line of log.lines) {
+        out.print(out.fit(line.stream === "err" ? t.danger(line.text) : line.text));
+    }
+    // No "rolled off" line: this came from the file, which holds everything up to
+    // the cap. The cap is the only thing worth reporting, and only if it was hit.
+    if (log.truncatedAt !== undefined) {
+        out.print(t.muted(`… log capped at ${log.truncatedAt} lines (\`jobs.logFileLines\`) — later output was not recorded`));
+    }
+    out.print(t.muted(log.status === INTERRUPTED
+        ? "(interrupted — no terminal record; the process was killed mid-job)"
+        : `(${log.status})`));
+    return true;
+}
 /** Cancel a job (`/cancel <id>`). */
 async function handleJobCancel(input, ctx) {
     const { out, session } = ctx;

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,

package/dist/config/manager.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { configInvalid, configParse, mcpProjectHeaders, } from "../errors/index.js";
-import { CruxyConfigSchema } from "./schema.js";
+import { configInvalid, configNotFound, configParse, mcpProjectHeaders, } from "../errors/index.js";
+import { CruxyConfigSchema, } from "./schema.js";
 import { globalConfigPath, findProjectConfig } from "./paths.js";
 import { readCredential } from "./credentials.js";
 function isPlainObject(v) {
@@ -90,6 +90,39 @@ function envOverrides() {
     }
     return out;
 }
+/**
+ * The `--config <path>` this process was invoked with, or null.
+ *
+ * PROCESS-WIDE RATHER THAN THREADED, because the flag is a property of the
+ * INVOCATION: every read of the config in one run must resolve the same file,
+ * and there are ~20 `loadConfig()` call sites. Two of them cannot take an
+ * argument at all — the credential-expiry probe in `src/index.ts` runs from the
+ * error boundary, after the command that would have carried the path has
+ * already thrown, and the Settings view's `reload` is a zero-argument callback
+ * held for a whole session. Threading would wire the sites that are easy to
+ * reach and leave those two reading a *different* config than the command they
+ * belong to, which is the same silent divergence this flag was filed for
+ * (#289).
+ *
+ * Set once from the `preAction` hook that already applies the other global
+ * options (`cli/program.ts`), alongside `logger.setLevel`. An explicit
+ * {@link LoadOptions.configPath} still wins, so a caller that names a file is
+ * unaffected.
+ */
+let cliConfigPath = null;
+/**
+ * Record the `--config <path>` for this process. Returns the previous value so
+ * a test can restore it; pass null to clear.
+ */
+export function setCliConfigPath(path) {
+    const previous = cliConfigPath;
+    cliConfigPath = path;
+    return previous;
+}
+/** The `--config <path>` in effect for this process, or null. */
+export function cliConfigPathInEffect() {
+    return cliConfigPath;
+}
 /**
  * Resolution order (later wins):
  *   schema defaults -> global file -> project file (or explicit) -> env vars
@@ -113,12 +146,21 @@ export function loadConfig(opts = {}) {
         merged = deepMerge(merged, layers.global);
         sources.global = gPath;
     }
-    if (opts.configPath) {
-        const obj = readJsonFile(opts.configPath);
-        rejectProjectScopeHeaders(obj, opts.configPath);
+    // `--config` (recorded process-wide) unless this caller named a file itself.
+    const configPath = opts.configPath ?? cliConfigPath ?? undefined;
+    if (configPath) {
+        // A named file that is not there is a MISTAKE, never a fall-through to
+        // discovery or defaults: silently running the default config for a path
+        // someone typed is precisely the failure #289 is about, wearing the other
+        // hat. The global and project layers are `existsSync`-guarded above because
+        // absence there is the normal case; here absence is the error.
+        if (!existsSync(configPath))
+            throw configNotFound(configPath);
+        const obj = readJsonFile(configPath);
+        rejectProjectScopeHeaders(obj, configPath);
         layers.explicit = obj;
         merged = deepMerge(merged, obj);
-        sources.explicit = opts.configPath;
+        sources.explicit = configPath;
     }
     else {
         const pPath = findProjectConfig(opts.cwd);
@@ -137,10 +179,28 @@ export function loadConfig(opts = {}) {
         const issues = result.error.issues
             .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
             .join("\n");
-        throw configInvalid(issues, sources.project ?? sources.global ?? undefined);
+        throw configInvalid(issues, configSourceFile(sources) ?? undefined);
     }
     return { config: result.data, sources, layers };
 }
+/**
+ * The file to NAME for the config as a whole — the nearest winning source, in
+ * the precedence order the merge itself used.
+ *
+ * `explicit` COMES FIRST, and that is the whole point: an explicit file
+ * REPLACES project discovery, so when `--config` is in play `sources.project`
+ * is null and a `project ?? global` fallback silently names the *global* file.
+ * A user fixing the field an error reports would then be editing a file that
+ * contributed nothing to it (#289).
+ *
+ * This is the whole-config counterpart to `originFile` in `effective.ts`, which
+ * answers the same question per key. It lives here, next to the `sources` it
+ * reads, so `loadConfig`'s own error path can use it without importing
+ * `effective.ts` (which imports this module).
+ */
+export function configSourceFile(sources) {
+    return sources.explicit ?? sources.project ?? sources.global ?? null;
+}
 /** Resolve a dot-path (e.g. "model.temperature") against a config object. */
 export function getPath(obj, path) {
     return path
@@ -205,13 +265,33 @@ export function resolveApiKey(provider) {
 function envApiKey(provider) {
     return process.env[apiKeyEnvVar(provider)];
 }
+/**
+ * Provider id → the environment variable its API key is read from.
+ *
+ * A TOTAL RECORD OVER `Provider`, not a switch with a default, because that is
+ * what makes the mapping self-maintaining: adding a provider to
+ * {@link ProviderSchema} makes this object a compile error until its env var is
+ * named. A `default:` arm silently answers `CRUXY_API_KEY` for a provider
+ * nobody has thought about yet, which is the failure mode #285 is named for —
+ * the copy that drifts is always the one telling the user where to put their
+ * key.
+ */
+const API_KEY_ENV_VAR = {
+    cruxy: "CRUXY_API_KEY",
+};
 /**
  * The environment variable a provider's API key is read from — the NAME only,
  * never the value, so a surface can say where a key would come from without
- * ever holding one. Exported so nothing has to restate this mapping: a second
- * copy would drift the moment a provider is added, and the copy that drifts is
- * always the one telling the user where to put their key.
+ * ever holding one.
+ *
+ * THE one definition. It was exported to prevent restatement and said so at the
+ * site, and two copies were written anyway (`cli/onboard.ts`,
+ * `cli/commands/pr.ts`), both carrying an `"openai"` branch that #284 had made
+ * unreachable — invisible because all three took `string`. The parameter is
+ * {@link Provider} now: an id the config layer would refuse no longer type-checks
+ * here, so the next such branch is a build failure rather than dead code that
+ * reads as live (#285).
  */
 export function apiKeyEnvVar(provider) {
-    return provider === "openai" ? "OPENAI_API_KEY" : "CRUXY_API_KEY";
+    return API_KEY_ENV_VAR[provider];
 }