peaks-loop 4.1.2 → 4.1.4

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

@@ -4,17 +4,16 @@
 // 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
-// line is byte-identical and no behaviour changed; `attributeUpstreamUpToDate
+// Extracted verbatim from `codegraph-commands.ts`; `attributeUpstreamUpToDate
 // Line` stays importable from `codegraph-commands.ts`, which re-exports it.
+// The axis evaluation lives in `codegraph-status-integrity.ts` and the
+// machine report in `codegraph-status-json.ts`.
 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 { localizeUpstreamCodegraphText, printCodegraphFailure, runCodegraphCommand } from './codegraph-command-runtime.js';
+import { CODEGRAPH_INTEGRITY_EXIT_CODE } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { codegraphIndexIntegrityExitCode } from '../../services/codegraph/codegraph-index-integrity.js';
+import { runCodegraphCommand } from './codegraph-command-runtime.js';
+import { emitIntegrityText, readStatusAxes } from './codegraph-status-integrity.js';
+import { runCodegraphStatusJson } from './codegraph-status-json.js';
 const ANSI_SGR_PATTERN = /\x1b\[[0-9;]*m/g;
 /**
  * Upstream `status` answers a different question than peaks-loop's
@@ -57,97 +56,20 @@ export function attributeUpstreamUpToDateLine(stdout) {
         .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.
+ * 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`.
  */
-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: localizeUpstreamCodegraphText(result.stdout).trimEnd(),
-        stderr: redactSensitiveErrorMessage(localizeUpstreamCodegraphText(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 drop the blocking exclude rules 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 drop the blocking exclude rules and rebuild the index without the stale rows.`
-            ]), true);
-    }
-    else {
-        printResult(io, ok('codegraph.status', data), true);
+function applyStatusExitCode(integrityGap, indexVerdict, strict) {
+    const indexExitCode = codegraphIndexIntegrityExitCode(indexVerdict, strict);
+    if (integrityGap) {
+        process.exitCode = CODEGRAPH_INTEGRITY_EXIT_CODE;
     }
-    if (upstreamFailed) {
-        process.exitCode = result.exitCode ?? 1;
+    else if (indexExitCode !== null) {
+        process.exitCode = indexExitCode;
     }
-    return upstreamFailed;
 }
 /**
  * `peaks codegraph status` with an integrity gate.
@@ -168,135 +90,26 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
  * (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';
+    const axes = readStatusAxes(resolve(options.project));
+    const integrityGap = axes.integrity?.gap === true;
+    const indexGap = axes.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) {
+        if (await runCodegraphStatusJson(io, options, axes))
             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);
-            }
-        }
+        const upstreamFailed = await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, false, integrityGap || indexGap ? attributeUpstreamUpToDateLine : undefined);
+        emitIntegrityText(io, axes);
         // Upstream failure outranks both gates — and it already set the exit
         // code to upstream's.
-        if (upstreamFailed) {
+        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;
     }
+    applyStatusExitCode(integrityGap, axes.indexVerdict, axes.strict);
 }

package/dist/cli/commands/codegraph-status-integrity.d.ts

@@ -0,0 +1,44 @@
+import { type CodegraphExcludeIntegrityReport } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { type CodegraphIndexIntegrityReport, type CodegraphIndexIntegrityVerdict } from '../../services/codegraph/codegraph-index-integrity.js';
+import { type ProgramIO } from '../cli-helpers.js';
+/** Everything both the human and the machine branches of `status` report. */
+export type CodegraphStatusAxes = {
+    readonly integrity: CodegraphExcludeIntegrityReport | null;
+    readonly integrityWarning: string | null;
+    readonly indexIntegrity: CodegraphIndexIntegrityReport | null;
+    readonly indexIntegrityWarning: string | null;
+    readonly indexVerdict: CodegraphIndexIntegrityVerdict;
+    readonly strict: boolean;
+};
+/**
+ * Read both axes for a project root.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function readStatusAxes(projectRoot: string): CodegraphStatusAxes;
+/** The human-readable axis report, printed only by the non-JSON branch. */
+export declare function emitIntegrityText(io: ProgramIO, axes: CodegraphStatusAxes): void;

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

@@ -0,0 +1,121 @@
+// src/cli/commands/codegraph-status-integrity.ts
+//
+// The two integrity axes `peaks codegraph status` evaluates, and the human
+// reading of them. Split out of `codegraph-status-command.ts`; every
+// applicability predicate, degradation rule and printed line is unchanged.
+import { inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent, renderCodegraphExcludeIntegrityLines } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { inspectCodegraphIndexIntegrity, isCodegraphIndexStrictMode, renderCodegraphIndexIntegrityLines, resolveCodegraphIndexIntegrityVerdict } from '../../services/codegraph/codegraph-index-integrity.js';
+import { isCodegraphInitialized } from '../../services/codegraph/codegraph-service.js';
+import { readCodegraphProjectInputs } from '../../services/codegraph/codegraph-exclude-reconciler.js';
+import { getErrorMessage } from '../cli-helpers.js';
+/**
+ * Read both axes for a project root.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export function readStatusAxes(projectRoot) {
+    let integrity = null;
+    let integrityWarning = null;
+    let indexIntegrity = null;
+    let indexIntegrityWarning = null;
+    const configPresent = isCodegraphExcludeConfigPresent(projectRoot);
+    const indexPresent = isCodegraphInitialized(projectRoot);
+    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);
+                }
+            }
+        }
+    }
+    return {
+        integrity,
+        integrityWarning,
+        indexIntegrity,
+        indexIntegrityWarning,
+        indexVerdict: resolveCodegraphIndexIntegrityVerdict(indexIntegrity, indexIntegrityWarning),
+        strict: isCodegraphIndexStrictMode()
+    };
+}
+/** The human-readable axis report, printed only by the non-JSON branch. */
+export function emitIntegrityText(io, axes) {
+    if (axes.integrityWarning !== null) {
+        io.stdout(`[WARN] codegraph exclude integrity not evaluated: ${axes.integrityWarning}`);
+    }
+    else if (axes.integrity !== null) {
+        for (const line of renderCodegraphExcludeIntegrityLines(axes.integrity)) {
+            io.stdout(line);
+        }
+    }
+    if (axes.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): ${axes.indexIntegrityWarning ?? 'unknown cause'}`);
+    }
+    else if (axes.indexIntegrity !== null) {
+        for (const line of renderCodegraphIndexIntegrityLines(axes.indexIntegrity, axes.strict)) {
+            io.stdout(line);
+        }
+    }
+}

package/dist/cli/commands/codegraph-status-json.d.ts

@@ -0,0 +1,5 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type CommonCodegraphOptions } from './codegraph-command-runtime.js';
+import type { CodegraphStatusAxes } from './codegraph-status-integrity.js';
+/** Returns true when upstream failed (the caller must stop before the gates). */
+export declare function runCodegraphStatusJson(io: ProgramIO, options: CommonCodegraphOptions, axes: CodegraphStatusAxes): Promise<boolean>;

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

@@ -0,0 +1,127 @@
+// src/cli/commands/codegraph-status-json.ts
+//
+// The `--peaks-json` machine report for `peaks codegraph status`. Split out of
+// `codegraph-status-command.ts`; every envelope code, message, `data` field,
+// next-action string and exit-code rule is unchanged.
+//
+// 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.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE, CODEGRAPH_INDEX_STRICT_ENV_VAR, CODEGRAPH_REPAIR_INDEX_COMMAND } from '../../services/codegraph/codegraph-index-integrity.js';
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../../services/codegraph/codegraph-service.js';
+import { printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { localizeUpstreamCodegraphText, printCodegraphFailure } from './codegraph-command-runtime.js';
+/**
+ * `--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.
+ */
+function buildStatusReport(result, axes) {
+    const upstream = {
+        exitCode: result.exitCode,
+        stdout: localizeUpstreamCodegraphText(result.stdout).trimEnd(),
+        stderr: redactSensitiveErrorMessage(localizeUpstreamCodegraphText(result.stderr)).trimEnd()
+    };
+    return {
+        upstream,
+        data: {
+            upstream,
+            integrity: axes.integrity,
+            integrityWarning: axes.integrityWarning,
+            indexIntegrity: axes.indexIntegrity,
+            indexIntegrityWarning: axes.indexIntegrityWarning,
+            indexIntegrityVerdict: axes.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: axes.indexVerdict === 'gap' ? (axes.strict ? 'error' : 'warning') : null
+        }
+    };
+}
+/** The refusal an index gap produces, in strict or advisory wording. */
+function indexGapVerdict(axes) {
+    const includeGap = axes.indexIntegrity?.includeGap.length ?? 0;
+    const deadRows = axes.indexIntegrity?.deadRows.length ?? 0;
+    return {
+        message: `codegraph index does not cover the repository: ${includeGap} extractor-supported tracked file(s) are not admitted by the config's include globs, and ${deadRows} index row(s) point at files that no longer exist.`,
+        nextActions: axes.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 drop the blocking exclude rules 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 drop the blocking exclude rules and rebuild the index without the stale rows.`
+            ]
+    };
+}
+/** Upstream failed: its exit code outranks both gates, so it is ranked first. */
+function emitUpstreamFailure(io, result, report) {
+    const { stdout, stderr } = report.upstream;
+    printResult(io, fail('codegraph.status', 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(stderr || stdout || `codegraph exited with code ${String(result.exitCode)}`), report.data, ['Check the codegraph project path before retrying']), true);
+}
+/** The gate verdicts, in precedence order, when upstream itself succeeded. */
+function emitGateVerdict(io, axes, data) {
+    const integrity = axes.integrity;
+    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);
+        return;
+    }
+    if (axes.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: ${axes.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);
+        return;
+    }
+    if (axes.indexVerdict === 'gap') {
+        const verdict = indexGapVerdict(axes);
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_GAP', verdict.message, data, verdict.nextActions), true);
+        return;
+    }
+    printResult(io, ok('codegraph.status', data), true);
+}
+/** Returns true when upstream failed (the caller must stop before the gates). */
+export async function runCodegraphStatusJson(io, options, axes) {
+    let result;
+    try {
+        result = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'status', project: options.project }));
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.status', error, true);
+        return true;
+    }
+    const report = buildStatusReport(result, axes);
+    if (result.exitCode !== null && result.exitCode !== 0) {
+        emitUpstreamFailure(io, result, report);
+        process.exitCode = result.exitCode ?? 1;
+        return true;
+    }
+    emitGateVerdict(io, axes, report.data);
+    return false;
+}

package/dist/cli/commands/compact-command.d.ts

@@ -12,9 +12,13 @@
  *   - force:      Write a pre-compact checkpoint via
  *                 `peaks session checkpoint`; the IDE-side `/compact`
  *                 is still the LLM's call.
+ *   - history / harness-window / settle: the observability and hook
+ *                 transport for the window this group reports on.
  *
- * Each subcommand returns a `--json` envelope via `printResult`.
+ * Each subcommand returns a `--json` envelope via `printResult`. This module is
+ * the registrar: the parent group is created here and handed to each command's
+ * own module.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerCompactCommands(program: Command, io: ProgramIO): void;