peaks-loop 4.0.43 → 4.0.44

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

@@ -5,6 +5,36 @@ import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } f
 import { writeLogEntry } from '../../services/log/logger.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { summarizeBatchResults } from './sub-agent-shared.js';
+/** The one selection rule `--request-id` and `--batch` now share. */
+export const FINALIZE_SELECTION_RULE = 'prefer status=queued; among those, newest by record createdAt (then filename); ' +
+    'no queued match means nothing is finalized';
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * (this session holds six records for `2026-09-12-defect-remediation`) it
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export function selectFinalizeTarget(candidates) {
+    const queued = candidates.filter(candidate => candidate.status === 'queued');
+    if (queued.length === 0)
+        return null;
+    return [...queued].sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.recordPath.localeCompare(a.recordPath))[0];
+}
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export function describeFinalizeRejection(candidate, chosen) {
+    if (candidate.status !== 'queued' || chosen === null) {
+        return 'status is ' + candidate.status;
+    }
+    return 'superseded by the newer queued record ' + chosen.recordPath;
+}
 export function registerShareCommand(parent, io) {
     addJsonOption(parent
         .command('share')
@@ -329,6 +359,31 @@ export function registerFinalizeCommand(parent, io) {
                 const finalized = [];
                 const skipped = [];
                 const errors = [];
+                let selection = null;
+                /**
+                 * N2 — one unreadable record must not abort the sweep.
+                 *
+                 * Skipping `active-dispatches.json` and `batch-*.counter.json` by
+                 * FILENAME removed the two non-record files that happened to be in the
+                 * directory, but a single stale or foreign `dispatch-*.json` (an old
+                 * `version`, hand-edited JSON, a truncated write) still made
+                 * `readRecord` throw from OUTSIDE any try/catch — and the throw
+                 * escaped to the action's outer handler, so `--request-id` AND
+                 * `--batch` both died with `FINALIZE_ERROR` and exit 1 without
+                 * touching a single healthy record.
+                 *
+                 * A record that cannot be read is now reported in `errors[]` and
+                 * skipped; every other record is processed as before.
+                 */
+                const tryReadRecord = (recordPath) => {
+                    try {
+                        return readRecord(recordPath);
+                    }
+                    catch (e) {
+                        errors.push({ recordPath, error: getErrorMessage(e) });
+                        return null;
+                    }
+                };
                 const applyOutcome = (recordPath, rid) => {
                     markCompleted({ recordPath, now: () => new Date(), status: mapped.status, outcome: mapped.outcome, projectRoot });
                     finalized.push({ recordPath, requestId: rid, status: mapped.status });
@@ -352,29 +407,59 @@ export function registerFinalizeCommand(parent, io) {
                     const fs2 = await import('node:fs');
                     const path2 = await import('node:path');
                     const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
-                    let resolvedPath = null;
+                    const candidates = [];
                     if (fs2.existsSync(dir)) {
                         for (const f of fs2.readdirSync(dir)) {
-                            if (!f.endsWith('.json'))
+                            // Only dispatch records are readable records. The session
+                            // directory also holds `active-dispatches.json` (an index)
+                            // and `batch-<uuid>.counter.json` (batch counters); neither
+                            // carries a `version` field, so `readRecord` on them throws
+                            // `Dispatch record version mismatch ... got undefined`. The
+                            // `--batch` branch below has always used this same filter.
+                            if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
                             const p = path2.join(dir, f);
-                            const r = readRecord(p);
-                            if (r.requestId === options.requestId) {
-                                resolvedPath = p;
-                                break;
-                            }
+                            const r = tryReadRecord(p);
+                            if (r === null || r.requestId !== options.requestId)
+                                continue;
+                            candidates.push({
+                                recordPath: p,
+                                requestId: r.requestId,
+                                status: r.status,
+                                createdAt: r.createdAt
+                            });
                         }
                     }
-                    if (!resolvedPath) {
+                    if (candidates.length === 0) {
                         printResult(io, fail('sub-agent.finalize', 'RECORD_NOT_FOUND', 'No dispatch record for requestId=' + options.requestId, { ok: false }, ['Check --request-id matches the dispatch envelope.']), asJson);
                         process.exitCode = 1;
                         return;
                     }
-                    try {
-                        applyOutcome(resolvedPath, options.requestId);
+                    // N3: same rule as `--batch` — see `selectFinalizeTarget`.
+                    const chosen = selectFinalizeTarget(candidates);
+                    selection = {
+                        requestId: options.requestId,
+                        rule: FINALIZE_SELECTION_RULE,
+                        matched: candidates.length,
+                        chosen: chosen?.recordPath ?? null,
+                        rejected: candidates
+                            .filter(candidate => candidate !== chosen)
+                            .map(candidate => ({
+                            recordPath: candidate.recordPath,
+                            status: candidate.status,
+                            reason: describeFinalizeRejection(candidate, chosen)
+                        }))
+                    };
+                    for (const rejected of selection.rejected) {
+                        skipped.push({ recordPath: rejected.recordPath, reason: rejected.reason });
                     }
-                    catch (e) {
-                        errors.push({ recordPath: resolvedPath, error: getErrorMessage(e) });
+                    if (chosen !== null) {
+                        try {
+                            applyOutcome(chosen.recordPath, chosen.requestId);
+                        }
+                        catch (e) {
+                            errors.push({ recordPath: chosen.recordPath, error: getErrorMessage(e) });
+                        }
                     }
                 }
                 else {
@@ -386,7 +471,9 @@ export function registerFinalizeCommand(parent, io) {
                             if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
                             const p = path2.join(dir, f);
-                            const r = readRecord(p);
+                            const r = tryReadRecord(p);
+                            if (r === null)
+                                continue;
                             if (r.batchId !== options.batch)
                                 continue;
                             if (r.status !== 'queued') {
@@ -402,7 +489,20 @@ export function registerFinalizeCommand(parent, io) {
                         }
                     }
                 }
-                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], errors.length > 0 ? ['Re-run after fixing.'] : ['All targeted records transitioned out of queued.']), asJson);
+                const hints = [];
+                if (errors.length > 0) {
+                    hints.push('Re-run after fixing; unreadable records are listed in errors[] and were skipped, not fatal.');
+                }
+                else if (finalized.length === 0 && skipped.length > 0) {
+                    hints.push('Nothing was finalized: every matching record had already left `queued`. See skipped[] for each record\'s status.');
+                }
+                else {
+                    hints.push('All targeted records transitioned out of queued.');
+                }
+                if (selection !== null) {
+                    hints.push(`--request-id selection (${selection.rule}): chose ${selection.chosen ?? '(none)'} of ${selection.matched} matching record(s); ${selection.rejected.length} rejected.`);
+                }
+                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, selection, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], hints), asJson);
                 if (errors.length > 0)
                     process.exitCode = 1;
             }

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

@@ -38,6 +38,7 @@
 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';
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.
@@ -107,6 +108,17 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
                     note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
                 };
             }
+            // That init just wrote upstream's 99-rule default `exclude`
+            // template, some of which block tracked source files — the same
+            // self-heal the CLI's `peaks codegraph init` performs, via the
+            // same shared helper. Skipped, this path would stamp the
+            // peaks-loop marker over an incomplete index that no later
+            // `init` (it would no-op) could ever repair.
+            //
+            // Never throws (the helper catches everything), and
+            // `reindex: false` because the index call below covers the
+            // recovered files.
+            await repairCodegraphExcludeFromProject(projectRoot, runner, { reindex: false });
         }
         const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
         const result = await executeCodegraphInvocation(invocation, runner);

package/dist/services/codegraph/codegraph-exclude-integrity.d.ts

@@ -0,0 +1,61 @@
+import { type CodegraphExcludeViolation } from './codegraph-exclude-reconciler.js';
+/**
+ * Exit code `peaks codegraph status` uses when the index is
+ * demonstrably incomplete. Distinct from the upstream pass-through
+ * exit code and from `CODEGRAPH_INIT_CONFLICT_EXIT_CODE` (73) so a CI
+ * job can tell "codegraph said no" apart from "peaks-loop found a
+ * tracked source file the index silently dropped".
+ */
+export declare const CODEGRAPH_INTEGRITY_EXIT_CODE = 74;
+export type CodegraphExcludeRuleImpact = {
+    /** The `exclude` rule that must be dropped. */
+    readonly rule: string;
+    /** Distinct tracked source files this single rule blocks. */
+    readonly blockedCount: number;
+};
+export type CodegraphExcludeIntegrityReport = {
+    /** Absolute path of the reconciled `.codegraph/config.json`. */
+    readonly configPath: string;
+    /** True when at least one tracked source file is blocked. */
+    readonly gap: boolean;
+    /** Tracked files that pass the config's `include` filter at all. */
+    readonly trackedSourceCount: number;
+    /** Distinct tracked source files blocked by at least one rule. */
+    readonly excludedTrackedCount: number;
+    /** One entry per (file, rule) pair — see S1's reconciler. */
+    readonly violations: readonly CodegraphExcludeViolation[];
+    /** Rules that must be dropped; empty exactly when `gap` is false. */
+    readonly rulesToRemove: readonly string[];
+    /** Per-rule blocked-file counts, in `rulesToRemove` order. */
+    readonly ruleImpacts: readonly CodegraphExcludeRuleImpact[];
+};
+/**
+ * True when `<projectRoot>/.codegraph/config.json` exists, i.e. when an
+ * exclude list is actually in play here. Both consumers use this to
+ * stay SILENT on a project that never ran `peaks codegraph init`: there
+ * is no exclusion to report, and a missing config is not a finding.
+ *
+ * Note the difference from `isCodegraphInitialized` in
+ * `codegraph-service.ts`, which probes `codegraph.db` (upstream's own
+ * definition of "initialized"). The exclude list is written by upstream
+ * init, so its presence is the narrower question this module asks.
+ */
+export declare function isCodegraphExcludeConfigPresent(projectRoot: string): boolean;
+/**
+ * Read the project's git-tracked files + `.codegraph/config.json` and
+ * fold the reconciliation into a report.
+ *
+ * Throws (never silently degrades) when the project is not a git work
+ * tree, when the config is missing, or when it is malformed — callers
+ * that must stay alive (doctor, `status`) catch and surface the reason.
+ */
+export declare function inspectCodegraphExcludeIntegrity(projectRoot: string): CodegraphExcludeIntegrityReport;
+/**
+ * Human-readable detail lines for a gapped report: the headline count,
+ * then the offending rules, then a sample of the blocked files so an
+ * operator can point at a concrete path without re-running anything.
+ *
+ * Returns an empty array for a clean report — the caller decides
+ * whether "clean" is worth printing at all.
+ */
+export declare function renderCodegraphExcludeIntegrityLines(report: CodegraphExcludeIntegrityReport): readonly string[];

package/dist/services/codegraph/codegraph-exclude-integrity.js

@@ -0,0 +1,98 @@
+// src/services/codegraph/codegraph-exclude-integrity.ts
+//
+// Slice S2 of `2026-09-12-codegraph-exclude-integrity` — the READ-ONLY
+// integrity report shared by `peaks codegraph status` and the
+// `capability:codegraph-exclude-integrity` doctor check.
+//
+// S1's reconciler computes the raw truth (`violations` /
+// `rulesToRemove`). This module folds it into a verdict-shaped report
+// that both consumers can render and gate on, so neither of them has
+// to re-derive "is there a gap, how big, and which rules cause it".
+//
+// It NEVER writes `.codegraph/config.json`. The only write path is
+// `codegraph-exclude-repair.ts`, reachable from `peaks codegraph init`
+// (fresh-initialization self-heal) and the explicit
+// `peaks codegraph repair-exclude` command. Read stays read.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CODEGRAPH_CONFIG_FILENAME, reconcileCodegraphExcludeFromProject } from './codegraph-exclude-reconciler.js';
+import { CODEGRAPH_DIR_NAME } from './codegraph-service.js';
+/**
+ * Exit code `peaks codegraph status` uses when the index is
+ * demonstrably incomplete. Distinct from the upstream pass-through
+ * exit code and from `CODEGRAPH_INIT_CONFLICT_EXIT_CODE` (73) so a CI
+ * job can tell "codegraph said no" apart from "peaks-loop found a
+ * tracked source file the index silently dropped".
+ */
+export const CODEGRAPH_INTEGRITY_EXIT_CODE = 74;
+/** How many offending rules and blocked files we name on the human path. */
+const MAX_REPORTED_RULES = 10;
+const MAX_REPORTED_FILES = 10;
+/**
+ * True when `<projectRoot>/.codegraph/config.json` exists, i.e. when an
+ * exclude list is actually in play here. Both consumers use this to
+ * stay SILENT on a project that never ran `peaks codegraph init`: there
+ * is no exclusion to report, and a missing config is not a finding.
+ *
+ * Note the difference from `isCodegraphInitialized` in
+ * `codegraph-service.ts`, which probes `codegraph.db` (upstream's own
+ * definition of "initialized"). The exclude list is written by upstream
+ * init, so its presence is the narrower question this module asks.
+ */
+export function isCodegraphExcludeConfigPresent(projectRoot) {
+    return existsSync(join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME));
+}
+/**
+ * Read the project's git-tracked files + `.codegraph/config.json` and
+ * fold the reconciliation into a report.
+ *
+ * Throws (never silently degrades) when the project is not a git work
+ * tree, when the config is missing, or when it is malformed — callers
+ * that must stay alive (doctor, `status`) catch and surface the reason.
+ */
+export function inspectCodegraphExcludeIntegrity(projectRoot) {
+    const result = reconcileCodegraphExcludeFromProject(projectRoot);
+    const blockedCounts = new Map();
+    for (const violation of result.violations) {
+        blockedCounts.set(violation.matchedRule, (blockedCounts.get(violation.matchedRule) ?? 0) + 1);
+    }
+    return {
+        configPath: join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME),
+        gap: result.excludedTrackedCount > 0,
+        trackedSourceCount: result.trackedSourceCount,
+        excludedTrackedCount: result.excludedTrackedCount,
+        violations: result.violations,
+        rulesToRemove: result.rulesToRemove,
+        ruleImpacts: result.rulesToRemove.map((rule) => ({ rule, blockedCount: blockedCounts.get(rule) ?? 0 }))
+    };
+}
+/**
+ * Human-readable detail lines for a gapped report: the headline count,
+ * then the offending rules, then a sample of the blocked files so an
+ * operator can point at a concrete path without re-running anything.
+ *
+ * Returns an empty array for a clean report — the caller decides
+ * whether "clean" is worth printing at all.
+ */
+export function renderCodegraphExcludeIntegrityLines(report) {
+    if (!report.gap) {
+        return [];
+    }
+    const lines = [
+        `[FAIL] codegraph index is incomplete: ${report.excludedTrackedCount} of ${report.trackedSourceCount} tracked source files are excluded by ${report.rulesToRemove.length} rule(s).`
+    ];
+    for (const impact of report.ruleImpacts.slice(0, MAX_REPORTED_RULES)) {
+        lines.push(`  rule ${impact.rule} blocks ${impact.blockedCount} tracked file(s)`);
+    }
+    if (report.ruleImpacts.length > MAX_REPORTED_RULES) {
+        lines.push(`  … and ${report.ruleImpacts.length - MAX_REPORTED_RULES} more rule(s)`);
+    }
+    for (const violation of report.violations.slice(0, MAX_REPORTED_FILES)) {
+        lines.push(`  excluded: ${violation.path} <- ${violation.matchedRule}`);
+    }
+    if (report.violations.length > MAX_REPORTED_FILES) {
+        lines.push(`  … and ${report.violations.length - MAX_REPORTED_FILES} more file/rule pair(s)`);
+    }
+    lines.push('Run `peaks codegraph repair-exclude --project <root>` to drop these rules, back up the config, and rebuild the index.');
+    return lines;
+}

package/dist/services/codegraph/codegraph-exclude-reconciler.d.ts

@@ -0,0 +1,26 @@
+export declare function matchesCodegraphGlob(filePath: string, pattern: string): boolean;
+export type CodegraphExcludeReconcileInput = {
+    readonly trackedFiles: readonly string[];
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+};
+export type CodegraphExcludeViolation = {
+    readonly path: string;
+    readonly matchedRule: string;
+};
+export type CodegraphExcludeReconcileResult = {
+    readonly violations: readonly CodegraphExcludeViolation[];
+    readonly rulesToRemove: readonly string[];
+    readonly trackedSourceCount: number;
+    readonly excludedTrackedCount: number;
+};
+export declare function reconcileCodegraphExclude(input: CodegraphExcludeReconcileInput): CodegraphExcludeReconcileResult;
+export declare const CODEGRAPH_CONFIG_FILENAME = "config.json";
+export type CodegraphExcludeConfig = {
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+};
+export declare function readTrackedFiles(projectRoot: string): readonly string[];
+export declare function assertStringArray(value: unknown, field: string, configPath: string): readonly string[];
+export declare function readCodegraphExcludeConfig(projectRoot: string): CodegraphExcludeConfig;
+export declare function reconcileCodegraphExcludeFromProject(projectRoot: string): CodegraphExcludeReconcileResult;

package/dist/services/codegraph/codegraph-exclude-reconciler.js

@@ -0,0 +1,217 @@
+// src/services/codegraph/codegraph-exclude-reconciler.ts
+//
+// Slice S1 of `2026-09-12-codegraph-exclude-integrity` — the pure
+// reconciliation core. It answers one question:
+//
+//   "Which git-tracked source files does the codegraph `exclude` list
+//    silently block, and which rules must be removed to unblock them?"
+//
+// Why this exists (the real defect): upstream `@colbymchenry/codegraph`
+// ships a 99-entry default `exclude` template matched by *directory
+// name* via `picomatch.isMatch(path, pattern, { dot: true })`. Upstream
+// `mergeConfig` has no separate override channel — `config.json`'s
+// `exclude` array replaces the defaults wholesale — so any default rule
+// whose directory name collides with real source silently drops tracked
+// files from the index while `peaks codegraph status` still reports
+// `[OK] Index is up to date`. This repo has five such rules:
+// `**` + `/artifacts/**`, `**` + `/release/**`, `**` + `/vendor/**`,
+// `**` + `/bin/**`, `**` + `/publish/**`.
+//
+// Scope of this module:
+//   - PURE: `reconcileCodegraphExclude` takes already-resolved data and
+//     computes violations + the rules to remove. No fs, no spawn.
+//   - ADAPTER: `readTrackedFiles` / `readCodegraphExcludeConfig` /
+//     `reconcileCodegraphExcludeFromProject` are the thin
+//     boundary-reading helpers. They READ ONLY — this module never
+//     writes `.codegraph/config.json` (that is S2's repair path).
+//
+// It is deliberately generic: no hardcoded rule list. Any rule that
+// blocks a tracked source file is caught by the same logic, in this
+// repo or any other.
+//
+// NOTE FOR FUTURE EDITORS: glob literals contain the two-character
+// sequence that ends a block comment, so every comment in this file
+// uses `//` lines. Do not convert them to `/* ... */`.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import picomatch from 'picomatch';
+import { normalizePath } from '../../shared/path-utils.js';
+import { CODEGRAPH_DIR_NAME } from './codegraph-service.js';
+// ─────────────────────────────────────────────────────────────────────
+// Glob matching — delegated to `picomatch`, the same engine upstream uses
+//
+// Upstream `@colbymchenry/codegraph` matches its `exclude` / `include`
+// globs with `picomatch.isMatch(path, pattern, { dot: true })`.
+//
+// This module used to re-implement that matcher by hand, covering only
+// `**`, `*` and `?`. That was a silent-failure generator: the hand-rolled
+// version returned `false` for every *extended* glob (`{a,b}`, `[abc]`,
+// `!(...)`), so a config carrying `**/{release,artifacts}/**` was
+// reconciled as clean while the gap was still there — `init` and
+// `repair-exclude` reported success over an incomplete index, which is
+// the exact failure this mechanism exists to prevent. The generated
+// regexes were also superlinear in the number of `**/` segments.
+//
+// So the matcher IS picomatch now: promoted from a transitive dependency
+// of `@colbymchenry/codegraph` to a direct one, pinned to the version
+// already in the tree (4.0.4). No new install weight, no fork of the
+// semantics, and no way to drift from upstream again.
+//
+// `dot: true` keeps upstream's semantics: `*` and `?` also match a
+// leading `.`.
+//
+// NOTE: this delegation was differential-tested against the previous
+// implementation over every git-tracked file in this repo x every rule
+// of both the upstream 99-rule default template and this repo's config,
+// with zero disagreements on the vocabulary the old matcher supported —
+// the only differences being the extended globs it used to get wrong.
+//
+// One side effect of the delegation had to be repaired right after it
+// shipped: `picomatch('')` throws, so a config carrying `"exclude": [""]`
+// made the whole reconciliation throw, and `peaks codegraph status`
+// turned that into `[WARN] … not evaluated` with exit 0 — a silent false
+// pass over a real index gap, which is precisely what this module exists
+// to prevent. Empty / whitespace-only rules are now skipped before
+// compilation (`isUnmatchableRule`), so no single junk entry can mask the
+// verdict of the other rules.
+// ─────────────────────────────────────────────────────────────────────
+const PICOMATCH_OPTIONS = { dot: true };
+// `picomatch(glob, options)` parses the glob once and returns a reusable
+// matcher. Compiling per rule (not per file x rule) is what keeps a
+// reconciliation over N files x M rules linear in N.
+function compileGlob(pattern) {
+    return { pattern, match: picomatch(pattern, PICOMATCH_OPTIONS) };
+}
+// A rule that carries no glob at all — empty or whitespace-only — cannot
+// name a project-relative source path, so it is skipped instead of
+// compiled.
+//
+// Why this guard exists (regression introduced by the very commit that
+// delegated matching to picomatch): `picomatch('')` THROWS
+// ("Expected pattern to be a non-empty string"). A config carrying
+// `"exclude": [""]` therefore aborted the whole reconciliation, and the
+// consumers degraded that throw into a silent false pass — `status`
+// printed `[WARN] codegraph exclude integrity not evaluated` and left
+// the exit code at 0 while tracked source files were still excluded.
+// Skipping the rule is semantically exact (it matches nothing) and keeps
+// every OTHER rule's verdict, so one junk entry can never mask a real
+// gap. `picomatch('   ')` does not throw; it simply matches no real path,
+// so dropping it is a no-op with the same outcome.
+function isUnmatchableRule(pattern) {
+    return pattern.trim().length === 0;
+}
+// Compile a rule list, dropping the rules that cannot match anything.
+function compileRules(patterns) {
+    return patterns.filter((pattern) => !isUnmatchableRule(pattern)).map(compileGlob);
+}
+// Does `filePath` match `pattern` under the same rules upstream uses?
+// Exported so the test suite can pin the glob semantics directly,
+// including the negative case: the artifacts rule must NOT match
+// `src/artifactsman/foo.ts`.
+//
+// Total by construction: an unmatchable rule answers `false` rather than
+// throwing, so no caller can be turned into a false pass by one junk
+// entry in the config. For every non-empty pattern the answer is the
+// picomatch answer, unchanged.
+export function matchesCodegraphGlob(filePath, pattern) {
+    if (isUnmatchableRule(pattern)) {
+        return false;
+    }
+    return compileGlob(pattern).match(normalizePath(filePath));
+}
+// Reconcile the codegraph `exclude` list against the set of git-tracked
+// source files. Pure: no fs, no spawn, no clock.
+//
+// The `include` filter runs first: a rule that only blocks files the
+// index would not ingest anyway (e.g. a markdown-only rule) is not a
+// violation and is not removed.
+export function reconcileCodegraphExclude(input) {
+    // Unmatchable rules are dropped from BOTH lists before compiling — see
+    // `isUnmatchableRule`. An empty `include` entry admits nothing, which
+    // is the same verdict as an explicitly empty `include` list, so it
+    // needs no special case here.
+    const includeRules = compileRules(input.include);
+    const excludeRules = compileRules(input.exclude);
+    const trackedSourceFiles = [];
+    for (const candidate of input.trackedFiles) {
+        const normalizedPath = normalizePath(candidate);
+        if (includeRules.some((rule) => rule.match(normalizedPath))) {
+            trackedSourceFiles.push(normalizedPath);
+        }
+    }
+    const violations = [];
+    const offendingRules = new Set();
+    const blockedFiles = new Set();
+    for (const path of trackedSourceFiles) {
+        for (const rule of excludeRules) {
+            if (!rule.match(path)) {
+                continue;
+            }
+            violations.push({ path, matchedRule: rule.pattern });
+            offendingRules.add(rule.pattern);
+            blockedFiles.add(path);
+        }
+    }
+    return {
+        violations,
+        rulesToRemove: input.exclude.filter((pattern) => offendingRules.has(pattern)),
+        trackedSourceCount: trackedSourceFiles.length,
+        excludedTrackedCount: blockedFiles.size
+    };
+}
+// ─────────────────────────────────────────────────────────────────────
+// Thin boundary adapters — READ ONLY
+// ─────────────────────────────────────────────────────────────────────
+// Upstream `CONFIG_FILENAME` inside `<projectRoot>/.codegraph/`.
+export const CODEGRAPH_CONFIG_FILENAME = 'config.json';
+// Project-relative paths of every git-tracked file, exactly as
+// `git ls-files` reports them. Why git and not an fs walk: the index
+// must cover what git tracks (see the anti-fake-green contract in
+// `src/services/dispatch/dispatch-sub-agent.ts`), so git is the only
+// admissible source of truth.
+//
+// Throws when `projectRoot` is not inside a git work tree — callers
+// decide whether that is fatal; this function never swallows it.
+export function readTrackedFiles(projectRoot) {
+    const stdout = execFileSync('git', ['-C', projectRoot, 'ls-files'], {
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024
+    });
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => normalizePath(line));
+}
+// Exported for S2's repair writer, which re-validates `exclude` on the
+// way out so the read and write paths agree on what a valid config is.
+export function assertStringArray(value, field, configPath) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`codegraph config ${configPath}: "${field}" must be an array of strings`);
+    }
+    return value;
+}
+// Read `<projectRoot>/.codegraph/config.json` and return just the two
+// glob lists the reconciler needs. Read-only: this module never writes
+// that file.
+export function readCodegraphExcludeConfig(projectRoot) {
+    const configPath = join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME);
+    const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`codegraph config ${configPath}: expected a JSON object`);
+    }
+    const record = parsed;
+    return {
+        include: assertStringArray(record.include, 'include', configPath),
+        exclude: assertStringArray(record.exclude, 'exclude', configPath)
+    };
+}
+// Read-only entry point: resolve the project's tracked files + codegraph
+// config from disk and reconcile them. S2's repair path consumes this
+// result and writes the reduced `exclude` list back; S1 only computes.
+export function reconcileCodegraphExcludeFromProject(projectRoot) {
+    const trackedFiles = readTrackedFiles(projectRoot);
+    const { include, exclude } = readCodegraphExcludeConfig(projectRoot);
+    return reconcileCodegraphExclude({ trackedFiles, include, exclude });
+}