peaks-loop 4.0.53 → 4.1.0

package/dist/cli/commands/code-runtime-commands.js

@@ -12,7 +12,10 @@
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { detectPostCompactResume, formatPostCompactResumeLogLine } from '../../services/code/post-compact-detector.js';
-import { runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
+import { evaluateCompactTrigger, runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
+import { thresholdFor } from '../../services/code/auto-compact-modes.js';
+import { resolveAutoCompactProfile } from '../../services/mode/mode-status-service.js';
+import { AUTO_COMPACT_SOFT_WARN_RATIO } from '../../services/context/auto-compact-types.js';
 import { auditContext } from '../../services/context/context-audit.js';
 import { syncHarnessWindowForProject } from '../../services/context/auto-compact-reader.js';
 import { describeHarnessWindowSync, harnessWindowSyncWarning } from '../../services/context/harness-window-config.js';
@@ -25,6 +28,43 @@ import { readJobShapeDecision, JobShapeDecisionError } from '../../services/code
 import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
 import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
 import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
+/** The one dispatch verb the action and red-line tiers name. */
+const COMPACT_CMD = 'peaks code auto-compact';
+/**
+ * Slice H4 (rid=h4-context-now-mode-blind) — the ONE mapping from the shared
+ * `CompactTrigger` to this command's `action` vocabulary, so the two cannot
+ * drift: the trigger is `evaluateCompactTrigger`, the same function `peaks
+ * code auto-compact` decides with.
+ *
+ * `auto-fire` maps to `soft-warn` in BOTH modes: that tier is `peaks skill
+ * presence`'s — the every-turn probe, which reads this same table and mode
+ * resolver — so `context-now` has no auto-fire tier of its own (SKILL.md
+ * "two probes, two thresholds"). Reporting it as `auto-compact-now` would
+ * change every non-24h session's output, which slice H4 forbids.
+ */
+export function contextNowActionFor(ratio, mode) {
+    const kind = evaluateCompactTrigger(ratio, mode).kind;
+    if (kind === 'red-line')
+        return { action: 'red-line', next: COMPACT_CMD };
+    if (kind === 'pre-compact')
+        return { action: 'auto-compact-now', next: COMPACT_CMD };
+    return { action: kind === 'none' ? 'ok' : 'soft-warn', next: null };
+}
+/** Slice H4: the labels `context-now` prints, read out of the table for the mode
+ *  in force — the old hard-coded "≥0.85 / ≥0.95 / 50–85%" told a 24h operator
+ *  the wrong lines. `*Ratio` is the `0.85` form `gateModeNotice` uses. */
+function contextNowBandLabels(mode) {
+    const pct = (r) => `${(r * 100).toFixed(0)}`;
+    const pre = thresholdFor(mode, 'preCompact');
+    const red = thresholdFor(mode, 'redLine');
+    return {
+        softWarn: pct(AUTO_COMPACT_SOFT_WARN_RATIO),
+        preCompact: pct(pre),
+        redLine: pct(red),
+        preCompactRatio: pre.toFixed(2),
+        redLineRatio: red.toFixed(2)
+    };
+}
 /**
  * Adapt `runAutoCompact`'s domain result to a `ResultEnvelope`.
  *
@@ -55,7 +95,14 @@ export function buildAutoCompactEnvelope(result) {
     // `fail()` hard-codes `warnings: []`, so the warning is spread back over it —
     // a refused write can disagree with the ratio just as easily on the failure
     // path, and the state does not become less true because the dispatch failed.
-    return { ...fail('code.auto-compact', result.code, result.message, data, [...nextActions]), warnings };
+    return {
+        ...fail('code.auto-compact', result.code, result.message, data, [...nextActions]),
+        warnings
+    };
+}
+function printPostCompactNoActiveSession(io, opts) {
+    printResult(io, fail('code.post-compact-detect', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
+    process.exitCode = 1;
 }
 export function registerCodeRuntimeCommands(code, io) {
     addJsonOption(code
@@ -69,8 +116,7 @@ export function registerCodeRuntimeCommands(code, io) {
         try {
             const sessionId = opts.sessionId ?? readActiveSid(opts.project);
             if (sessionId === null) {
-                printResult(io, fail('code.post-compact-detect', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
-                process.exitCode = 1;
+                printPostCompactNoActiveSession(io, opts);
                 return;
             }
             const probe = await detectPostCompactResume({
@@ -161,7 +207,7 @@ export function registerCodeRuntimeCommands(code, io) {
                             // projects.
                             const out = probeInFlightBatch({ now: new Date().toISOString(), graphs: [] });
                             return out.inFlightBatch === true;
-                        },
+                        }
                     }
                     : {}),
                 force: opts.force === true,
@@ -191,14 +237,14 @@ export function registerCodeRuntimeCommands(code, io) {
     });
     addJsonOption(code
         .command('context-now')
-        .description('v2.13.0 AC-1: read the active IDE adapter\'s context-fill % ' +
+        .description("v2.13.0 AC-1: read the active IDE adapter's context-fill % " +
         'without requiring the LLM to pass --prompt-size <bytes> manually. ' +
         'Adapter-driven (no hard-coded IDE names): Claude Code is the MVP ' +
         'implementation; trae / codex / cursor / qoder / tongyi-lingma / ' +
         'hermes / openclaw register their own env-var via IdeAdapter.compact. ' +
-        'v3.1.2 / 2026-09-12: ≥0.85 emits action=auto-compact-now ' +
-        '(MANDATORY in every mode — single-rid included) and ' +
-        '≥0.95 emits action=red-line (the installed PreToolUse hook re-runs ' +
+        "v3.1.2 / 2026-09-12: the mode's pre-compact line emits " +
+        'action=auto-compact-now (MANDATORY, single-rid included) and ' +
+        'the red line emits action=red-line (the installed PreToolUse hook re-runs ' +
         'this command on the next Bash/Task tool call; nothing is blocked). ' +
         '--enforce-job-mode only changes the reported `jobMode` label; ' +
         'the thresholds are identical. ' +
@@ -296,42 +342,30 @@ export function registerCodeRuntimeCommands(code, io) {
             });
             const witnessNotice = describeHarnessWitness(harnessWitness);
             const ratioPct = (probe.ratio * 100).toFixed(1);
-            let action = 'ok';
-            let next = null;
-            if (probe.ratio >= 0.95) {
-                action = 'red-line';
-                next = 'peaks code auto-compact';
-            }
-            else if (probe.ratio >= 0.85) {
-                // Slice 2026-09-12-compact-band-policy (defect A): the
-                // 0.85–0.95 band is MANDATORY auto-compact for single-rid
-                // sessions too. It used to be downgraded to `soft-warn` here,
-                // which contradicted this command's own help text, the
-                // `pre-compact` action from `peaks skill presence`, the
-                // peaks-code SKILL.md, and the 2026-07-27 user-calibrated
-                // threshold policy — and left an LLM that follows the "single
-                // source of truth" (`context-now`) never compacting in the
-                // zone, violating the zero-pause contract.
-                action = 'auto-compact-now';
-                next = 'peaks code auto-compact';
-            }
-            else if (probe.ratio >= 0.5) {
-                action = 'soft-warn';
-            }
-            const verdict = action === 'red-line' ? 'red-line'
-                : action === 'auto-compact-now' ? 'pre-compact'
-                    : action === 'soft-warn' ? 'soft-warn'
-                        : 'ok';
-            // Slice 2026-09-12-compact-band-policy: the two modes no longer
-            // differ in behaviour ABOVE 0.50 — both auto-fire at ≥0.85 and
-            // both red-line at ≥0.95 — so the old "advisory mode
-            // (single-rid)" notice was a lie the moment the downgrade was
-            // removed. Job mode's remaining difference is that its threshold
-            // policy is recorded up front (`job-shape.json`), which the
-            // `jobMode` field already reports. The notice now says only that.
+            // Slice H4 (rid=h4-context-now-mode-blind): ONE table, ONE mode
+            // resolver. The hard-coded ladder that used to live here (≥0.95 / ≥0.85
+            // / ≥0.5) read no mode at all, so on a 24h run (`partial` =
+            // 0.65/0.70/0.85) it answered `soft-warn` + `next: null` across
+            // [0.70, 0.85) — the band in which `peaks code auto-compact` had
+            // already decided to compact. SKILL.md calls THIS command the "single
+            // source of truth", so an LLM obeying it did nothing.
+            const compactMode = resolveAutoCompactProfile(canonicalProjectRoot);
+            const decided = contextNowActionFor(probe.ratio, compactMode);
+            const action = decided.action;
+            const next = decided.next;
+            const verdict = action === 'red-line'
+                ? 'red-line'
+                : action === 'auto-compact-now'
+                    ? 'pre-compact'
+                    : action;
+            const bands = contextNowBandLabels(compactMode);
+            // Slice H4: the text here used to claim "the two modes no longer differ
+            // in behaviour ABOVE 0.50 — both auto-fire at ≥0.85 and both red-line at
+            // ≥0.95". That was false: `partial` fires at 0.70, red-lines at 0.85.
+            // The lines now come from the table for the mode in force.
             const gateModeNotice = isJobMode
-                ? 'Job mode (job-shape.json isJob=true): the same ≥0.85 / ≥0.95 thresholds apply, and the decision is recorded in job-shape.json.'
-                : 'Single-rid mode: the same ≥0.85 / ≥0.95 thresholds apply — ≥0.85 is MANDATORY auto-compact, not advisory.';
+                ? `Job mode (job-shape.json isJob=true): the same ≥${bands.preCompactRatio} / ≥${bands.redLineRatio} thresholds apply, and the decision is recorded in job-shape.json.`
+                : `Single-rid mode: the same ≥${bands.preCompactRatio} / ≥${bands.redLineRatio} thresholds apply — ≥${bands.preCompactRatio} is MANDATORY auto-compact, not advisory.`;
             printResult(io, ok('code.context-now', {
                 ratio: probe.ratio,
                 ratioPct: `${ratioPct}%`,
@@ -366,12 +400,12 @@ export function registerCodeRuntimeCommands(code, io) {
                 ...(witnessNotice === null ? [] : [witnessNotice])
             ], [
                 action === 'red-line'
-                    ? `RED LINE: ≥ 95%. Next: \`${next}\` — peaks-loop asks the harness to compact and KEEPS WORKING (dispatch is not blocked); re-probe to confirm it landed.`
+                    ? `RED LINE: ≥ ${bands.redLine}%. Next: \`${next}\` — peaks-loop asks the harness to compact and KEEPS WORKING (dispatch is not blocked); re-probe to confirm it landed.`
                     : action === 'auto-compact-now'
-                        ? `MANDATORY auto-compact (≥85%, every mode). Code MUST call \`${next}\` WITHOUT confirmation.`
+                        ? `MANDATORY auto-compact (≥${bands.preCompact}%, every mode). Code MUST call \`${next}\` WITHOUT confirmation.`
                         : action === 'soft-warn'
-                            ? `Soft warn (50–85%). Continue working; the next \`peaks code auto-compact\` will re-check.`
-                            : `Below 50%. No action required.`,
+                            ? `Soft warn (${bands.softWarn}–${bands.preCompact}%). Continue working; the next \`peaks code auto-compact\` will re-check.`
+                            : `Below ${bands.softWarn}%. No action required.`,
                 gateModeNotice,
                 // Single wording, shared with `peaks code auto-compact` — see
                 // `describeHarnessWindowSync`.
@@ -383,7 +417,9 @@ export function registerCodeRuntimeCommands(code, io) {
                 // the same split, and note this one never asks a question.
                 ...(witnessNotice === null
                     ? []
-                    : ['Re-probe with `peaks code context-now` to confirm; this is reported, not blocking.'])
+                    : [
+                        'Re-probe with `peaks code context-now` to confirm; this is reported, not blocking.'
+                    ])
             ]), 
             // Slice 2026-09-13-auto-compact-trigger-ownership: was hard-coded
             // `true`, which made the declared `--json` flag a no-op and left the
@@ -412,10 +448,10 @@ export function registerCodeRuntimeCommands(code, io) {
     // `available:false` with a reason and NEVER sets a non-zero exit code.
     addJsonOption(code
         .command('context-audit')
-        .description('Slice 2026-09-10 Slice A: report what fills the current session\'s ' +
+        .description("Slice 2026-09-10 Slice A: report what fills the current session's " +
         'context window, grouped by tool + short input key (command line / ' +
-        'path tail / pattern), sorted by bytes. Locates the CURRENT session\'s ' +
-        'IDE transcript through the active adapter\'s ' +
+        "path tail / pattern), sorted by bytes. Locates the CURRENT session's " +
+        "IDE transcript through the active adapter's " +
         '`compact.resolveTranscriptPath` (vendor-neutral); emits total bytes, ' +
         'entry count, and the top-N groups ' +
         '(`{tool, key, bytes, pctOfTotal, count}`). Read-only and fail-soft — ' +
@@ -434,13 +470,17 @@ export function registerCodeRuntimeCommands(code, io) {
             const result = auditContext({
                 outerSessionId: outerSessionId ?? null,
                 ...(opts.top !== undefined ? { topN: opts.top } : {}),
-                ...(opts.transcript !== undefined ? { transcriptPath: opts.transcript } : {}),
+                ...(opts.transcript !== undefined ? { transcriptPath: opts.transcript } : {})
             });
             // Fail-soft contract: unavailability is DATA, not an error. The exit
             // code stays 0 so a `context-audit` call can never block a workflow.
             const nextActions = result.available
-                ? [`${result.entryCount} tool result(s) across ${result.groupCount} group(s); showing top ${result.entries.length}.`]
-                : [`context-audit unavailable: ${result.reason ?? 'unknown'} — continue without it (read-only probe).`];
+                ? [
+                    `${result.entryCount} tool result(s) across ${result.groupCount} group(s); showing top ${result.entries.length}.`
+                ]
+                : [
+                    `context-audit unavailable: ${result.reason ?? 'unknown'} — continue without it (read-only probe).`
+                ];
             printResult(io, ok('code.context-audit', { ...result }, [], nextActions), opts.json);
         }
         catch (err) {
@@ -482,9 +522,7 @@ export function registerCodeRuntimeCommands(code, io) {
                     mode: 'no-session',
                     decision: null,
                     nextSlice: null
-                }, [], [
-                    'No active session id; gate passes through (single-rid mode).'
-                ]);
+                }, [], ['No active session id; gate passes through (single-rid mode).']);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -524,10 +562,7 @@ export function registerCodeRuntimeCommands(code, io) {
                     mode: 'single',
                     decision: null,
                     nextSlice: null
-                }, [], [
-                    'job-shape.json says isJob=false; single-rid mode (gate allows).',
-                    ...hintActions
-                ]);
+                }, [], ['job-shape.json says isJob=false; single-rid mode (gate allows).', ...hintActions]);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -584,9 +619,7 @@ export function registerCodeRuntimeCommands(code, io) {
         try {
             const sessionId = opts.sessionId ?? readActiveSid(opts.project);
             if (sessionId === null) {
-                const envelope = ok('code.emit-handoff', { allow: true, mode: 'no-session' }, [], [
-                    'No active session id; gate passes through (single-rid mode).'
-                ]);
+                const envelope = ok('code.emit-handoff', { allow: true, mode: 'no-session' }, [], ['No active session id; gate passes through (single-rid mode).']);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -600,16 +633,12 @@ export function registerCodeRuntimeCommands(code, io) {
                 evalInput.forceUnderJob = true;
             const verdict = evaluateEmitHandoff(evalInput);
             if (verdict.kind === 'allow-not-job') {
-                const envelope = ok('code.emit-handoff', { allow: true, mode: 'single' }, [], [
-                    'job-shape.json says isJob=false (or absent); normal handoff allowed.'
-                ]);
+                const envelope = ok('code.emit-handoff', { allow: true, mode: 'single' }, [], ['job-shape.json says isJob=false (or absent); normal handoff allowed.']);
                 printResult(io, envelope, opts.json);
                 return;
             }
             if (verdict.kind === 'allow-done') {
-                const envelope = ok('code.emit-handoff', { allow: true, mode: 'job-done', remaining: verdict.remaining }, [], [
-                    `Job is complete (remaining=0); handoff allowed.`
-                ]);
+                const envelope = ok('code.emit-handoff', { allow: true, mode: 'job-done', remaining: verdict.remaining }, [], [`Job is complete (remaining=0); handoff allowed.`]);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -621,7 +650,9 @@ export function registerCodeRuntimeCommands(code, io) {
                 return;
             }
             if (verdict.kind === 'block-not-initialized') {
-                const envelope = fail('code.emit-handoff', JOB_NOT_INITIALIZED, `Job ${verdict.jobId} has no state.json; peaks job init was skipped.`, { jobId: verdict.jobId }, [`Run \`peaks job init --job-id ${verdict.jobId} --slice-list <...>\` before emitting handoff.`]);
+                const envelope = fail('code.emit-handoff', JOB_NOT_INITIALIZED, `Job ${verdict.jobId} has no state.json; peaks job init was skipped.`, { jobId: verdict.jobId }, [
+                    `Run \`peaks job init --job-id ${verdict.jobId} --slice-list <...>\` before emitting handoff.`
+                ]);
                 printResult(io, envelope, opts.json);
                 process.exitCode = 1;
                 return;
@@ -656,7 +687,8 @@ function readActiveSid(projectRoot) {
             return null;
         return presence.sessionId ?? null;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
 }

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

@@ -1,8 +1,8 @@
 // src/cli/commands/codegraph-commands.ts
 //
 // The codegraph verbs that MUTATE or PROXY: `repair-exclude`, `repair-index`,
-// `init`, `affected`, plus the commander registration for every codegraph
-// subcommand.
+// `config-restore`, `init`, `affected`, plus the commander registration for
+// every codegraph subcommand.
 //
 // D1 (rid 2026-09-17-oversize-and-scale, the 800-line file-size cap) moved
 // the shared invocation runtime to `codegraph-command-runtime.ts` and the
@@ -12,11 +12,13 @@
 // re-exported below, so every existing importer still resolves.
 import { InvalidArgumentError } from 'commander';
 import { statSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { createCodegraphInvocation, executeCodegraphInvocation, defaultCodegraphInitGuard, resolveProjectRoot, writeCodegraphMarker, writeCodegraphAffectedContext, CodegraphInitConflictError } from '../../services/codegraph/codegraph-service.js';
+import { join, resolve } from 'node:path';
+import { assertCodegraphDirContained, createCodegraphInvocation, executeCodegraphInvocation, defaultCodegraphInitGuard, resolveProjectRoot, writeCodegraphMarker, writeCodegraphAffectedContext, CodegraphInitConflictError, CODEGRAPH_DIR_NAME } from '../../services/codegraph/codegraph-service.js';
 import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
+import { CODEGRAPH_CONFIG_FILENAME } from '../../services/codegraph/codegraph-exclude-reconciler.js';
+import { rollbackCodegraphConfig } from '../../services/codegraph/codegraph-config-repair-writer.js';
 import { fail, ok } from 'peaks-loop-shared/result';
-import { printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
 import { printCodegraphFailure, runCodegraphCommand } from './codegraph-command-runtime.js';
 import { runCodegraphStatusCommand } from './codegraph-status-command.js';
 // Re-exported so the D1 split is invisible to importers of THIS path.
@@ -132,9 +134,7 @@ async function runCodegraphRepairCommand(io, options, asJson, mode) {
     // in the third slot reads as a problem — and a real warning parked
     // there double-prefixes. Confirmations go to `nextActions`; only a
     // genuine `report.warning` reaches `warnings`, verbatim.
-    const confirmations = [
-        report.applied ? appliedRepairNote(report) : spec.noopNote
-    ];
+    const confirmations = [report.applied ? appliedRepairNote(report) : spec.noopNote];
     if (report.applied || mode === 'index') {
         confirmations.push('Re-run `peaks codegraph status --project <root>` to confirm the gap is closed.');
     }
@@ -158,6 +158,160 @@ async function runCodegraphRepairCommand(io, options, asJson, mode) {
         process.exitCode = 1;
     }
 }
+/**
+ * Exit code for a `config-restore` run that never reached the restore point:
+ * `--project` is missing or not a directory, or the containment guard refused
+ * the `.codegraph/` directory.
+ *
+ * Deliberately NOT `CODEGRAPH_CONFIG_RESTORE_EXIT_CODE` (77). The two codes
+ * answer different questions, and a CI job has to be able to tell them apart:
+ *
+ *   - 1  — the command was never aimed at a usable project. Nothing looked at a
+ *          rollback point, so "your backup is unusable" would be a verdict
+ *          nothing reached, and the remedy is a different one (fix the path, or
+ *          remove the link). The VALUE is 1 because that is what every other
+ *          codegraph verb already exits with for this same input failure —
+ *          `repair-exclude --project <bad>` and `status --project <bad>` both
+ *          exit 1 (measured), so a caller that handles one handles this one.
+ *   - 77 — the restore point WAS examined and the restore did not happen.
+ *
+ * Named rather than left as `printCodegraphFailure`'s default `1` so both
+ * classes are visible in one place, side by side, instead of one of them living
+ * only in another module's parameter default.
+ */
+const CODEGRAPH_CONFIG_RESTORE_PRECONDITION_EXIT_CODE = 1;
+/**
+ * Exit code for `peaks codegraph config-restore` when the restore did not
+ * happen: the backup is absent, unreadable, or REFUSED (a symbolic link, a
+ * hard link or a directory occupies the fixed, guessable `.bak` path), or the
+ * reverse write itself failed.
+ *
+ * Its own code rather than the precondition `1`, for the same reason 73/74/75/76
+ * have theirs: it is an operator-actionable verdict about the RESTORE POINT, and
+ * a CI job has to be able to tell it apart from "the command was aimed wrong".
+ * The cause lives in `data.reason`, which names the path and the shape that was
+ * refused — a per-cause CODE would need the rollback helper to return a
+ * discriminated reason rather than a message, which is a change to that helper's
+ * contract for no operator-visible gain while the message already carries the
+ * details.
+ */
+const CODEGRAPH_CONFIG_RESTORE_EXIT_CODE = 77;
+/**
+ * The failure envelope for EVERY `config-restore` failure, so all four `data`
+ * keys are present whatever went wrong.
+ *
+ * A JSON consumer reads `data.restored` and `data.reason` unconditionally, so a
+ * failure envelope that omits them leaves it guessing — and this verb reports a
+ * `reason` instead of an exit code alone precisely so a failure is never silent.
+ * Built here rather than delegated to `printCodegraphFailure`, whose `data` is
+ * always `{}` and therefore cannot satisfy that.
+ *
+ * `code` names the VERB's failure for all three cases; the exit code names the
+ * CLASS (precondition vs restore) and `reason` names the cause. That split is
+ * deliberate: one `code` a consumer can match on, plus the two facts it needs
+ * to decide what to do next.
+ *
+ * The verb-specific `code` is an INTENTIONAL DIVERGENCE from every other
+ * codegraph verb, not a consistency with them — `repair-exclude`,
+ * `repair-index` and `status` all report `CODEGRAPH_COMMAND_FAILED` out of
+ * `printCodegraphFailure` with `data: {}` (measured, 2026-09-17). Two reasons
+ * to diverge here anyway:
+ *
+ *   1. A generic `code` cannot be paired with a verb-specific `reason`
+ *      contract: this verb's failure ALWAYS carries `restored`/`reason`, which
+ *      `printCodegraphFailure` cannot express at all (`fail()` hard-codes the
+ *      other verbs' `data` to `{}`).
+ *   2. `CODEGRAPH_CONFIG_RESTORE_FAILED` says WHICH restore failed, and a
+ *      consumer matching on `code` gets that from the envelope rather than from
+ *      the exit code alone.
+ *
+ * FOLLOW-UP (recorded, not done here — it is out of this slice's scope):
+ * `code` naming across the codegraph verb family is now inconsistent, and the
+ * rest of the family should either adopt verb-specific codes or this one should
+ * return to the generic one. See this slice's RD artifact,
+ * `## A1 QA 修复循环 2`.
+ */
+function printConfigRestoreFailure(io, asJson, reason, exitCode, nextActions) {
+    const redacted = redactSensitiveErrorMessage(reason);
+    printResult(io, fail('codegraph.config-restore', 'CODEGRAPH_CONFIG_RESTORE_FAILED', redacted, { restored: false, from: null, to: null, reason: redacted }, [...nextActions]), asJson);
+    process.exitCode = exitCode;
+}
+/**
+ * `peaks codegraph config-restore` — put `.codegraph/config.json` back to the
+ * bytes the last repair backed up to `.codegraph/config.json.bak`.
+ *
+ * The EXPLICIT undo of a repair, and the only way the `.bak` is ever read: the
+ * repair seams leave the copy behind and never consume it, because a repair
+ * that restored its own write would cancel itself out (the config would be
+ * exactly as it was found, `status` would still report the gap, and exit 75
+ * would never clear).
+ *
+ * Touches the CONFIG FILE ONLY — no `codegraph` subprocess is spawned, so this
+ * is safe to run while nothing else is rebuilding. The index still reflects
+ * whatever config the last rebuild used; the envelope's `nextActions` says so
+ * rather than silently reindexing.
+ */
+async function runCodegraphConfigRestoreCommand(io, options, asJson) {
+    let configPath;
+    try {
+        // `resolveProjectRoot` for the same reason the repair verbs use it: the
+        // paths reported here must be the canonical ones, or a `--project` alias
+        // reports a restore that happened somewhere the operator cannot find.
+        const projectRoot = resolveProjectRoot(options.project);
+        // The containment refusal the repair seam makes before IT writes here. A
+        // `.codegraph/` that resolves outside the canonical project root (a junction
+        // or a symlink) would otherwise let this verb publish one project's bytes
+        // into another. Called for its refusal only — the paths below stay derived
+        // from the caller's canonical `projectRoot`.
+        assertCodegraphDirContained(projectRoot);
+        configPath = join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME);
+    }
+    catch (error) {
+        // The PRECONDITION class: nothing below this line ran, so the envelope says
+        // the restore did not happen and stops short of blaming the rollback point.
+        printConfigRestoreFailure(io, asJson, getErrorMessage(error), CODEGRAPH_CONFIG_RESTORE_PRECONDITION_EXIT_CODE, [
+            'Check that `--project` names an existing directory whose `.codegraph/` resolves inside it.',
+            'Run `peaks codegraph config-restore --project <root>` again once the path is right.'
+        ]);
+        return;
+    }
+    let result;
+    try {
+        result = await rollbackCodegraphConfig(configPath);
+    }
+    catch (error) {
+        // Only the reverse write's own fs failure reaches here (the refusals are
+        // returned, not thrown). The RESTORE class, and the same code as a refusal:
+        // the restore was attempted and did not happen, and a script that can read
+        // one can read the other. What differs is the `reason`, which is this
+        // error's own message.
+        printConfigRestoreFailure(io, asJson, getErrorMessage(error), CODEGRAPH_CONFIG_RESTORE_EXIT_CODE, [
+            'Check that the `.codegraph/` directory is writable, then re-run.',
+            'The config was NOT restored; its bytes are unchanged.'
+        ]);
+        return;
+    }
+    if (!result.rolledBack) {
+        // LOUD, never silent: the reason reaches the envelope's `message` (which
+        // `fail()` redacts) AND `data.reason`, and the exit code is this verb's
+        // own. A restore that quietly reported success over a `.bak` it refused to
+        // read is exactly the fail-silent family this release closed.
+        printConfigRestoreFailure(io, asJson, result.error, CODEGRAPH_CONFIG_RESTORE_EXIT_CODE, [
+            `There is no usable rollback point at ${result.backupPath}.`,
+            'A restore needs the `.bak` that a previous `peaks codegraph repair-exclude` or `repair-index` left next to the config.'
+        ]);
+        return;
+    }
+    printResult(io, ok('codegraph.config-restore', {
+        restored: true,
+        from: result.backupPath,
+        to: result.configPath,
+        reason: null
+    }, [], [
+        'Run `peaks codegraph status --project <root>` to see the restored config reflected in the integrity gate.',
+        'Run `peaks codegraph index` if the index should reflect the restored config too — this verb does not rebuild it.'
+    ]), asJson);
+}
 /**
  * rid-CG-006 — init conflict guard. Resolves the project root and
  * probes `.codegraph/` for the peaks-loop marker before invoking the
@@ -369,14 +523,21 @@ async function runCodegraphAffectedCommand(io, files, options, asJson) {
     }
 }
 export function registerCodegraphCommands(program, io) {
-    const codegraph = program.command('codegraph').description('Run upstream codegraph commands through the Peaks launcher');
-    addProjectOption(codegraph.command('status').description('Show codegraph status, including the exclude integrity gate')).action((options) => runCodegraphStatusCommand(io, options, options.peaksJson));
+    const codegraph = program
+        .command('codegraph')
+        .description('Run upstream codegraph commands through the Peaks launcher');
+    addProjectOption(codegraph
+        .command('status')
+        .description('Show codegraph status, including the exclude integrity gate')).action((options) => runCodegraphStatusCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('repair-exclude')
         .description('Normalize the codegraph include list, drop exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'exclude'));
     addProjectOption(codegraph
         .command('repair-index')
         .description('Repair both codegraph config axes, then rebuild the index from scratch (drops rows for deleted files)')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'index'));
+    addProjectOption(codegraph
+        .command('config-restore')
+        .description('Restore .codegraph/config.json from the byte-exact .bak a repair left — the explicit undo of a repair')).action((options) => runCodegraphConfigRestoreCommand(io, options, options.peaksJson));
     addProjectOption(codegraph.command('init').description('Initialize codegraph for a project')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('index')
@@ -419,7 +580,10 @@ export function registerCodegraphCommands(program, io) {
             ...(options.maxDepth !== undefined ? { maxDepth: options.maxDepth } : {})
         }, options.peaksJson);
     });
-    addProjectOption(codegraph.command('context').description('Build task context with codegraph').argument('<task>', 'task text')).action(async (task, options) => {
+    addProjectOption(codegraph
+        .command('context')
+        .description('Build task context with codegraph')
+        .argument('<task>', 'task text')).action(async (task, options) => {
         await runCodegraphCommand(io, 'codegraph.context', { subcommand: 'context', project: options.project, task }, options.peaksJson);
     });
     addProjectOption(codegraph

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

@@ -113,10 +113,14 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
         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);
+        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);
+        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