peaks-loop 4.1.1 → 4.1.3

package/dist/services/codegraph/codegraph-foreign-removal.js

@@ -0,0 +1,77 @@
+// src/services/codegraph/codegraph-foreign-removal.ts
+//
+// The one destructive act `peaks codegraph init --force` performs: removing a
+// `.codegraph/` that peaks-loop does not own, so a fresh managed index can take
+// its place.
+//
+// Why deletion and not a backup: the owner's ruling on 2026-10-05. Another
+// tool's SQLite file copied to `.codegraph.bak` inside the project root leaves
+// two divergent indices where there was one, and sibling backups at a project
+// root are exactly what this repo's memory-shape and codegraph-containment
+// guards exist to prevent. The caller who passes `--force` has decided the
+// foreign directory should go; the CLI says plainly what it deleted.
+//
+// Two refusals make that safe to hand to a flag:
+//   - a `.codegraph` that is itself a link (symlink, or a Windows junction —
+//     `lstat` reports both) is never removed. Following it would delete files
+//     the project root was only pointing at, which is a different thing from
+//     replacing a directory the project owns. Containment alone does not catch
+//     it: a junction may legitimately point somewhere INSIDE the root.
+//   - a directory carrying the peaks-loop marker is never removed. `--force`
+//     replaces a FOREIGN index; aimed at our own it would be an index-wipe
+//     wearing an init's name.
+import { existsSync, lstatSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, defaultCodegraphInitGuard } from './codegraph-service.js';
+/** Reported by the CLI as `CODEGRAPH_FOREIGN_REMOVAL_REFUSED`. */
+export class ForeignCodegraphRemovalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ForeignCodegraphRemovalError';
+    }
+}
+/**
+ * Remove `<projectRoot>/.codegraph` and return the path that was deleted.
+ * Throws `ForeignCodegraphRemovalError` for a link or for a
+ * peaks-loop-managed directory.
+ */
+export function removeForeignCodegraphDir(projectRoot) {
+    // The LEXICAL path, deliberately: `assertCodegraphDirContained` hands back a
+    // REALPATH, and removing what a realpath points at would delete the target
+    // of a junction — the opposite of the refusal below.
+    const codegraphDir = join(resolve(projectRoot), CODEGRAPH_DIR_NAME);
+    let stats;
+    try {
+        stats = lstatSync(codegraphDir);
+    }
+    catch {
+        throw new ForeignCodegraphRemovalError(`nothing to remove at ${codegraphDir}: it does not exist, so --force had no foreign ` +
+            '.codegraph/ directory to replace.');
+    }
+    // A junction reports `isSymbolicLink()` on Windows and a plain symlink does
+    // on POSIX, so one check covers both. `rmSync` on a link removes the link
+    // and leaves the target — but the caller asked to replace the project's
+    // `.codegraph`, and replacing a link means the project now points at nothing,
+    // which is not an init anyone agreed to.
+    if (stats.isSymbolicLink()) {
+        throw new ForeignCodegraphRemovalError(`refusing to remove ${codegraphDir}: it is a link (symlink or Windows junction). Delete the ` +
+            'link yourself, then re-run `peaks codegraph init`.');
+    }
+    if (stats.isDirectory() && existsSync(join(codegraphDir, CODEGRAPH_MARKER_NAME))) {
+        throw new ForeignCodegraphRemovalError(`refusing to remove ${codegraphDir}: it carries the peaks-loop marker, so this is ` +
+            'peaks-loop-owned index data, not a foreign directory. --force replaces a foreign ' +
+            '.codegraph/ only.');
+    }
+    rmSync(codegraphDir, { recursive: true, force: true });
+    return codegraphDir;
+}
+/**
+ * Remove the foreign directory and re-run the init guard, so the caller sees an
+ * ordinary fresh init. Kept next to the removal because the two are one
+ * decision: what `--force` means is "replace it, then continue as if it had
+ * never been foreign".
+ */
+export function forcePastForeignConflict(projectRoot) {
+    const removed = removeForeignCodegraphDir(projectRoot);
+    return { removed, outcome: defaultCodegraphInitGuard(projectRoot) };
+}

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

@@ -1,3 +1,4 @@
+import type { CodegraphConfigModel } from './codegraph-project-config.js';
 import { type ReadCodegraphExcludeConfig, type ReadTrackedFiles } from './codegraph-exclude-reconciler.js';
 /**
  * Exit code `peaks codegraph status` uses when the index itself is
@@ -129,10 +130,17 @@ export declare function resolveCodegraphIndexIntegrityVerdict(report: CodegraphI
  */
 export declare function codegraphIndexIntegrityExitCode(verdict: CodegraphIndexIntegrityVerdict, strict: boolean): number | null;
 export type CodegraphIndexIntegrityReport = {
-    /** Absolute path of the inspected `.codegraph/config.json`. */
+    /** Absolute path of the inspected config file — see `codegraph-project-config.ts`. */
     readonly configPath: string;
     /** Absolute path of the inspected index database. */
     readonly databasePath: string;
+    /**
+     * Which config model the include axis was evaluated under. Reported rather
+     * than implied, because it decides whether an empty `includeGap` means
+     * "measured, nothing withheld" or "this upstream's include list cannot
+     * withhold anything" — two different claims that must not read alike.
+     */
+    readonly admissionModel: CodegraphConfigModel;
     /** True when either axis is non-empty. `[OK]` must not be printed then. */
     readonly gap: boolean;
     /** Git-tracked files upstream's extractor would ingest (any extension). */
@@ -143,7 +151,6 @@ export type CodegraphIndexIntegrityReport = {
     readonly includeGap: readonly string[];
     /** Rows in the index's `files` table. */
     readonly indexedFileCount: number;
-    /** Class ② — index rows whose path no longer exists on disk. */
     readonly deadRows: readonly string[];
 };
 /**
@@ -154,7 +161,10 @@ export type CodegraphIndexIntegrityInput = {
     readonly configPath: string;
     readonly databasePath: string;
     readonly trackedFiles: readonly string[];
+    /** The config's `include` globs. Only consulted under `include-whitelist`. */
     readonly include: readonly string[];
+    /** How this upstream's config treats `include` — see `codegraph-project-config.ts`. */
+    readonly admissionModel: CodegraphConfigModel;
     /** Project-relative paths carried by the index's `files` table. */
     readonly indexedPaths: readonly string[];
     /** True when upstream's extractor supports `filePath`'s language. */
@@ -242,27 +252,4 @@ export type CodegraphIndexIntegrityDeps = {
  * callers that must stay alive (`status`, doctor) catch and surface it.
  */
 export declare function inspectCodegraphIndexIntegrity(projectRoot: string, deps?: CodegraphIndexIntegrityDeps): CodegraphIndexIntegrityReport;
-/**
- * Human-readable detail lines for a gapped report, grouped by axis so an
- * operator can tell which defect they have (and whether they have both).
- *
- * Returns an empty array for a clean report — the caller decides whether
- * "clean" is worth printing at all.
- *
- * `blocking` is the user's option C switch, and it changes the TAG, not
- * the finding: advisory (the default) prints `[WARN]` and the command
- * exits 0; strict prints `[FAIL]` and the command exits 75. The verdict
- * word is chosen here rather than by the caller so the two channels
- * cannot disagree about the same report.
- *
- * The remediation sentence NAMES the real command (`peaks codegraph
- * repair-index`). Slice-001 deliberately named none, because naming a
- * command that does not exist yet reproduces the exact failure this gate
- * exists to prevent (an operator following a hint into "command not
- * found"). Slice-002 shipped that command, so the obligation recorded in
- * slice-001's design decision 4 is discharged here — and the name is
- * exported as a constant so the renderer, the doctor message and the
- * error envelope cannot drift from the command that is actually
- * registered.
- */
 export declare function renderCodegraphIndexIntegrityLines(report: CodegraphIndexIntegrityReport, blocking: boolean): readonly string[];

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

@@ -1,6 +1,5 @@
 // src/services/codegraph/codegraph-index-integrity.ts
 //
-// Slice-001 of `2026-09-16-codegraph-index-integrity` — the READ-ONLY
 // integrity report for the two index defects the exclude gate cannot see.
 // Shared by `peaks codegraph status` and the
 // `capability:codegraph-index-integrity` doctor check.
@@ -17,6 +16,13 @@
 //     `include` template has no `**/*.mjs` / `**/*.cjs`, so every `.mjs`
 //     in a repo is dropped while `status` still says the index is fine.
 //
+//     THIS AXIS IS MODEL-DEPENDENT (1.6.2 upgrade). The paragraph above is the
+//     0.7.x config model, where `include` was the whitelist that chose what
+//     got indexed. 1.6.x inverted it — see `codegraph-project-config.ts` — and
+//     there the axis has no set difference to compute. Which of the two is in
+//     force is probed from the installed upstream and reported as
+//     `admissionModel`, never assumed.
+//
 //   ② STALENESS — the index holds `files` rows for paths that no longer
 //     exist on disk (deleted or renamed upstream). Incremental `index`
 //     never deletes them, so the graph keeps answering about files that
@@ -48,11 +54,12 @@
 // tracks upstream instead of drifting from a list we would have to maintain.
 import { createRequire } from 'node:module';
 import { existsSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import Database from 'better-sqlite3';
+import { join } from 'node:path';
+import { openSqlite } from '../sqlite/sqlite-driver.js';
 import { normalizePath } from '../../shared/path-utils.js';
 import { CODEGRAPH_DB_NAME, CODEGRAPH_DIR_NAME } from './codegraph-service.js';
-import { CODEGRAPH_CONFIG_FILENAME, filterAdmittedTrackedFiles, resolveSharedConfig, resolveSharedTrackedFiles } from './codegraph-exclude-reconciler.js';
+import { resolveCodegraphUpstreamLayout } from './codegraph-upstream-layout.js';
+import { filterAdmittedTrackedFiles, resolveSharedConfig, resolveSharedTrackedFiles } from './codegraph-exclude-reconciler.js';
 /**
  * Exit code `peaks codegraph status` uses when the index itself is
  * incomplete or stale — distinct from `CODEGRAPH_INTEGRITY_EXIT_CODE` (74,
@@ -175,11 +182,6 @@ const MAX_REPORTED_PATHS = 10;
  * index's own rows against the filesystem.
  */
 export function inspectCodegraphIndexIntegrityFrom(input) {
-    // Reuse the exclude reconciler's matcher so the two axes cannot disagree
-    // about what `include` admits (AC6) — this is the same function the
-    // exclude gate filters with, not a second implementation of it.
-    const admitted = filterAdmittedTrackedFiles(input.trackedFiles, input.include);
-    const admittedSet = new Set(admitted);
     // The `include` filter is a path test, not an extension test, so a file
     // it drops could be dropped for a directory reason rather than an
     // extension reason. Only the extension axis is this gate's business:
@@ -188,13 +190,14 @@ export function inspectCodegraphIndexIntegrityFrom(input) {
     const supportedTracked = input.trackedFiles
         .map((file) => normalizePath(file))
         .filter((file) => input.supportsPath(file));
-    const includeGap = supportedTracked.filter((file) => !admittedSet.has(file));
+    const includeGap = includeAxisGap(input, supportedTracked);
     const deadRows = input.indexedPaths
         .map((indexedPath) => normalizePath(indexedPath))
         .filter((indexedPath) => !input.pathExists(indexedPath));
     return {
         configPath: input.configPath,
         databasePath: input.databasePath,
+        admissionModel: input.admissionModel,
         gap: includeGap.length > 0 || deadRows.length > 0,
         trackedSourceCount: supportedTracked.length,
         admittedTrackedCount: supportedTracked.length - includeGap.length,
@@ -203,6 +206,31 @@ export function inspectCodegraphIndexIntegrityFrom(input) {
         deadRows
     };
 }
+// Axis ① — supported tracked files the config's `include` globs do not admit,
+// or an empty list when this upstream's `include` CANNOT withhold one.
+//
+// WHY THE MODEL DECIDES THIS (the 1.6.2 upgrade). 0.7.x's `include` was the
+// whitelist that chose what got indexed, so a supported tracked file missing
+// from it was a real omission. 1.6.x's `include` is upstream's own "force INTO
+// the index even when `.gitignore` would drop it" list, with selection driven
+// by `.gitignore` — so an absent list withholds NOTHING. Running the whitelist
+// difference against it does not weaken the gate, it INVERTS it: a freshly
+// initialised project, with no `codegraph.json` at all, would report every
+// supported tracked file as withheld.
+//
+// The set is emptied rather than the axis deleted, and `admissionModel` rides
+// on the report, so "nothing was withheld" and "this list cannot withhold"
+// stay told apart — the rule this module already applies to `clean` vs
+// `not-applicable` vs `not-evaluated`. The matcher is reused from the exclude
+// reconciler (AC6), and is only reached under the model that has a withholding
+// list to test.
+function includeAxisGap(input, supportedTracked) {
+    if (input.admissionModel === 'force-include') {
+        return [];
+    }
+    const admittedSet = new Set(filterAdmittedTrackedFiles(input.trackedFiles, input.include));
+    return supportedTracked.filter((file) => !admittedSet.has(file));
+}
 let cachedUpstreamGrammars = null;
 /**
  * Load upstream's own `grammars` module and return the two functions
@@ -212,9 +240,8 @@ let cachedUpstreamGrammars = null;
  * extension list drifts from upstream silently, and a list derived from
  * `EXTENSION_MAP` would still be a re-derivation of a decision upstream
  * already implements. Calling the decision is exact by construction. The
- * module path is resolved from the package's own `package.json` (the same
- * seam `codegraph-service.ts` uses for the binary), so it follows whichever
- * `@colbymchenry/codegraph` instance this install actually runs.
+ * directory it is read from comes from the shared layout resolver, so it
+ * follows whichever `@colbymchenry/codegraph` instance this install runs.
  *
  * Node's `require` cache makes the second and later loads free; the module
  * body only defines tables and functions (grammar WASM loading is a
@@ -223,8 +250,8 @@ let cachedUpstreamGrammars = null;
 function loadUpstreamGrammars() {
     if (cachedUpstreamGrammars === null) {
         const require = createRequire(import.meta.url);
-        const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
-        const grammarsPath = join(dirname(packageJsonPath), 'dist', 'extraction', 'grammars.js');
+        const { moduleDir } = resolveCodegraphUpstreamLayout();
+        const grammarsPath = join(moduleDir, 'extraction', 'grammars.js');
         cachedUpstreamGrammars = require(grammarsPath);
     }
     return cachedUpstreamGrammars;
@@ -240,10 +267,10 @@ export function upstreamSupportsPath(filePath) {
 /**
  * The project-relative paths recorded in the index's `files` table.
  *
- * Opened `readonly: true` so the gate can never mutate the index's
- * CONTENT, and `fileMustExist: true` so a missing/not-yet-initialized db
- * throws instead of silently creating an empty one (which would report a
- * 100% stale index).
+ * Opened read-only so the gate can never mutate the index's CONTENT, and the
+ * seam refuses a path that is not there rather than creating one: an empty
+ * database made by the open would report a 100% stale index, which reads as a
+ * verdict and is actually an absence.
  *
  * Read-only, exactly stated: opening a WAL database (`journal_mode = wal`
  * is what upstream `dist/db/index.js` sets, and what this repo's own index
@@ -261,7 +288,7 @@ function readIndexedFilePaths(projectRoot) {
     const databasePath = join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_DB_NAME);
     let db;
     try {
-        db = new Database(databasePath, { readonly: true, fileMustExist: true });
+        db = openSqlite(databasePath, { readOnly: true });
     }
     catch (error) {
         // sqlite's own message ("unable to open database file") does not name
@@ -406,10 +433,14 @@ export function inspectCodegraphIndexIntegrity(projectRoot, deps = {}) {
     const config = resolveSharedConfig(deps.config, projectRoot);
     const trackedFiles = resolveSharedTrackedFiles(deps.trackedFiles, projectRoot);
     return inspectCodegraphIndexIntegrityFrom({
-        configPath: join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME),
+        // Both come off the config value, so the file this report NAMES is the
+        // file that was READ and the model that judgement used is the model that
+        // resolved it — no consumer re-derives either.
+        configPath: config.configPath,
         databasePath: join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_DB_NAME),
         trackedFiles,
         include: config.include,
+        admissionModel: config.model,
         indexedPaths: readIndexed(projectRoot),
         supportsPath: supports,
         pathExists: (projectRelativePath) => exists(projectRoot, projectRelativePath)
@@ -438,13 +469,43 @@ export function inspectCodegraphIndexIntegrity(projectRoot, deps = {}) {
  * error envelope cannot drift from the command that is actually
  * registered.
  */
+// The headline's finding list. It names only what was MEASURED, so it can never
+// present a count no input could have produced — at least one entry is always
+// present, because `gap` is the disjunction of these two.
+function describeFindings(report) {
+    const findings = [];
+    if (report.includeGap.length > 0) {
+        findings.push(`${report.includeGap.length} supported tracked file(s) are not admitted by the config's include globs`);
+    }
+    if (report.deadRows.length > 0) {
+        findings.push(`${report.deadRows.length} index row(s) point at files that no longer exist`);
+    }
+    return findings.join('; ');
+}
+// The include axis' own note, or `null` when there is nothing honest to say.
+//
+// Under `include-whitelist` the axis has a count and the headline carries it;
+// under `force-include` the axis can never fire, so this note EXISTS to explain
+// the silence rather than leave it looking like a measured zero. It is its own
+// indented line, not part of the finding list, so it cannot be read as a reason
+// the index does not cover the repository.
+function includeAxisNoteLines(report) {
+    if (report.admissionModel !== 'force-include') {
+        return [];
+    }
+    return [
+        "  include axis: not applicable — this upstream's `include` list can only add files to " +
+            'the index, never withhold one'
+    ];
+}
 export function renderCodegraphIndexIntegrityLines(report, blocking) {
     if (!report.gap) {
         return [];
     }
     const lines = [
-        `${blocking ? '[FAIL]' : '[WARN]'} codegraph index does not cover the repository: ${report.includeGap.length} supported tracked file(s) are not admitted by the config's include globs, and ${report.deadRows.length} index row(s) point at files that no longer exist.`
+        `${blocking ? '[FAIL]' : '[WARN]'} codegraph index does not cover the repository: ${describeFindings(report)}.`
     ];
+    lines.push(...includeAxisNoteLines(report));
     if (report.includeGap.length > 0) {
         lines.push(`  include gap: ${report.admittedTrackedCount} of ${report.trackedSourceCount} extractor-supported tracked file(s) are admitted by include`);
         for (const filePath of report.includeGap.slice(0, MAX_REPORTED_PATHS)) {
@@ -466,6 +527,6 @@ export function renderCodegraphIndexIntegrityLines(report, blocking) {
     if (!blocking) {
         lines.push(`  advisory: this does not fail the command. Set ${CODEGRAPH_INDEX_STRICT_ENV_VAR}=1 to make it block (exit ${CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE}).`);
     }
-    lines.push(`  fix: run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` — it appends the missing include pattern(s), re-checks the exclude rules against the widened list, and rebuilds the index from scratch (that rebuild is what drops the stale rows).`);
+    lines.push(`  fix: run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` — it drops the config's exclude rules that block tracked source files and rebuilds the index from scratch (that rebuild is what drops the stale rows).`);
     return lines;
 }

package/dist/services/codegraph/codegraph-preflight-service.js

@@ -1,6 +1,5 @@
 // src/services/codegraph/codegraph-preflight-service.ts
 //
-// Slice 2026-09-03-codegraph-preread (Option A) — pre-dispatch codegraph
 // preflight for RD planning. peaks-code's RD dispatch path calls
 // `buildCodegraphPreflightBlock` BEFORE composing the RD sub-agent prompt
 // (src/cli/commands/dispatch-commands.ts) so the RD plans against the real
@@ -15,7 +14,6 @@
 //      absent, run `codegraph init` + `codegraph index` (best-effort).
 //   2. Skip-when-fresh: when `.codegraph/` already carries the
 //      peaks-loop marker, do NOT re-init / re-index on every dispatch
-//      (index is incremental; the sibling rid-2026-09-03-codegraph-autorefresh
 //      owns post-slice refresh). A foreign-schema `.codegraph/` is never
 //      clobbered — we fail-soft instead.
 //   3. Read a BOUNDED project-structure summary from the index
@@ -33,6 +31,7 @@
 import { mkdirSync } from 'node:fs';
 import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, isCodegraphInitialized, writeCodegraphMarker } from './codegraph-service.js';
 import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+import { dropSqliteBackendAdvice, isBackendRuleLine } from './codegraph-backend-advice.js';
 import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
 import { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES, normalizeCodegraphPath, parseFilesPayload } from './codegraph-preflight-structure.js';
 export { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES } from './codegraph-preflight-structure.js';
@@ -89,10 +88,20 @@ function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function firstMeaningfulLine(text) {
-    const trimmed = text.trim();
-    if (trimmed.length === 0)
-        return 'no upstream output';
-    const first = trimmed.split(/\r?\n/)[0];
+    // Upstream writes its SQLite-backend block before anything
+    // else, so the raw first line of stderr is a box-drawing frame — and the
+    // line after it names a package this project removed. Neither is the
+    // failure cause, and this function exists to name the cause.
+    //
+    // Removing the block is not enough on its own: the frame's CLOSING rule
+    // survives whenever the cause follows it with no blank line between, which is
+    // exactly what the real binary prints (measured 2026-10-06 — `files` on an
+    // unreadable store leaves `────…`, then `[ERR] Failed to list files: file is
+    // not a database`). A frame is not a cause, so frames are skipped.
+    const first = dropSqliteBackendAdvice(text)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0 && !isBackendRuleLine(line));
     return first !== undefined ? first.slice(0, 200) : 'no upstream output';
 }
 async function readStructure(projectRoot, runner) {

package/dist/services/codegraph/codegraph-project-config.d.ts

@@ -0,0 +1,35 @@
+/** Upstream's per-project config filename at the project root. */
+export declare const CODEGRAPH_PROJECT_CONFIG_FILENAME = "codegraph.json";
+/** Upstream's config filename inside `.codegraph/`. */
+export declare const CODEGRAPH_DIR_CONFIG_FILENAME = "config.json";
+/**
+ * How this upstream's `include` list relates to being indexed.
+ *
+ *   - `force-include`    — 1.6.x. Selection is `.gitignore`-driven; `include`
+ *                          can only ADD files to the index, never withhold
+ *                          one. Config lives at `<root>/codegraph.json`.
+ *   - `include-whitelist`— 0.7.x. `include` decides which tracked files are
+ *                          indexed, so its gaps are real omissions. Config
+ *                          lives at `<root>/.codegraph/config.json`.
+ */
+export type CodegraphConfigModel = 'force-include' | 'include-whitelist';
+export type CodegraphConfigSource = {
+    /** Absolute path of the file upstream reads for this project. */
+    readonly configPath: string;
+    /** True when that file exists. Its ABSENCE is meaningful in both models. */
+    readonly present: boolean;
+    readonly model: CodegraphConfigModel;
+};
+/** The model implied by an upstream `dist/` directory, or `null` when there is none. */
+export declare function codegraphConfigModelFor(moduleDir: string): CodegraphConfigModel | null;
+/** Where the config lives under `model`. Pure: no fs. */
+export declare function codegraphConfigPathFor(projectRoot: string, model: CodegraphConfigModel): string;
+/**
+ * Resolve the source for a KNOWN model. A parameter rather than a lookup so a
+ * caller that has already probed upstream (or a test driving both models) does
+ * not have to reach the installed package twice, and so the model can never
+ * disagree with the path derived from it.
+ */
+export declare function codegraphConfigSourceFor(projectRoot: string, model: CodegraphConfigModel): CodegraphConfigSource;
+/** `codegraphConfigSourceFor` for whichever config model this install runs. */
+export declare function resolveCodegraphConfigSource(projectRoot: string): CodegraphConfigSource;

package/dist/services/codegraph/codegraph-project-config.js

@@ -0,0 +1,90 @@
+// src/services/codegraph/codegraph-project-config.ts
+//
+// ONE answer to "which file holds this project's codegraph config, and what
+// does its `include` list MEAN", for every reader and writer of that file.
+//
+// WHY THIS EXISTS (the 1.6.2 upgrade). Before it, one constant covered every
+// site: join `.codegraph/config.json` onto the project root. That rule is
+// false from 1.6.x, and false in two ways at once:
+//
+//   - LOCATION. The only per-project config 1.6.x reads is
+//     `<projectRoot>/codegraph.json`. `init` does not write
+//     `.codegraph/config.json` and nothing in the 1.6.x bundle reads it, so
+//     every read of the old path is an ENOENT and every write is inert.
+//
+//   - SEMANTICS. 0.7.x's `include` was a WHITELIST: it decided which files
+//     were indexed, so a supported tracked file missing from it was silently
+//     dropped. 1.6.x's `include` is the opposite — upstream's own words are
+//     "force INTO the index even when `.gitignore` would drop it". An absent
+//     `include` therefore withholds NOTHING in 1.6.x, where the same absence
+//     withheld everything in 0.7.x.
+//
+// The two follow from one upstream fact, so they are resolved together, once,
+// and by PROBE rather than by version string — the same discipline
+// `codegraph-upstream-layout.ts` already established for "where does upstream
+// put its files". The probe is upstream's own project-config module: 0.7.x
+// reads `<projectRoot>/.codegraph/config.json` through `dist/config.js` and
+// ships no `project-config.js`; 1.6.x reads `<projectRoot>/codegraph.json`
+// through `lib/dist/project-config.js` and ships no `config.js`. Both halves
+// measured against real installs of 0.7.10 and 1.6.2.
+//
+// PROBE FAILURE IS FAIL-CLOSED. When no upstream can be probed at all, the
+// model resolves to the whitelist one, which REQUIRES the legacy config to be
+// present before any verdict is claimed — so the gate reports "could not
+// evaluate" rather than silently asserting that nothing is withheld.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CODEGRAPH_DIR_NAME } from './codegraph-service.js';
+import { resolveCodegraphUpstreamLayout } from './codegraph-upstream-layout.js';
+/** Upstream's per-project config filename at the project root. */
+export const CODEGRAPH_PROJECT_CONFIG_FILENAME = 'codegraph.json';
+/** Upstream's config filename inside `.codegraph/`. */
+export const CODEGRAPH_DIR_CONFIG_FILENAME = 'config.json';
+/**
+ * Upstream's module that reads the project-root config. Its presence is the
+ * 1.6.x layout signature; `null` means "no upstream to probe".
+ */
+const PROJECT_CONFIG_MODULE = 'project-config.js';
+/** The model implied by an upstream `dist/` directory, or `null` when there is none. */
+export function codegraphConfigModelFor(moduleDir) {
+    // An empty `moduleDir` is the layout resolver's "nothing resolved" value.
+    // Without this guard `join('', 'project-config.js')` becomes the RELATIVE
+    // path `project-config.js`, whose existence would depend on the process's
+    // working directory — a probe that answers about the cwd instead of about
+    // upstream.
+    if (moduleDir === '') {
+        return null;
+    }
+    return existsSync(join(moduleDir, PROJECT_CONFIG_MODULE)) ? 'force-include' : 'include-whitelist';
+}
+/** Where the config lives under `model`. Pure: no fs. */
+export function codegraphConfigPathFor(projectRoot, model) {
+    return model === 'force-include'
+        ? join(projectRoot, CODEGRAPH_PROJECT_CONFIG_FILENAME)
+        : join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_DIR_CONFIG_FILENAME);
+}
+/**
+ * Resolve the source for a KNOWN model. A parameter rather than a lookup so a
+ * caller that has already probed upstream (or a test driving both models) does
+ * not have to reach the installed package twice, and so the model can never
+ * disagree with the path derived from it.
+ */
+export function codegraphConfigSourceFor(projectRoot, model) {
+    const configPath = codegraphConfigPathFor(projectRoot, model);
+    return { configPath, present: existsSync(configPath), model };
+}
+/** `codegraphConfigSourceFor` for whichever config model this install runs. */
+export function resolveCodegraphConfigSource(projectRoot) {
+    return codegraphConfigSourceFor(projectRoot, resolveCodegraphConfigModel());
+}
+function resolveCodegraphConfigModel() {
+    try {
+        const probed = codegraphConfigModelFor(resolveCodegraphUpstreamLayout().moduleDir);
+        return probed ?? 'include-whitelist';
+    }
+    catch {
+        // No installed upstream to probe — see the module header: fail CLOSED, so
+        // the caller demands the legacy config before claiming any verdict.
+        return 'include-whitelist';
+    }
+}

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

@@ -1,5 +1,5 @@
 declare const CODEGRAPH_PACKAGE_NAME = "@colbymchenry/codegraph";
-declare const CODEGRAPH_PACKAGE_VERSION = "0.7.10";
+declare const CODEGRAPH_PACKAGE_VERSION = "1.6.2";
 declare const CODEGRAPH_EXECUTABLE: string;
 declare const ALLOWED_SUBCOMMANDS: readonly ["status", "init", "index", "query", "files", "context", "affected"];
 type CodegraphSubcommand = (typeof ALLOWED_SUBCOMMANDS)[number];
@@ -188,7 +188,6 @@ export type CodegraphAffectedRow = {
 export type WriteCodegraphAffectedContextInput = {
     /** The peaks-loop project root (where `.peaks/_runtime/` lives). */
     readonly projectRoot: string;
-    /** Request id, e.g. `rid-CG-002`. Used as the envelope's anchor. */
     readonly rid: string;
     /** Project-relative file paths passed to `peaks codegraph affected`. */
     readonly files: readonly string[];

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

@@ -1,11 +1,11 @@
 import { existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+import { resolveCodegraphUpstreamLayout } from './codegraph-upstream-layout.js';
 import { getSessionId, getSessionDir } from '../session/index.js';
 import { isInsidePath } from '../../shared/path-utils.js';
 const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
-const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
+const CODEGRAPH_PACKAGE_VERSION = '1.6.2';
 const CODEGRAPH_EXECUTABLE = process.execPath;
 const CODEGRAPH_BINARY_PATH = resolveCodegraphBinaryPath();
 const POSITIONAL_ARGUMENT_PREFIX = '-';
@@ -22,10 +22,11 @@ const NUMERIC_FLAG_NAMES = ['limit', 'maxDepth'];
 const COMMON_OPTION_KEYS = ['subcommand', 'project'];
 const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
     status: [],
-    // Upstream `init` takes NO flags. The `--yes` we used to whitelist
-    // here was passed straight through to `@colbymchenry/codegraph`, which
-    // rejects it with CODEGRAPH_COMMAND_FAILED — and upstream init never
-    // prompts, so there was nothing for it to answer.
+    // peaks-loop passes upstream `init` NO flags. The `--yes` we used to
+    // whitelist was forwarded verbatim and rejected with
+    // CODEGRAPH_COMMAND_FAILED — and init never prompts, so there was nothing
+    // for it to answer. 1.6.2 added `-y, --yes` for a prompt that still does
+    // not exist, which changes nothing: it stays unwhitelisted.
     init: [],
     index: ['force', 'quiet'],
     query: ['search', 'json', 'limit'],
@@ -33,11 +34,11 @@ const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
     context: ['task'],
     affected: ['files', 'json']
 };
+// Upstream's on-disk layout is owned by `codegraph-upstream-layout.ts` — the
+// same resolver the two module oracles and the doctor's probe read, so none
+// of the four can disagree about which install it is reading.
 function resolveCodegraphBinaryPath() {
-    const require = createRequire(import.meta.url);
-    const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
-    const binaryPath = resolve(dirname(packageJsonPath), 'dist', 'bin', 'codegraph.js');
-    return binaryPath;
+    return resolveCodegraphUpstreamLayout().binaryPath;
 }
 function assertSupportedSubcommand(subcommand) {
     if (!ALLOWED_SUBCOMMANDS.includes(subcommand)) {
@@ -331,7 +332,6 @@ function inspectCandidateCodegraphDir(codegraphDir) {
     const markerPath = join(codegraphDir, CODEGRAPH_MARKER_NAME);
     if (existsSync(markerPath)) {
         // Marker present but no codegraph.db → the dangling state left by the
-        // pre-fix rid-CG-001 auto-stake (marker stamped without running
         // upstream init). Report 'fresh' so consumers re-run upstream init
         // (idempotent, creates the db) instead of treating the schema as
         // fully initialized.

package/dist/services/codegraph/codegraph-upstream-layout.d.ts

@@ -0,0 +1,24 @@
+export type CodegraphUpstreamLayout = {
+    /**
+     * Absolute path of the script to spawn with `process.execPath`. Empty
+     * string when NO candidate directory holds an entry at all — the caller
+     * then fails with a path it can name rather than with a silent `undefined`.
+     */
+    readonly binaryPath: string;
+    /**
+     * Absolute path of the directory holding upstream's JS modules
+     * (`types.js`, `extraction/grammars.js`). Same `dist/` the entry's `bin/`
+     * lives under, so one probe locates both.
+     */
+    readonly moduleDir: string;
+};
+/**
+ * Resolve upstream's layout for one `package.json` path.
+ *
+ * `packageJsonPath` is a parameter rather than a lookup because the doctor's
+ * yarn-pnp fallback reaches the same package by a filesystem walk and needs
+ * the layout for THAT path, not for whatever `createRequire` finds.
+ */
+export declare function codegraphUpstreamLayoutFor(packageJsonPath: string): CodegraphUpstreamLayout;
+/** `codegraphUpstreamLayoutFor` for whichever install this process runs against. */
+export declare function resolveCodegraphUpstreamLayout(): CodegraphUpstreamLayout;