peaks-loop 4.0.50 → 4.0.52

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

@@ -1,11 +1,13 @@
 import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
 import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
-import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody } from '../../services/memory/project-memory-service.js';
+import { describeMemoryBlockDrops, describeSessionScanFailures, extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody, VALID_PROJECT_MEMORY_KINDS } from '../../services/memory/project-memory-service.js';
 import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
 import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
 import { formatMdCompact } from '../../shared/format-md-compact.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. */
+const KIND_HELP = VALID_PROJECT_MEMORY_KINDS.join(', ');
 export function registerProjectCommands(program, io) {
     const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
     addJsonOption(project
@@ -111,7 +113,15 @@ export function registerProjectCommands(program, io) {
                 writtenFiles: result.writtenFiles,
                 memoryDir: result.primaryMemoryDir,
                 indexUpdated: result.updatedIndex
-            }), options.json);
+            }, [
+                // Two drop axes, one channel. `droppedBlocks` = a block was found and
+                // rejected (or a marker-shaped comment was not findable at all);
+                // `scanFailures` = the whole artifact could not be read, so its blocks
+                // were never candidates. `data` is unchanged by either — same contract
+                // as `memory.extract`.
+                ...describeMemoryBlockDrops(result.droppedBlocks),
+                ...describeSessionScanFailures(result.scanFailures)
+            ]), options.json);
         }
         catch (error) {
             printResult(io, fail('project.memories:extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), { sessionId: options.sessionId, projectRoot: options.project }, ['Check the session-id and project path']), options.json);
@@ -141,7 +151,7 @@ export function registerProjectCommands(program, io) {
         .command('memories')
         .description('Read durable project memories (decisions, conventions, modules, rules) from .peaks/memory for LLM consumption')
         .requiredOption('--project <path>', 'target project root')
-        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module, lesson')).action((options) => {
+        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)).action((options) => {
         try {
             const result = readProjectMemories(options.project);
             if (options.kind) {

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

@@ -8,7 +8,7 @@ import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-serv
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
-import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
+import { codegraphRefreshNotice, refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { isUnsafePathInput } from '../../shared/path-safety.js';
 /**
@@ -296,6 +296,9 @@ export function registerRequestCommands(program, io) {
             // RD → QA slice-complete boundary. Set only for rd:qa-handoff; null
             // otherwise. Best-effort and fail-silent — never blocks the transition.
             let codegraphRefresh = 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 (role === 'rd' && newState === 'qa-handoff') {
                 try {
                     const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
@@ -319,6 +322,11 @@ export function registerRequestCommands(program, io) {
                     // The refresh is best-effort; never block the transition.
                     codegraphRefresh = { refreshed: false, reason: 'unavailable', note: 'auto codegraph refresh failed after transition' };
                 }
+                // A2 (2026-09-17): never BLOCKING is kept; never VISIBLE is not. A
+                // non-refresh while a codegraph store is in use becomes a warning
+                // line beside the transition's own notes. See
+                // `codegraphRefreshNotice` for why `no-codegraph-dir` stays silent.
+                codegraphWarning = codegraphRefreshNotice(codegraphRefresh);
             }
             // v2.13.2 AC-4 — auto-regen prd/handoff.md on prd:handed-off success.
             // Only fires when the handoff is missing; existing handoffs are not overwritten.
@@ -360,13 +368,16 @@ export function registerRequestCommands(program, io) {
             // transition is not a slice boundary), preCompact is null and
             // we emit a `preCompactCheckpoint: null` field so LLM callers
             // can branch on it without re-deriving zone membership.
-            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null, codegraphRefresh }, preCompact !== null
-                ? [
-                    `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
-                        ? String(preCompact.data.ratio)
-                        : 'unknown'} (zone=pre-compact)`
-                ]
-                : []), options.json);
+            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null, codegraphRefresh }, [
+                ...(preCompact !== null
+                    ? [
+                        `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
+                            ? String(preCompact.data.ratio)
+                            : 'unknown'} (zone=pre-compact)`
+                    ]
+                    : []),
+                ...(codegraphWarning === null ? [] : [codegraphWarning])
+            ]), options.json);
         }
         catch (error) {
             if (error instanceof InvalidArgumentError) {

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

@@ -1,5 +1,5 @@
-import { realpathSync as realpathSyncNative } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readdirSync, realpathSync as realpathSyncNative } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } from 'peaks-loop-shared-channel';
@@ -282,19 +282,39 @@ export function registerAwaitCommand(parent, io) {
             process.exitCode = 1;
             return;
         }
-        // No record-path index is kept for DAG-dispatched batches yet; the caller
-        // is expected to have a single shared record directory. We pass the empty
-        // list — the runner tracks outcomes through its own contract-store writes,
-        // so the dispatcher reaches no slot and reports no results (see the
-        // `recordPaths: []` case in tests/unit/services/dispatch/
-        // sub-agent-dispatchers.test.ts, which pins that empty shape).
-        const input = {
-            batchId: options.batch,
-            dispatchCount: 1,
-            recordPaths: [],
-            ...(timeoutMs !== undefined ? { timeoutMs } : {})
-        };
         try {
+            // Slice 2026-09-16-n1-await-reports: resolve the batch's records from the
+            // session's dispatch directory. `recordPaths` used to be hardcoded to
+            // `[]`, and `awaitBatch` short-circuits on an empty list
+            // (await-batch.ts:134) — so `await` reported zero results and exited 0
+            // for every batch, forever. A batch we cannot locate is now a failure,
+            // not a success with nothing in it.
+            const { readRecord } = await import('../../services/dispatch/dispatch-record-writer.js');
+            const scan = resolveBatchRecords({
+                projectRoot,
+                sessionId: sid,
+                batchId: options.batch,
+                readOne: readRecord
+            });
+            if (scan.recordPaths.length === 0) {
+                const unreadableNote = scan.unreadable.length > 0
+                    ? ` ${scan.unreadable.length} dispatch record(s) there could not be read, so they could not be matched to this batch: ${scan.unreadable.join(', ')}`
+                    : '';
+                printResult(io, fail('sub-agent.await', 'NO_DISPATCH_RECORDS', `No dispatch record with batchId=${options.batch} under ${scan.sessionDir}.${unreadableNote}`, {
+                    ok: false,
+                    batchId: options.batch,
+                    sessionDir: scan.sessionDir,
+                    unreadableRecords: scan.unreadable
+                }, [awaitErrorNextActions('NO_DISPATCH_RECORDS')]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            const input = {
+                batchId: options.batch,
+                dispatchCount: scan.recordPaths.length,
+                recordPaths: scan.recordPaths,
+                ...(timeoutMs !== undefined ? { timeoutMs } : {})
+            };
             const results = await dispatcher.awaitBatch(input);
             const summary = summarizeBatchResults(results);
             printResult(io, ok('sub-agent.await', {
@@ -303,15 +323,18 @@ export function registerAwaitCommand(parent, io) {
                 batchId: options.batch,
                 ide: dispatcher.label,
                 results,
-                summary
-            }, [], [
+                summary,
+                unreadableRecords: scan.unreadable
+            }, scan.unreadable.length > 0
+                ? [`${scan.unreadable.length} unreadable dispatch record(s) in this session were skipped and are NOT part of the results: ${scan.unreadable.join(', ')}`]
+                : [], [
                 // Slice 2026-09-15-s9: corrected. This used to tell users that the
                 // four non-Claude IDEs would report `awaitByLlm: <ide> 1.2 fallback`,
                 // the slice-1.2 marker that slice 1.3 replaced with a real
                 // file-polling await. The text survived because nothing tested it —
                 // no adapter produces that note any more (asserted in
-                // sub-agent-dispatchers.test.ts), and the only code that still emits
-                // it, `awaitByLlmFallback`, has no callers.
+                // sub-agent-dispatchers.test.ts), and the emitter that produced it,
+                // `awaitByLlmFallback`, has since been removed.
                 `Each non-claude-code IDE labels its own results (see the \`note\` field), so a timed-out slot is attributable to the adapter it came from.`
             ]), asJson);
         }
@@ -331,6 +354,9 @@ function awaitErrorNextActions(code) {
     if (code === 'IDE_NOT_SUPPORTED') {
         return 'Switch to claude-code, or rely on LLM-side await for non-claude-code IDEs in slice 1.3.';
     }
+    if (code === 'NO_DISPATCH_RECORDS') {
+        return 'Check --session-id / --project: records live under .peaks/_sub_agents/<sessionId>/. Use the batchId exactly as printed by the dispatch envelope.';
+    }
     return 'See error message; check that --batch matches the dispatch envelope and --timeout is a positive integer ms.';
 }
 /**
@@ -351,6 +377,47 @@ function safeRecordPath(p) {
         return p;
     }
 }
+/**
+ * Slice 2026-09-16-n1-await-reports: which on-disk records belong to a batch.
+ *
+ * Reuses the conventions already in the repo instead of inventing a new one:
+ *   - records live at `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json`
+ *     (`dispatchRecordPath`, src/services/security/safe-settings-path.ts);
+ *   - a record's batch is its own `batchId` field, written by
+ *     `writeInitialDispatchRecord`. The `--batch` branch of `finalize` (below)
+ *     and `findBatchRecords` in heartbeat-watch-command.ts resolve a batch the
+ *     same way: scan the session dir, filter `dispatch-*.json`, compare field.
+ *
+ * `unreadable` lists the `dispatch-*.json` candidates whose batch could NOT be
+ * determined. The caller must not fold them into "no such batch": a record it
+ * cannot read is not evidence that the batch is empty.
+ */
+function resolveBatchRecords(input) {
+    const sessionDir = resolve(input.projectRoot, '.peaks', '_sub_agents', input.sessionId);
+    const recordPaths = [];
+    const unreadable = [];
+    if (!existsSync(sessionDir))
+        return { sessionDir, recordPaths, unreadable };
+    for (const name of readdirSync(sessionDir)) {
+        // `active-dispatches.json` (the index) and `batch-<uuid>.counter.json` are
+        // not records; neither carries a `version`, so `readRecord` would reject
+        // them as "version mismatch". Same filter as the `--batch` branch below.
+        if (!name.startsWith('dispatch-') || !name.endsWith('.json'))
+            continue;
+        const recordPath = safeRecordPath(join(sessionDir, name));
+        let batchId;
+        try {
+            batchId = input.readOne(recordPath).batchId;
+        }
+        catch {
+            unreadable.push(recordPath);
+            continue;
+        }
+        if (batchId === input.batchId)
+            recordPaths.push(recordPath);
+    }
+    return { sessionDir, recordPaths, unreadable };
+}
 export function registerFinalizeCommand(parent, io) {
     addJsonOption(parent
         .command('finalize')

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

@@ -35,7 +35,7 @@ export function registerSliceCommands(program, io) {
         'Each stage reports pass / fail / skipped. ' +
         'Exit 0 only if every stage passes or is skipped.')
         .option('--project <path>', 'target project root', '.')
-        .option('--rid <rid>', 'request id; defaults to the active current-change binding')
+        .option('--rid <rid>', 'request id; REQUIRED — there is no binding to fall back to, and slice check fails without it')
         .option('--refresh-fanout', 're-run the 3-way review fan-out (peaks-rd) even if the review files already exist', false)
         .option('--run-tests', 'opt in to the FULL test suite at the boundary (default is the changed-only suite via `vitest run --changed`); use the peaks-test skill to run the full suite standalone', false)
         .option('--skip-tests', 'skip the unit-test stage entirely (e.g. docs-only slices); use the peaks-test skill to run the full suite manually if you want a separate check', false)
@@ -60,7 +60,7 @@ export function registerSliceCommands(program, io) {
             }
         }
         catch (error) {
-            printResult(io, fail('slice.check', 'SLICE_CHECK_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path is a peaks repo, --rid is correct, and .peaks/_runtime/current-change is valid']), options.json ?? false);
+            printResult(io, fail('slice.check', 'SLICE_CHECK_FAILED', getErrorMessage(error), { projectRoot: options.project }, [`Verify the project path is a peaks repo and --rid names a slice (letters, digits, dots, underscores or dashes): ${options.rid ?? '(no --rid given)'}`]), options.json ?? false);
             process.exitCode = 1;
         }
     });

package/dist/services/artifacts/artifact-prerequisites.js

@@ -237,10 +237,32 @@ const PRD_CONTENT = {
     description: 'PRD artifact must contain Goal and Acceptance criteria sections before handoff',
     mustContain: ['## Goals', '## Acceptance']
 };
+// R10 (2026-09-16): the second marker used to be the bare `test(` inside
+// `mustContain` — i.e. ALL markers required. That made the gate satisfiable
+// only by MENTIONING the literal string in prose, never by honest test code,
+// because this repo's own BDD Test Style Contract
+// (`skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md:170`) names BOTH
+// idioms — "The first string-literal argument of `it()` / `test()` MUST
+// describe business behavior" — and `it(` is the dominant one by ~8x.
+// Measured 2026-09-16 (`grep -rho '\bit(' tests | wc -l`, same for `test(`):
+// `it(` 3015 vs `test(` 372 across `tests/`; the three test files slice
+// 2026-09-16-codegraph-index-integrity added contain `it(` 58 / `test(` 0.
+// The gate was in fact passing on artifacts whose ONLY `test(` was prose —
+// including this repo's own generated template `buildTestCases`
+// (`src/services/evidence/evidence-generator.ts`), which literally reads
+// "no new tests; behavior preserved" and satisfied the marker anyway.
+// Both idioms are therefore accepted via `mustContainAny` — an existing
+// field on this type, already used by PERF_BASELINE / AUDIT_SECURITY /
+// MUT_REPORT — while `## Test cases` stays a hard `mustContain`.
+// Do NOT "tighten" this back to a single idiom in `mustContain`: that
+// restores exactly the pass-by-mentioning hole `headingMustContain` was
+// introduced to close (see the field doc comment above), and no honest test
+// file in this repo could then satisfy the gate.
 const UNIT_TESTS = {
     relativePath: 'qa/test-cases/<rid>.md',
     description: 'Unit test files for the implemented changes (enforces peaks-rd Gate B2)',
-    mustContain: ['## Test cases', 'test(']
+    mustContain: ['## Test cases'],
+    mustContainAny: ['test(', 'it(']
 };
 const QA_INITIATED = {
     relativePath: 'qa/.initiated',

package/dist/services/codegraph/codegraph-autorefresh.d.ts

@@ -6,6 +6,22 @@ export type CodegraphAutorefreshResult = {
     reason: 'no-codegraph-dir' | 'index-failed' | 'unavailable';
     note: string;
 };
+/**
+ * The operator-facing line for a refresh that did not happen, or `null` when
+ * there is nothing to report. The ONE place the report/no-report rule lives,
+ * shared by both slice-boundary call sites (`peaks job checkpoint --state
+ * done` and `peaks request transition rd:qa-handoff`) so the two cannot
+ * drift into disagreeing about what counts as visible.
+ *
+ * Returns the result's own `note` verbatim rather than rebuilding a
+ * sentence: that note is where the reason (exit code / upstream error line)
+ * and the remedy live, and a second wording here would be a second truth.
+ *
+ * `no-codegraph-dir` is deliberately SILENT — see the header's A2 note. A
+ * store that exists and did not refresh is a warning; a project that never
+ * set codegraph up is not a defect to report at every slice boundary.
+ */
+export declare function codegraphRefreshNotice(result: CodegraphAutorefreshResult): string | null;
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.

package/dist/services/codegraph/codegraph-autorefresh.js

@@ -15,8 +15,8 @@
 // hook install surface needed), fires exactly once at the true slice
 // boundary, and needs no IDE hook plumbing.
 //
-// The refresh is best-effort and FAIL-SILENT — it never throws and never
-// blocks the checkpoint/transition ok envelope:
+// The refresh is best-effort and never throws, and it never blocks the
+// checkpoint/transition ok envelope:
 //   - No `<projectRoot>/.codegraph/` directory → skip (codegraph was
 //     never initialized for this project; `peaks codegraph init` is a
 //     one-time setup the orchestrator owns).
@@ -29,6 +29,24 @@
 //     human-readable note.
 //   - Any unexpected error → return `unavailable` with a note.
 //
+// A2 (`2026-09-17-codegraph-msg-and-refresh`). The old header said
+// "FAIL-SILENT", and it was: both call sites discarded this result's `note`,
+// so a refresh that DID NOT HAPPEN and one that did were indistinguishable
+// to the operator — the same silent-failure class this job exists to close.
+// "Never blocks the caller" is the correct half and is KEPT; "never tells
+// anyone" was not.
+//
+// The two halves are split by whether a refresh was EXPECTED:
+//   - `no-codegraph-dir` → the project has no codegraph store (or has a
+//     foreign, never-initialized one). Nothing was expected, so nothing is
+//     reported: warning on every slice boundary of every project that never
+//     opted in is noise that trains the reader to skip the line that
+//     matters. The note is still in the JSON envelope.
+//   - `index-failed` / `unavailable` → a store EXISTS and is in use, so the
+//     refresh was expected and did not happen. That is a real failure and
+//     `codegraphRefreshNotice` turns it into an operator-visible warning
+//     naming the reason and the remedy.
+//
 // We do NOT auto-init a genuinely fresh (no `.codegraph/` dir) project:
 // the orchestrator owns that one-time setup. The dangling self-heal above
 // IS an auto-init, but `codegraph init` (WITHOUT `--index`) is fast (~1 s)
@@ -39,6 +57,28 @@ import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized, } from './codegraph-service.js';
 import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
+/**
+ * The operator-facing line for a refresh that did not happen, or `null` when
+ * there is nothing to report. The ONE place the report/no-report rule lives,
+ * shared by both slice-boundary call sites (`peaks job checkpoint --state
+ * done` and `peaks request transition rd:qa-handoff`) so the two cannot
+ * drift into disagreeing about what counts as visible.
+ *
+ * Returns the result's own `note` verbatim rather than rebuilding a
+ * sentence: that note is where the reason (exit code / upstream error line)
+ * and the remedy live, and a second wording here would be a second truth.
+ *
+ * `no-codegraph-dir` is deliberately SILENT — see the header's A2 note. A
+ * store that exists and did not refresh is a warning; a project that never
+ * set codegraph up is not a defect to report at every slice boundary.
+ */
+export function codegraphRefreshNotice(result) {
+    if (result.refreshed)
+        return null;
+    if (result.reason === 'no-codegraph-dir')
+        return null;
+    return result.note;
+}
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.
@@ -62,6 +102,12 @@ function isCodegraphPeaksLoopManaged(projectRoot) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+// A2: the remedy half of an operator-visible failure note. Phrased like the
+// existing follow-up-index warning in `codegraph-exclude-repair.ts` so the
+// two read as one voice; it names the command the LLM/orchestrator re-runs,
+// never a verb the user is asked to type (Human-NL-Choice-Only — the same
+// posture that warning already ships with).
+const REFRESH_REMEDY = 'Run `peaks codegraph index --project <root>` to refresh the codegraph index.';
 function firstMeaningfulLine(text) {
     const trimmed = text.trim();
     if (trimmed.length === 0)
@@ -105,7 +151,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
                 return {
                     refreshed: false,
                     reason: 'index-failed',
-                    note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                    note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}. ${REFRESH_REMEDY}`,
                 };
             }
             // That init just wrote upstream's 99-rule default `exclude`
@@ -126,7 +172,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
             return {
                 refreshed: false,
                 reason: 'index-failed',
-                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}. ${REFRESH_REMEDY}`,
             };
         }
         return { refreshed: true };
@@ -135,7 +181,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
         return {
             refreshed: false,
             reason: 'unavailable',
-            note: `auto codegraph refresh unavailable: ${errorMessage(error)}`,
+            note: `auto codegraph refresh unavailable: ${errorMessage(error)}. ${REFRESH_REMEDY}`,
         };
     }
 }

package/dist/services/codegraph/codegraph-config-repair-writer.d.ts

@@ -0,0 +1,88 @@
+/** Suffix of the byte-exact pre-repair copy kept next to the config. */
+export declare const CODEGRAPH_CONFIG_BACKUP_SUFFIX = ".bak";
+export type CodegraphExcludeRepairPlan = {
+    /** True when at least one rule would actually be dropped. */
+    readonly changed: boolean;
+    /** The `exclude` array after the removal. */
+    readonly exclude: readonly string[];
+    /** Rules actually present in `exclude` and dropped, in config order. */
+    readonly removedRules: readonly string[];
+};
+/**
+ * Pure: given the current `exclude` list and the rules to drop, return
+ * the new list. No fs, no clock, no serialization.
+ *
+ * A rule named in `rulesToRemove` but absent from `exclude` is NOT
+ * invented — the result is a subset of the input, so a caller can
+ * never add a rule by accident. Removing an already-absent rule is a
+ * no-op, which is what makes the whole repair idempotent: feeding the
+ * repaired list back in yields `changed: false`.
+ */
+export declare function repairCodegraphExclude(input: {
+    readonly exclude: readonly string[];
+    readonly rulesToRemove: readonly string[];
+}): CodegraphExcludeRepairPlan;
+/**
+ * Pure: given the current `include` list and the patterns to append, return
+ * the new list. The mirror of `repairCodegraphExclude`, in the other
+ * direction — a SUPERSET operation instead of a subset one.
+ *
+ * A pattern already present is not appended twice: the include reconciler
+ * already guarantees that, but this function is the writer's own last line
+ * of defence, and a duplicated glob in a third-party config would be a
+ * visible defect even though it changes no matching behaviour.
+ */
+export declare function repairCodegraphInclude(input: {
+    readonly include: readonly string[];
+    readonly patternsToAdd: readonly string[];
+}): {
+    readonly changed: boolean;
+    readonly include: readonly string[];
+    readonly addedPatterns: readonly string[];
+};
+export type CodegraphConfigRepairPlan = {
+    /** Rules from the exclude reconciler to drop. */
+    readonly rulesToRemove: readonly string[];
+    /** Patterns from the include reconciler to append. */
+    readonly includePatternsToAdd: readonly string[];
+};
+export type CodegraphConfigRepairOutcome = {
+    readonly applied: false;
+    readonly reason: 'nothing-to-repair';
+    readonly removedRules: readonly string[];
+    readonly addedIncludePatterns: readonly string[];
+} | {
+    readonly applied: true;
+    readonly configPath: string;
+    readonly backupPath: string;
+    readonly removedRules: readonly string[];
+    readonly addedIncludePatterns: readonly string[];
+    readonly excludeCountBefore: number;
+    readonly excludeCountAfter: number;
+    readonly includeCountBefore: number;
+    readonly includeCountAfter: number;
+};
+/**
+ * Apply BOTH config repairs to `<projectRoot>/.codegraph/config.json` in one
+ * atomic rewrite.
+ *
+ * No-op (and no write, no mtime change, no backup) when both lists are
+ * empty. Otherwise: back up the original bytes to `config.json.bak`, then
+ * rewrite the file with `exclude` reduced by exactly the rules that were
+ * both requested and present, and `include` extended by exactly the
+ * patterns that were both requested and absent.
+ *
+ * ONE rewrite, not two. A caller that widened `include` in one write and
+ * dropped the newly-offending `exclude` rules in a second would leave a
+ * window in which the config on disk is worse than it started (the widened
+ * include admits a file that a surviving rule then hides from the index),
+ * and would need two backups to stay rollback-exact. One rewrite through
+ * the same-directory temp file has neither property.
+ *
+ * Throws only on real fs/parse failures and on the containment refusal
+ * above — the caller decides whether that is fatal (`repair-exclude` /
+ * `repair-index` → non-zero exit) or a surfaced warning (`init` → keep
+ * going, the init itself already succeeded). Both are refusals BEFORE
+ * anything is written, so a throw can never half-apply.
+ */
+export declare function applyCodegraphConfigRepair(projectRoot: string, repair: CodegraphConfigRepairPlan): CodegraphConfigRepairOutcome;