@cruxy/cli 1.10.0 → 1.11.0

package/README.md

@@ -272,7 +272,7 @@ branch on them:
 | `0`  | success    | —                                                                                                                                                                                                    |
 | `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                                                                                                   |
 | `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`, `CRUXY_E_PLAN_INVALID`, `CRUXY_E_PLAN_REVISION_LIMIT`, `CRUXY_E_CHECKPOINT_NOT_FOUND` |
-| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                                                                                                     |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`, `CRUXY_E_CONFIG_NOT_FOUND`                                                                                                                         |
 | `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                                                                                                             |
 | `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                                                             |
 | `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_REQUEST_REJECTED`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                   |

package/dist/agent/session.js

@@ -617,6 +617,17 @@ export class Session {
         // its effort can land. That matters more here than on the main loop: a
         // summarize call reasoning at `high` is exactly the kind of silent spend a
         // per-request record exists to expose.
+        //
+        // IT LANDS, BUT NOT UNDER THIS CLASS. No `origin` is passed here, so the
+        // entry takes the turn collector's default `"turn"` — which is correct
+        // (`UsageEntry.origin` names the main loop and its compaction as one thing,
+        // so `runCount` keeps meaning "turns") and which also means the effort
+        // above is filed indistinguishably from the triggering turn's own. The
+        // record exposes the SPEND; it does not attribute it to `summarize`.
+        // cli#195 wanted exactly that attribution, to justify a per-task-class
+        // effort floor from collected data, and closed when it turned out the shape
+        // of the record — not the size of the sample — withholds it. Anything that
+        // needs to isolate compaction's effort has to change the record first.
         onRequestUsage?.({
             tier: servedTier ?? routed?.tier,
             ...(routingMode !== undefined ? { routingMode } : {}),

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/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,7 +1,7 @@
 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, defaultPromptIO, InteractivePolicy, SessionAllowlist, } from "../../approval/index.js";
@@ -92,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/run.js

@@ -12,7 +12,7 @@ import { SessionLog, listSessions, loadResume, resolveSessionId, resumePicker, s
  * 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 { 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";
@@ -24,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";
@@ -135,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

package/dist/cli/commands/sessions.js

@@ -88,7 +88,8 @@ export function sessionsCommand() {
             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"));
+                logger.print(t.muted("no sessions to prune"));
+                printJobLogCaveat(t);
                 return;
             }
             for (const ref of doomed) {
@@ -97,6 +98,7 @@ export function sessionsCommand() {
             }
             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
@@ -104,12 +106,23 @@ export function sessionsCommand() {
         // from `SessionLog.open`.
         const result = pruneSessions(cwd, { sessions: config.sessions });
         if (result.removed.length === 0) {
-            logger.print(t.muted("nothing to prune"));
+            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`);
         }
@@ -146,6 +159,18 @@ export function sessionsCommand() {
     });
     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) {

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

@@ -22,8 +22,9 @@ 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 { logsCommand } from "./commands/logs.js";
 import { sessionsCommand } from "./commands/sessions.js";
-import { loadConfig } from "../config/index.js";
+import { loadConfig, setCliConfigPath } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
     const program = new Command();
@@ -36,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());
@@ -59,6 +72,7 @@ export function buildProgram() {
     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/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/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];
 }