peaks-loop 4.0.50 → 4.0.52

package/dist/cli/commands/codegraph-status-command.js

@@ -0,0 +1,299 @@
+// src/cli/commands/codegraph-status-command.ts
+//
+// `peaks codegraph status` — the two-axis integrity gate (exclude rules +
+// index coverage), its `--peaks-json` machine envelope, and the attribution
+// of upstream's `[OK] Index is up to date` line.
+//
+// Extracted verbatim from `codegraph-commands.ts` (rid
+// 2026-09-17-oversize-and-scale, D1 — the 800-line file-size cap). Every moved
+// line is byte-identical and no behaviour changed; `attributeUpstreamUpToDate
+// Line` stays importable from `codegraph-commands.ts`, which re-exports it.
+import { resolve } from 'node:path';
+import { createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized } from '../../services/codegraph/codegraph-service.js';
+import { CODEGRAPH_INTEGRITY_EXIT_CODE, inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent, renderCodegraphExcludeIntegrityLines } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE, CODEGRAPH_INDEX_STRICT_ENV_VAR, CODEGRAPH_REPAIR_INDEX_COMMAND, codegraphIndexIntegrityExitCode, inspectCodegraphIndexIntegrity, isCodegraphIndexStrictMode, renderCodegraphIndexIntegrityLines, resolveCodegraphIndexIntegrityVerdict } from '../../services/codegraph/codegraph-index-integrity.js';
+import { readCodegraphProjectInputs } from '../../services/codegraph/codegraph-exclude-reconciler.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { printCodegraphFailure, rewriteBareCodegraphHints, runCodegraphCommand } from './codegraph-command-runtime.js';
+const ANSI_SGR_PATTERN = /\x1b\[[0-9;]*m/g;
+/**
+ * Upstream `status` answers a different question than peaks-loop's
+ * integrity gate: upstream says "the on-disk graph matches the last scan"
+ * (true), peaks says "that graph covers the repository" (false when rules
+ * exclude tracked files). Both verdicts are correct, but an unqualified
+ * `[OK] Index is up to date` printed above our `[FAIL] ...` reads as
+ * "nothing to see here" — and the OK is the line the eye lands on first.
+ * The exit code and the JSON envelope are already right; only this line
+ * lies by juxtaposition.
+ *
+ * So: keep upstream's wording — the line stays recognizable, and the
+ * Files/Nodes counts around it are untouched — but drop the bare OK
+ * marker and name the only question it answers. Clean runs never reach
+ * this, so their output stays byte-identical.
+ *
+ * The match is anchored to THAT line. An earlier version keyed on
+ * `includes('up to date')`, which is content-blind: upstream prints other
+ * `[OK] ... are up to date` lines (a language-server or watcher line is the
+ * observed one), and each of those was rewritten into a claim about the
+ * INDEX — a misattribution introduced by a change whose entire purpose was
+ * to stop misleading output. Anything that is not the index line is passed
+ * through byte-for-byte, tail note and all.
+ */
+const INDEX_UP_TO_DATE_RE = /^\[OK\]\s+Index is up to date\b/i;
+export function attributeUpstreamUpToDateLine(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => {
+        const visible = line.replace(ANSI_SGR_PATTERN, '').trim();
+        if (!INDEX_UP_TO_DATE_RE.test(visible)) {
+            return line;
+        }
+        // Only the OK marker is downgraded and the attribution appended: the
+        // rest of the line — including whatever upstream wrote after it — is
+        // preserved, so nothing upstream actually said is replaced.
+        const withoutOk = visible.replace(/^\[OK\]\s*/, '');
+        return `[i] ${withoutOk} (upstream: matches the last scan only; repository coverage is answered below)`;
+    })
+        .join('\n');
+}
+/**
+ * `--peaks-json` machine report for `status`. Carries the upstream
+ * result AND the peaks-loop integrity verdict as one JSON document so a
+ * CI job can gate on `data.integrity.gap` / `data.integrity.rulesToRemove`
+ * without scraping human text.
+ *
+ * EXIT-CODE PRECEDENCE (decided here, mirrored on the human path, pinned
+ * by tests on BOTH axes):
+ *
+ *   1. upstream failed      → upstream's exit code. Ranked FIRST because
+ *      every gate's remedy assumes upstream can run, and because the
+ *      gate's own branches would otherwise MASK a real command failure:
+ *      under the advisory default a gap exits 0, so a "gate first" order
+ *      would turn "upstream failed + gap" into exit 0 — the gate hiding a
+ *      failure. The gate verdicts stay in `data` verbatim, so ranking
+ *      them lower hides nothing.
+ *   2. exclude gap          → 74 (`CODEGRAPH_INDEX_INCOMPLETE`).
+ *   3. index not evaluated  → 76 (`CODEGRAPH_INDEX_NOT_EVALUATED`): the
+ *      axis was attempted and failed, which is NOT "verified clean".
+ *   4. index gap            → 75 (`CODEGRAPH_INDEX_GAP`) in strict mode,
+ *      0 in the advisory default.
+ *
+ * The envelope still reports the finding in case 4 (`ok:false`, the same
+ * `code`, plus `indexIntegritySeverity: 'warning'`) — the policy governs
+ * the EXIT CODE, not whether the finding is visible. This mirrors the
+ * doctor's established convention: `ok:false` + `severity:'warning'`
+ * surfaces the finding without escalating the exit code.
+ */
+async function runCodegraphStatusJson(io, options, integrity, integrityWarning, indexIntegrity, indexIntegrityWarning, indexVerdict, strict) {
+    let result;
+    try {
+        result = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'status', project: options.project }));
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.status', error, true);
+        return true;
+    }
+    const upstream = {
+        exitCode: result.exitCode,
+        stdout: rewriteBareCodegraphHints(result.stdout).trimEnd(),
+        stderr: redactSensitiveErrorMessage(rewriteBareCodegraphHints(result.stderr)).trimEnd()
+    };
+    const upstreamFailed = result.exitCode !== null && result.exitCode !== 0;
+    const data = {
+        upstream,
+        integrity,
+        integrityWarning,
+        indexIntegrity,
+        indexIntegrityWarning,
+        indexIntegrityVerdict: indexVerdict,
+        // Only meaningful where there IS a finding: a `clean` or `not-applicable`
+        // axis has no severity, and reporting `'warning'` there would read as
+        // "something was wrong but advisory".
+        indexIntegritySeverity: indexVerdict === 'gap' ? (strict ? 'error' : 'warning') : null
+    };
+    if (upstreamFailed) {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(upstream.stderr || upstream.stdout || `codegraph exited with code ${String(result.exitCode)}`), data, ['Check the codegraph project path before retrying']), true);
+    }
+    else if (integrity?.gap === true) {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_INCOMPLETE', `codegraph index is incomplete: ${integrity.excludedTrackedCount} of ${integrity.trackedSourceCount} tracked source files are excluded by ${integrity.rulesToRemove.length} rule(s).`, data, ['Run `peaks codegraph repair-exclude --project <root>` to drop the offending rules and rebuild the index.']), true);
+    }
+    else if (indexVerdict === 'not-evaluated') {
+        // Distinct from the `ok` branch below on purpose: this axis produced
+        // NO verdict, and the envelope must not read as "index verified".
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_NOT_EVALUATED', `codegraph index integrity could not be evaluated: ${indexIntegrityWarning ?? 'unknown cause'}`, data, [
+            'The index was NOT measured — this is not a statement that the index is correct.',
+            'Re-run once the cause above is resolved.'
+        ]), true);
+    }
+    else if (indexVerdict === 'gap') {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_GAP', `codegraph index does not cover the repository: ${indexIntegrity?.includeGap.length ?? 0} extractor-supported tracked file(s) are not admitted by the config's include globs, and ${indexIntegrity?.deadRows.length ?? 0} index row(s) point at files that no longer exist.`, data, strict
+            ? [
+                'The index must admit every extractor-supported tracked file and hold no row for a path that is gone.',
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`
+            ]
+            : [
+                'Advisory: this gap is reported as a warning and the command exits 0.',
+                `Set ${CODEGRAPH_INDEX_STRICT_ENV_VAR}=1 to make it blocking (exit ${CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE}).`,
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`
+            ]), true);
+    }
+    else {
+        printResult(io, ok('codegraph.status', data), true);
+    }
+    if (upstreamFailed) {
+        process.exitCode = result.exitCode ?? 1;
+    }
+    return upstreamFailed;
+}
+/**
+ * `peaks codegraph status` with an integrity gate.
+ *
+ * The upstream status is still proxied verbatim (that is what the
+ * command has always done), but a clean upstream "index is up to date"
+ * is no longer sufficient: when git-tracked source files are being
+ * excluded by the config, or the index itself does not cover the
+ * repository, the command says so and names the rules and files.
+ *
+ * SEVERITY (user decision, option C): the exclude gate keeps its shipped
+ * blocking behaviour (exit 74); the index gate is ADVISORY by default and
+ * blocking only when `PEAKS_CODEGRAPH_INDEX_STRICT` is set. A detected
+ * gap is the finding either way — only the tag and the exit code move.
+ *
+ * Read-only by construction — it imports the integrity inspectors, never
+ * the repair writer. Fixing the config is `peaks codegraph init`
+ * (fresh) or `peaks codegraph repair-exclude` (explicit).
+ */
+export async function runCodegraphStatusCommand(io, options, asJson) {
+    let integrity = null;
+    let integrityWarning = null;
+    let indexIntegrity = null;
+    let indexIntegrityWarning = null;
+    const projectRoot = resolve(options.project);
+    const strict = isCodegraphIndexStrictMode();
+    // R12-1: the two axes have DIFFERENT applicability predicates, and folding
+    // them into the config's alone is how a db-present / config-absent project
+    // came to exit 0 in SILENCE — under `PEAKS_CODEGRAPH_INDEX_STRICT=1` too.
+    // "Could not evaluate" is a verdict; it may not be spelled the same way as
+    // "verified clean" merely because the read happened to be gated out.
+    //
+    //   - exclude axis: applicable iff `.codegraph/config.json` exists. The
+    //     config IS the subject of that axis, so with no config there is no
+    //     exclusion list in play — `not-applicable`, silent, as before.
+    //   - index axis: applicable iff `.codegraph/codegraph.db` exists — the
+    //     SAME predicate the doctor's `defaultProbe` uses
+    //     (`isCodegraphInitialized` in
+    //     `doctor-service/checks/codegraph-index-integrity.ts`), so the two
+    //     consumers now agree about when the axis is evaluable at all. The
+    //     index is the subject here and the config is only an INPUT it reads,
+    //     so a missing config is "could not evaluate" (exit 76, `[FAIL]`),
+    //     not "nothing to evaluate".
+    //
+    // The user's constraint holds either way: an absent config is LEGITIMATE
+    // for a project that never ran `peaks codegraph init` — with no db BOTH
+    // predicates are false and the command stays silent exactly as before.
+    const configPresent = isCodegraphExcludeConfigPresent(projectRoot);
+    const indexPresent = isCodegraphInitialized(projectRoot);
+    // The two axes are evaluated INDEPENDENTLY: an unreadable index must not
+    // blind the exclude verdict, and a malformed exclude list must not hide a
+    // stale index. Each failure degrades to its own warning.
+    if (configPresent || indexPresent) {
+        // Perf audit F1: both axes need the SAME tracked-file list and the SAME
+        // config, and reading them per-axis spawned `git ls-files` twice per
+        // command and re-ran the identical 32-glob `include` filter. Read once
+        // and hand the values to both inspectors through their deps seam.
+        let sharedInputs = null;
+        try {
+            sharedInputs = readCodegraphProjectInputs(projectRoot);
+        }
+        catch (error) {
+            // One read, two blind axes — they consume exactly these two inputs,
+            // so a failure here blinds both. Report it on both, rather than
+            // letting the second axis re-run the same failing read to find out.
+            // Each axis claims the failure only where it was applicable at all:
+            // an unreadable CONFIG is not an exclude-axis finding on a project
+            // that has no config by design.
+            if (configPresent) {
+                integrityWarning = getErrorMessage(error);
+            }
+            if (indexPresent) {
+                indexIntegrityWarning = getErrorMessage(error);
+            }
+        }
+        if (sharedInputs !== null) {
+            if (configPresent) {
+                try {
+                    integrity = inspectCodegraphExcludeIntegrity(projectRoot, sharedInputs);
+                }
+                catch (error) {
+                    integrityWarning = getErrorMessage(error);
+                }
+            }
+            // The index axis needs an index. A config without `codegraph.db` is a
+            // pre-init / dangling state, not a defect: there are no rows to be
+            // stale and nothing `include` withheld from a graph that does not exist.
+            if (indexPresent) {
+                try {
+                    indexIntegrity = inspectCodegraphIndexIntegrity(projectRoot, sharedInputs);
+                }
+                catch (error) {
+                    indexIntegrityWarning = getErrorMessage(error);
+                }
+            }
+        }
+    }
+    const indexVerdict = resolveCodegraphIndexIntegrityVerdict(indexIntegrity, indexIntegrityWarning);
+    const indexGap = indexVerdict === 'gap';
+    if (asJson === true) {
+        const upstreamFailed = await runCodegraphStatusJson(io, options, integrity, integrityWarning, indexIntegrity, indexIntegrityWarning, indexVerdict, strict);
+        // Upstream failure outranks both gates — and it already set the exit
+        // code to upstream's (see `runCodegraphStatusJson`).
+        if (upstreamFailed) {
+            return;
+        }
+    }
+    else {
+        // Only when a gate found a gap: upstream's `[OK] Index is up
+        // to date` answers "consistent with the last scan", and printing it
+        // unqualified right above our verdict tells the reader two opposite
+        // things at once. Clean runs get no transform and stay byte-identical.
+        const upstreamFailed = await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, false, integrity?.gap === true || indexGap ? attributeUpstreamUpToDateLine : undefined);
+        if (integrityWarning !== null) {
+            io.stdout(`[WARN] codegraph exclude integrity not evaluated: ${integrityWarning}`);
+        }
+        else if (integrity !== null) {
+            for (const line of renderCodegraphExcludeIntegrityLines(integrity)) {
+                io.stdout(line);
+            }
+        }
+        if (indexVerdict === 'not-evaluated') {
+            // `[FAIL]`, in every mode, because the command exits non-zero in
+            // every mode: the axis was attempted and failed, so this is not a
+            // statement about the index. Distinct wording from the gap line so
+            // the two can never be confused.
+            io.stdout(`[FAIL] codegraph index integrity could not be evaluated (the index was NOT measured): ${indexIntegrityWarning ?? 'unknown cause'}`);
+        }
+        else if (indexIntegrity !== null) {
+            for (const line of renderCodegraphIndexIntegrityLines(indexIntegrity, strict)) {
+                io.stdout(line);
+            }
+        }
+        // Upstream failure outranks both gates — and it already set the exit
+        // code to upstream's.
+        if (upstreamFailed) {
+            return;
+        }
+    }
+    // Gate precedence: exclude wins when both fire (it is the upstream cause,
+    // and repairing it also rebuilds the index the staleness axis is about).
+    // Then "not evaluated" outranks "gap", because an unmeasured axis must
+    // never be reported with the same status as a measured one. See
+    // `codegraphIndexIntegrityExitCode`.
+    const indexExitCode = codegraphIndexIntegrityExitCode(indexVerdict, strict);
+    if (integrity?.gap === true) {
+        process.exitCode = CODEGRAPH_INTEGRITY_EXIT_CODE;
+    }
+    else if (indexExitCode !== null) {
+        process.exitCode = indexExitCode;
+    }
+}

package/dist/cli/commands/core/memory-command.js

@@ -1,4 +1,4 @@
-import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult, VALID_PROJECT_MEMORY_KINDS } from '../../../services/memory/project-memory-service.js';
+import { describeMemoryBlockDrops, executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult, VALID_PROJECT_MEMORY_KINDS } from '../../../services/memory/project-memory-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 /** Derived from the canonical kind vocabulary — never hand-maintain a list here. */
@@ -19,7 +19,11 @@ export function registerMemoryCommand(program, io) {
         }
         try {
             const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: options.apply === true });
-            printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result)), options.json);
+            // A block that was found but not extracted must not vanish silently: the
+            // parser's rejection reasons ride the envelope's existing `warnings`
+            // channel (JSON: `warnings[]`; human: `warning: …` on stderr). `data` is
+            // unchanged — this adds no field to the summary.
+            printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result), describeMemoryBlockDrops(result.droppedBlocks)), options.json);
         }
         catch (error) {
             printResult(io, fail('memory.extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), {}, ['Check artifact paths and remove secrets before extracting memory']), options.json);

package/dist/cli/commands/job-commands.js

@@ -15,7 +15,51 @@ import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } fr
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { buildCostCheckEnvelope, runKarpathyCostCheck, } from '../../services/karpathy-cost/karpathy-cost-check-service.js';
 import { read24hState } from '../../services/24h-mode/store.js';
-import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
+import { codegraphRefreshNotice, refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
+// `printResult`'s third parameter is `asJson: boolean`. Each `job` subcommand
+// registers `--json` (see the `addJsonOption` calls below), so the flag to pass
+// it is `opts.json` — NEVER the whole options object. Commander types an
+// action's `opts` as `any`, so `printResult(io, envelope, opts)` type-checks
+// and is ALWAYS truthy: it forces the envelope branch and makes the
+// `warning: ` / `next: ` human rendering in `cli-helpers.ts` unreachable. That
+// is how the A2 codegraph-refresh warning ended up inside the JSON stdout
+// envelope instead of on stderr as `warning: `. `job progress` always passed
+// `opts.json`; the rest of this file did not, and E1 (2026-09-17) brought them
+// in line. Do not reintroduce the object form.
+function asJson(opts) {
+    return opts.json === true;
+}
+/**
+ * F1 (rid 2026-09-17-exit-code-truth): report a FAILED envelope **and** make the
+ * process exit non-zero.
+ *
+ * WHY THIS EXISTS. `printResult` (`src/cli/cli-helpers.ts`) renders a failed
+ * envelope — `CODE: message` + `nextActions` on stderr — but it does NOT set
+ * `process.exitCode`. Measured with the real CLI before this fix:
+ * `peaks job block --job-id j1 --slice-id nope --reason why` printed
+ * `SLICE_NOT_FOUND: …` on stderr and exited **0**, so CI and every script
+ * wrapping `peaks job` read the failure as success. Seven of this file's nine
+ * failure-reporting sites had that gap; only `job progress` set the code, and
+ * that was the file's one accidental precedent rather than a rule.
+ *
+ * Every `fail(...)` envelope in this file now goes through here, so "reported a
+ * failure" and "exited non-zero" cannot drift apart again. The helper takes the
+ * Commander `opts` object and calls `asJson(opts)` itself — it must never be
+ * handed a bare `opts.json`-less boolean, and it must never pass `opts` to
+ * `printResult` (see the `asJson` comment above for that bug's history).
+ *
+ * DELIBERATELY NOT APPLIED TO THE ADVISORY PATHS. Three sites in this file
+ * report a non-fatal outcome through an `ok(...)` envelope and MUST keep
+ * exiting 0: the two `emitJobEvent` best-effort catches (`job init`,
+ * `job status`) and the post-slice codegraph refresh in `job checkpoint`, whose
+ * stated design is "a refresh failure must never fail the checkpoint". Those
+ * are annotated in place; `tests/unit/cli/job-exit-code.test.ts` pins both
+ * directions so a future blanket "every warning exits 1" edit turns red.
+ */
+function failResult(io, result, opts) {
+    printResult(io, result, asJson(opts));
+    process.exitCode = 1;
+}
 function projectRoot(opts) {
     // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
     return opts.project ?? process.cwd();
@@ -125,7 +169,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         // a random UUID would scatter state across dirs and break resume/auto-compact.
         let sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
         if (!sessionId) {
-            return printResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-code session via peaks workspace init)', { project }, [
+            return failResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-code session via peaks workspace init)', { project }, [
                 'Re-run with --session-id <sid>',
                 'Or run `peaks workspace init` to create a session first'
             ]), opts);
@@ -142,7 +186,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
             json: opts.json,
         });
         if (!parsed.success)
-            return printResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
+            return failResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
         const jobRoot = resolveJobStateRoot(opts);
         const store = new JobStateStore(jobRoot.rootDir);
         const orch = new JobOrchestrator(store);
@@ -159,10 +203,14 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
             emitJobEvent({ kind: 'job-started', jobId: state.jobId, total: state.slices.length, strategy: state.mainLoopStrategy });
         }
         catch (e) {
-            // best-effort: event emission failures must not abort job init
+            // ADVISORY (F1, 2026-09-17) — deliberately exits 0. Event emission is a
+            // telemetry side effect; a failed emit does not mean `job init` failed
+            // (the state file was already written above). This catch must NOT be
+            // routed through `failResult`. Pinned by the "advisory stays 0" control
+            // in tests/unit/cli/job-exit-code.test.ts.
             void e;
         }
-        printResult(io, ok('init', { jobId: state.jobId, sliceCount: state.slices.length, statePath: `${jobRoot.rootDir}/${state.jobId}/state.json` }), opts);
+        printResult(io, ok('init', { jobId: state.jobId, sliceCount: state.slices.length, statePath: `${jobRoot.rootDir}/${state.jobId}/state.json` }), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'init'));
     job
@@ -191,10 +239,12 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
             emitJobEvent({ kind: 'job-progress', jobId: opts.jobId, done: s.done, total: s.total, ...(s.currentSlice ? { currentSlice: s.currentSlice } : {}) });
         }
         catch (e) {
-            // best-effort: event emission failures must not abort job status
+            // ADVISORY (F1, 2026-09-17) — deliberately exits 0. The status itself
+            // was already read successfully; the emit is telemetry. Same rule as
+            // the `job init` catch above: do NOT route through `failResult`.
             void e;
         }
-        printResult(io, ok('status', s), opts);
+        printResult(io, ok('status', s), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'status'));
     // M4.2: wire rotate-now to JobRotation (session-rotate callbacks are stubs pending M6.5 batch-fix).
@@ -206,7 +256,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const rotation = new JobRotation(store, async (_jid) => { /* delegate to peaks session rotate — implementation wired in M6.5 batch-fix */ return { rotated: true }; }, async (jid) => ({ jobId: jid, cycle: 0 }));
         const r = await rotation.rotateNow(opts.jobId);
-        printResult(io, ok('rotate-now', r), opts);
+        printResult(io, ok('rotate-now', r), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'rotate-now'));
     job.command('subagent-cleanup')
@@ -218,7 +268,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .action(async (opts) => {
         const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir), async () => ({ batchId: opts.batchId }));
         const r = await wrapper.cleanup({ jobId: opts.jobId, batchId: opts.batchId, force: !!opts.force });
-        printResult(io, ok('subagent-cleanup', r), opts);
+        printResult(io, ok('subagent-cleanup', r), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'subagent-cleanup'));
     // M3.2: wire the remaining 5 subcommand slots — block, checkpoint, continue, handoff, resume.
@@ -238,7 +288,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
             project: projectRoot(opts), json: opts.json,
         });
         if (!parsed.success)
-            return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
+            return failResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
         const jobRoot = resolveJobStateRoot(opts, opts.jobId);
         const store = new JobStateStore(jobRoot.rootDir);
         // D7: `--slice-id` accepts the canonical `slice-NNN` or the slice's label
@@ -246,7 +296,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         // so progress.json is never touched by a checkpoint that matched nothing.
         const slice = resolveSliceId(store, parsed.data.jobId, parsed.data.sliceId);
         if ('message' in slice) {
-            return printResult(io, fail('checkpoint', 'SLICE_NOT_FOUND', slice.message, {
+            return failResult(io, fail('checkpoint', 'SLICE_NOT_FOUND', slice.message, {
                 jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, validSliceIds: slice.validSliceIds,
             }, ['Re-run with one of the valid slice ids']), opts);
         }
@@ -256,6 +306,9 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         // envelope carries a non-blocking `codegraph` result; null for
         // failed/skipped (no slice-complete boundary).
         let codegraph = null;
+        // A2 (2026-09-17): the human-visible half of the refresh outcome. null
+        // when the refresh succeeded or when no codegraph store was in use.
+        let codegraphWarning = null;
         if (parsed.data.state === 'done') {
             await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
             // v3.1.2: after each --state done, mirror slice progress to
@@ -272,14 +325,31 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
                 lastCommitSha: parsed.data.commitSha ?? null,
                 updatedAt: new Date().toISOString()
             });
-            // Auto codegraph refresh at the slice-complete boundary. Best-effort
-            // and fail-silent: a refresh failure must never fail the checkpoint.
+            // Auto codegraph refresh at the slice-complete boundary. Best-effort:
+            // a refresh failure must never fail the checkpoint.
+            //
+            // A2 (2026-09-17): "must never fail the checkpoint" is not "must
+            // never be seen". A refresh that did not happen while a codegraph
+            // store IS in use is now a warning line (stderr, `warning: ` prefix,
+            // via printResult) naming the reason and the remedy. See
+            // `codegraphRefreshNotice` for why `no-codegraph-dir` stays silent.
+            //
+            // ADVISORY (F1, 2026-09-17) — deliberately exits 0, and the reach of
+            // that word is exactly here. The checkpoint itself SUCCEEDED (the slice
+            // flipped to done and progress.json was mirrored above); the refresh is
+            // a derived index, rebuildable on demand. So the outcome is reported
+            // through `ok(...)` + a `warning:` line, never through `failResult`,
+            // and `process.exitCode` is left alone even when the refresh throws.
+            // Raising it would turn an advisory rebuild into a build breaker for
+            // every CI that runs `peaks job checkpoint`. Pinned by the "advisory
+            // stays 0" control in tests/unit/cli/job-exit-code.test.ts.
             try {
                 codegraph = await refreshCodegraphAfterSlice(project);
             }
             catch (e) {
                 codegraph = { refreshed: false, reason: 'unavailable', note: `auto codegraph refresh failed: ${e instanceof Error ? e.message : String(e)}` };
             }
+            codegraphWarning = codegraphRefreshNotice(codegraph);
         }
         else if (parsed.data.state === 'skipped') {
             await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId, reason: parsed.data.reason });
@@ -287,7 +357,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         else {
             await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId, reason: parsed.data.reason });
         }
-        printResult(io, ok('checkpoint', { sliceId, status: parsed.data.state, codegraph }), opts);
+        printResult(io, ok('checkpoint', { sliceId, status: parsed.data.state, codegraph }, codegraphWarning === null ? [] : [codegraphWarning]), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
     job
@@ -303,19 +373,19 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
             project: projectRoot(opts), json: opts.json,
         });
         if (!parsed.success)
-            return printResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
+            return failResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
         const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         // D7 (same silent no-op as checkpoint): resolve label → sliceId, reject a
         // miss before any write.
         const slice = resolveSliceId(store, parsed.data.jobId, parsed.data.sliceId);
         if ('message' in slice) {
-            return printResult(io, fail('block', 'SLICE_NOT_FOUND', slice.message, {
+            return failResult(io, fail('block', 'SLICE_NOT_FOUND', slice.message, {
                 jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, validSliceIds: slice.validSliceIds,
             }, ['Re-run with one of the valid slice ids']), opts);
         }
         const orch = new JobOrchestrator(store);
         await orch.blockSlice({ ...parsed.data, sliceId: slice.sliceId });
-        printResult(io, ok('block', { blocked: slice.sliceId, reason: parsed.data.reason }), opts);
+        printResult(io, ok('block', { blocked: slice.sliceId, reason: parsed.data.reason }), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'block'));
     job
@@ -327,7 +397,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const orch = new JobOrchestrator(store);
         const r = orch.continueNow(opts.jobId);
-        printResult(io, ok('continue', r), opts);
+        printResult(io, ok('continue', r), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'continue'));
     job
@@ -339,7 +409,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const orch = new JobOrchestrator(store);
         const s = orch.status(opts.jobId);
-        printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
+        printResult(io, ok('resume', { resumed: opts.jobId, ...s }), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'resume'));
     // v3.1.2: read the on-disk slice progress mirror written by `peaks
@@ -353,7 +423,19 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .requiredOption('--job-id <jid>')
         .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
-        .option('--allow-missing', 'return done=0/total=0 envelope instead of failing when progress.json is absent')
+        // H3 (rid 2026-09-17-exit-code-root-cause): this string used to promise
+        // "return done=0/total=0 envelope instead of failing when progress.json is
+        // absent". No code path has ever returned such an envelope — the option was
+        // born in `d9a1a098` with `process.exitCode = 1` on the same branch — so it
+        // described a contract that never existed, and `--allow-missing` appeared to
+        // be broken. It is not: its job is to pick WHICH structured code reports the
+        // absence. The help text was the side that was wrong; it now says what the
+        // flag does. See `rd/requests/013-…-exit-code-root-cause.md` for why the
+        // alternative reading was rejected (the literal promise is also
+        // unimplementable without a new absent-vs-corrupt distinction:
+        // `tryReadJobProgress` returns `null` for a corrupt file too, so "done=0"
+        // there would report unreadable state as empty state).
+        .option('--allow-missing', 'report an absent progress.json as NO_PROGRESS (expected absence) rather than PROGRESS_READ_FAILED (read error); the command still exits non-zero')
         .action(async (opts) => {
         try {
             const jobRoot = resolveJobStateRoot(opts, opts.jobId);
@@ -363,20 +445,29 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
                 ? tryReadJobProgress(project, sessId, opts.jobId)
                 : readJobProgress(project, sessId, opts.jobId);
             if (progress === null) {
-                printResult(io, fail('progress', 'NO_PROGRESS', `No progress.json for job ${opts.jobId} at .peaks/_runtime/${sessId}/job/${opts.jobId}/progress.json`, { jobId: opts.jobId, sessionId: sessId }, [
+                // F1: this site already set `process.exitCode = 1` by hand; it is
+                // routed through `failResult` so all nine failure sites in this file
+                // share one rule instead of this one being the lone precedent.
+                failResult(io, fail('progress', 'NO_PROGRESS', `No progress.json for job ${opts.jobId} at .peaks/_runtime/${sessId}/job/${opts.jobId}/progress.json`, { jobId: opts.jobId, sessionId: sessId }, [
                     'Run `peaks job checkpoint --state done ...` at least once to seed progress.json.',
-                    'Or pass --allow-missing to return a zero-progress envelope.'
-                ]), opts.json);
-                process.exitCode = 1;
+                    // H3: the second action used to read "Or pass --allow-missing to
+                    // return a zero-progress envelope." That line could only ever be
+                    // printed when `--allow-missing` had ALREADY been passed — this
+                    // `progress === null` branch is unreachable otherwise, because the
+                    // no-flag path throws into the catch below and reports
+                    // PROGRESS_READ_FAILED. So the CLI was advising the caller to pass
+                    // the flag they had just passed, to obtain an envelope that does
+                    // not exist. Replaced with the fact the caller actually needs.
+                    '--allow-missing selects this NO_PROGRESS envelope over a PROGRESS_READ_FAILED read error; it does not change the exit code.'
+                ]), opts);
                 return;
             }
             printResult(io, ok('progress', progress, [], [
                 `Next: slice #${progress.done + 1} of ${progress.total} (${progress.currentSlice})`
-            ]), opts.json);
+            ]), asJson(opts));
         }
         catch (err) {
-            printResult(io, fail('progress', 'PROGRESS_READ_FAILED', err instanceof Error ? err.message : String(err), { jobId: opts.jobId }, ['Verify the job id and try again']), opts.json);
-            process.exitCode = 1;
+            failResult(io, fail('progress', 'PROGRESS_READ_FAILED', err instanceof Error ? err.message : String(err), { jobId: opts.jobId }, ['Verify the job id and try again']), opts);
         }
     });
     addJsonOption(job.commands.find(c => c.name() === 'progress'));
@@ -389,7 +480,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const orch = new JobOrchestrator(store);
         const s = orch.status(opts.jobId);
-        printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), opts);
+        printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'handoff'));
     job
@@ -402,7 +493,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         const project = projectRoot(opts);
         const sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
         if (!sessionId) {
-            return printResult(io, fail('karpathy-cost-check', 'NO_ACTIVE_SESSION', 'karpathy-cost-check requires --session-id (or an active peaks-code session)', { project }, [
+            return failResult(io, fail('karpathy-cost-check', 'NO_ACTIVE_SESSION', 'karpathy-cost-check requires --session-id (or an active peaks-code session)', { project }, [
                 'Re-run with --session-id <sid>',
                 'Or run `peaks workspace init` to create a session first',
             ]), opts);
@@ -420,7 +511,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
             reviewFilePath: opts.reviewFile,
             is24hModeActive,
         });
-        printResult(io, buildCostCheckEnvelope(out), opts);
+        printResult(io, buildCostCheckEnvelope(out), asJson(opts));
     });
     addJsonOption(job.commands.find(c => c.name() === 'karpathy-cost-check'));
     program.addCommand(job);