peaks-loop 4.1.1 → 4.1.3

package/dist/services/distribution/mcp-install.d.ts

@@ -0,0 +1,95 @@
+import type { IdeAdapter, IdeId } from '../ide/ide-types.js';
+import { type IdeMcpInstallProfile } from '../ide/ide-mcp-install-types.js';
+/** One process the plan wants run, as command + args. Never a joined string. */
+export interface McpInstallCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+/** What one operation is for, so a report can say which step did what. */
+export type McpInstallOperation = 'remove' | 'add';
+export interface McpInstallStep {
+    readonly operation: McpInstallOperation;
+    /** The scope this step acts on; the target scope for an `add`. */
+    readonly scope: string;
+    readonly command: McpInstallCommand;
+}
+/** What a runner says happened. `detail` is surfaced verbatim when it did not. */
+export interface McpInstallOutcome {
+    readonly ok: boolean;
+    readonly detail: string;
+    /**
+     * `false` only when the harness NEVER RENDERED A VERDICT — the deadline killed
+     * it, or it never launched. A non-zero exit answered ("no such registration"),
+     * so an absent value reads as `true`, as does every outcome that predates this
+     * field.
+     */
+    readonly answered?: boolean;
+}
+/** The seam: a test supplies one, the CLI supplies the spawning one below. */
+export type McpInstallRunner = (command: McpInstallCommand) => McpInstallOutcome;
+export interface McpInstallReport {
+    readonly serverName: string;
+    /** Scopes where the removal reported success — i.e. there was something to remove. */
+    readonly removed: readonly string[];
+    /** Scopes where the removal reported failure — normally "nothing was there". */
+    readonly absent: readonly string[];
+    /**
+     * Scopes whose removal never reached a verdict — the harness timed out or never
+     * launched — so it is neither `removed` nor honestly `absent`. Optional because
+     * the install sweep tolerates a failed removal (it is about to write) and never
+     * populates it; the uninstall sweep always does.
+     */
+    readonly unknown?: readonly string[];
+    readonly added: boolean;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/**
+ * The argv that launches THIS installation's read-only MCP server.
+ *
+ * An interpreter and an entry path, in array form: the same shape `mcp serve`
+ * spawns and the same one the read-only executor uses. A bare CLI name would be
+ * a `.cmd` shim on some platforms, and picking a spelling per platform is the
+ * branch this tree forbids — resolving the pair needs none.
+ */
+export declare function resolveMcpServerArgv(): readonly string[];
+/** The plan: one removal per declared scope, then the addition. Order is the contract. */
+export declare function buildMcpInstallPlan(profile: IdeMcpInstallProfile, serverArgv: readonly string[]): readonly McpInstallStep[];
+/** Every removal, then the addition. A failed removal is a fact, not a failure. */
+export declare function runMcpInstallPlan(profile: IdeMcpInstallProfile, serverArgv: readonly string[], runner: McpInstallRunner): McpInstallReport;
+/**
+ * The removal sweep on its own — what `uninstall` is, and all that it is.
+ *
+ * `exit 0` removed it, `exit != 0` answered "no" (absent, unchanged) — but a run the
+ * deadline killed, or one that never launched, ANSWERED NOTHING, and calling that
+ * "nothing was there" is the lie this sweep used to tell. Those scopes are `unknown`,
+ * and `ok` is false whenever any scope is unknown: with a scope the harness never
+ * spoke for, the removal is unconfirmed and the state is not known.
+ */
+export declare function runMcpUninstallPlan(profile: IdeMcpInstallProfile, serverArgv: readonly string[], runner: McpInstallRunner): McpInstallReport;
+/**
+ * One adapter's outcome. `skipped` is a FIRST-CLASS result and not an error: the
+ * install's contract with an adapter that declares no registration entry is
+ * silence, and a caller that has to distinguish "did nothing" from
+ * "failed" needs the distinction to be in the value, not in a log line.
+ */
+export type AdapterMcpInstallResult = {
+    readonly ideId: IdeId;
+    readonly skipped: true;
+    readonly reason: string;
+} | {
+    readonly ideId: IdeId;
+    readonly skipped: false;
+    readonly report: McpInstallReport;
+};
+export declare const NO_MCP_INSTALL_REASON = "adapter declares no mcpInstall profile";
+/** Register this adapter's harness, or report that there is nothing to register. */
+export declare function installMcpForAdapter(adapter: IdeAdapter, serverArgv: readonly string[], runner: McpInstallRunner): AdapterMcpInstallResult;
+/** The same, for the removal side. */
+export declare function uninstallMcpForAdapter(adapter: IdeAdapter, serverArgv: readonly string[], runner: McpInstallRunner): AdapterMcpInstallResult;
+/**
+ * The production runner and its deadline live in `mcp-install-runner.ts` — split
+ * out only to keep this engine within the file-size cap. They are re-exported, so
+ * the boundary is invisible: every caller still imports them from here.
+ */
+export { MCP_INSTALL_TIMEOUT_MS, spawnMcpInstallCommand, spawnMcpInstallRunner } from './mcp-install-runner.js';

package/dist/services/distribution/mcp-install.js

@@ -0,0 +1,179 @@
+// src/services/distribution/mcp-install.ts
+//
+// The vendor-neutral MCP registration engine (spec §8.3). It owns the SHAPE of
+// an install — delete every scope, then add — and owns no harness's spelling of
+// anything: the server key, the scopes and the argv come from the adapter's
+// `mcpInstall` profile, and the process that runs the argv is an injected
+// runner.
+//
+// WHY DELETE-THEN-ADD AND NOT "CHECK, THEN ADD IF ABSENT". The harness's own
+// register verb is not idempotent: the same name in the same scope fails, and
+// there is no `--force` and no `update` to reach for. A conditional add would
+// therefore have to be right about a state it cannot see — so the engine does
+// the one thing that is right in both states: it removes what is there (a
+// removal that finds nothing is tolerated) and then adds. That is also what
+// makes the install SEMANTICALLY idempotent: two runs produce the same argv in
+// the same order, so the registration left behind has the same CONTENT, even
+// though the second run performed operations the first one did too.
+//
+// WHY THE DELETE SWEEPS EVERY SCOPE. The entry can already exist in a scope the
+// install is not writing to — an earlier install, or a user who moved it. The
+// removal names a scope, and the harness fails on the wrong or empty one, so a
+// targeted delete would leave the old entry behind and the add would then fail
+// on the duplicate it left. Sweeping all declared scopes is the only version of
+// this that is correct for a state the engine cannot enumerate.
+//
+// WHAT "ONLY OURS" MEANS HERE. The engine never reads or writes the
+// harness's configuration file. It runs the harness's own removal and addition,
+// and the only key either of them names is the adapter's `serverName` — so no
+// other entry can be touched by construction. The honest limit of that
+// guarantee is the name itself: an entry the USER named the same thing is
+// indistinguishable from ours, and is the one case this cannot tell apart.
+//
+// NO HARNESS BRANCH, NO PLATFORM BRANCH. Every value is either the caller's or
+// the adapter's. `resolveMcpServerArgv` returns an interpreter and an entry path
+// for the same reason `cli-executor.ts` does: a shipped CLI name is a shim on
+// some platforms, and choosing between the two spellings would be the platform
+// branch this module is forbidden to contain.
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertMcpInstallProfile, expandMcpArgv } from '../ide/ide-mcp-install-types.js';
+/** `<packageRoot>` — this file's tree is `<root>/src/services/distribution` or `<root>/dist/…`. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+/**
+ * The argv that launches THIS installation's read-only MCP server.
+ *
+ * An interpreter and an entry path, in array form: the same shape `mcp serve`
+ * spawns and the same one the read-only executor uses. A bare CLI name would be
+ * a `.cmd` shim on some platforms, and picking a spelling per platform is the
+ * branch this tree forbids — resolving the pair needs none.
+ */
+export function resolveMcpServerArgv() {
+    return [process.execPath, join(PACKAGE_ROOT, 'bin', 'peaks.js'), 'mcp', 'serve'];
+}
+/** The plan: one removal per declared scope, then the addition. Order is the contract. */
+export function buildMcpInstallPlan(profile, serverArgv) {
+    assertMcpInstallProfile(profile);
+    const removals = profile.scopes.map((scope) => ({
+        operation: 'remove',
+        scope,
+        command: {
+            command: profile.removeArgv[0] ?? '',
+            args: expandMcpArgv(profile.removeArgv.slice(1), {
+                serverName: profile.serverName,
+                scope,
+                serverArgv
+            })
+        }
+    }));
+    const addition = {
+        operation: 'add',
+        scope: profile.targetScope,
+        command: {
+            command: profile.addArgv[0] ?? '',
+            args: expandMcpArgv(profile.addArgv.slice(1), {
+                serverName: profile.serverName,
+                scope: profile.targetScope,
+                serverArgv
+            })
+        }
+    };
+    return [...removals, addition];
+}
+/** Every removal, then the addition. A failed removal is a fact, not a failure. */
+export function runMcpInstallPlan(profile, serverArgv, runner) {
+    const plan = buildMcpInstallPlan(profile, serverArgv);
+    const removed = [];
+    const absent = [];
+    let detail = '';
+    for (const step of plan) {
+        const outcome = runner(step.command);
+        if (step.operation === 'remove') {
+            if (outcome.ok)
+                removed.push(step.scope);
+            else
+                absent.push(step.scope);
+            continue;
+        }
+        if (!outcome.ok) {
+            return {
+                serverName: profile.serverName,
+                removed,
+                absent,
+                added: false,
+                ok: false,
+                detail: `the registration was not written: ${outcome.detail}`
+            };
+        }
+        detail = `registered in scope '${step.scope}'`;
+    }
+    return { serverName: profile.serverName, removed, absent, added: true, ok: true, detail };
+}
+/**
+ * The removal sweep on its own — what `uninstall` is, and all that it is.
+ *
+ * `exit 0` removed it, `exit != 0` answered "no" (absent, unchanged) — but a run the
+ * deadline killed, or one that never launched, ANSWERED NOTHING, and calling that
+ * "nothing was there" is the lie this sweep used to tell. Those scopes are `unknown`,
+ * and `ok` is false whenever any scope is unknown: with a scope the harness never
+ * spoke for, the removal is unconfirmed and the state is not known.
+ */
+export function runMcpUninstallPlan(profile, serverArgv, runner) {
+    const plan = buildMcpInstallPlan(profile, serverArgv).filter((step) => step.operation === 'remove');
+    const removed = [];
+    const absent = [];
+    const unknown = [];
+    for (const step of plan) {
+        const outcome = runner(step.command);
+        if (outcome.ok)
+            removed.push(step.scope);
+        else if (outcome.answered === false)
+            unknown.push(step.scope);
+        else
+            absent.push(step.scope);
+    }
+    return {
+        serverName: profile.serverName,
+        removed,
+        absent,
+        unknown,
+        added: false,
+        ok: unknown.length === 0,
+        detail: unknown.length > 0
+            ? `the '${profile.serverName}' removal is unconfirmed: ${unknown.length} scope(s) never answered`
+            : removed.length === 0
+                ? `no '${profile.serverName}' registration was present in any declared scope`
+                : `removed '${profile.serverName}' from ${removed.length} scope(s)`
+    };
+}
+export const NO_MCP_INSTALL_REASON = 'adapter declares no mcpInstall profile';
+/** Register this adapter's harness, or report that there is nothing to register. */
+export function installMcpForAdapter(adapter, serverArgv, runner) {
+    const profile = adapter.mcpInstall;
+    if (profile === undefined) {
+        return { ideId: adapter.id, skipped: true, reason: NO_MCP_INSTALL_REASON };
+    }
+    return {
+        ideId: adapter.id,
+        skipped: false,
+        report: runMcpInstallPlan(profile, serverArgv, runner)
+    };
+}
+/** The same, for the removal side. */
+export function uninstallMcpForAdapter(adapter, serverArgv, runner) {
+    const profile = adapter.mcpInstall;
+    if (profile === undefined) {
+        return { ideId: adapter.id, skipped: true, reason: NO_MCP_INSTALL_REASON };
+    }
+    return {
+        ideId: adapter.id,
+        skipped: false,
+        report: runMcpUninstallPlan(profile, serverArgv, runner)
+    };
+}
+/**
+ * The production runner and its deadline live in `mcp-install-runner.ts` — split
+ * out only to keep this engine within the file-size cap. They are re-exported, so
+ * the boundary is invisible: every caller still imports them from here.
+ */
+export { MCP_INSTALL_TIMEOUT_MS, spawnMcpInstallCommand, spawnMcpInstallRunner } from './mcp-install-runner.js';

package/dist/services/distribution/plugin-manifest.d.ts

@@ -0,0 +1,97 @@
+import { type SkillMetadata } from '../skills/skill-registry.js';
+/** Where the generator writes, relative to the package root. */
+export declare const PLUGIN_MANIFEST_RELATIVE_PATH = ".claude-plugin/marketplace.json";
+/**
+ * The server key peaks registers itself under. It is OUR key, not a harness's —
+ * the adapter profiles that name it (`IdeMcpInstallProfile.serverName`) and the
+ * tool-name templates that match it (`IdeAdapter.mcp`) must agree with this one,
+ * which is why it is declared once.
+ */
+export declare const MCP_SERVER_KEY = "peaks";
+/** The subset of `package.json` this render reads. */
+interface PackageManifest {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly author?: string;
+    readonly homepage?: string;
+    readonly repository?: {
+        readonly url?: string;
+    } | string;
+    readonly license?: string;
+    readonly keywords?: readonly string[];
+}
+/** One plugin entry's skill list item — the shape `peaks skill:visibility` reads. */
+interface PluginSkillEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly description: string;
+    readonly userInvocable?: boolean;
+}
+interface GeneratedPluginManifest {
+    readonly metadata: {
+        readonly pluginRoot: string;
+        readonly version: string;
+    };
+    readonly plugins: readonly {
+        readonly name: string;
+        readonly description: string;
+        readonly version: string;
+        readonly author: {
+            readonly name: string;
+        };
+        readonly homepage: string;
+        readonly repository: string;
+        readonly license: string;
+        readonly keywords: readonly string[];
+        /**
+         * Declared, and deliberately not brought live: the plugin channel is not
+         * published by this slice (PRD non-goal), so this is the statement of what
+         * the channel WOULD run, kept true by generation rather than by memory.
+         *
+         * The command is the CLI's own name and subcommand, with no path in it: a
+         * manifest is built on one machine and read on another, so an absolute
+         * interpreter path resolved here would be the build host's. The RUNTIME
+         * registration is a different artefact with a different consumer and does
+         * resolve the pair — see `mcp-install.ts::resolveMcpServerArgv`.
+         */
+        readonly mcpServers: Record<string, {
+            readonly command: string;
+            readonly args: readonly string[];
+        }>;
+        readonly skills: readonly PluginSkillEntry[];
+    }[];
+}
+/** `package.json`, parsed. A missing version is a refusal, not a default. */
+export declare function loadPackageManifest(root?: string): PackageManifest;
+/**
+ * The skill entries, in the registry's order.
+ *
+ * `visibility: internal` is the skill's own declaration that it is an internal
+ * role rather than a front door, and it is the ONE source for `userInvocable` —
+ * the field is emitted only when it is `false`, which is the contract
+ * `skill:visibility` reads ("internal: userInvocable false; public: omitted").
+ */
+export declare function skillEntriesOf(skills: readonly SkillMetadata[]): readonly PluginSkillEntry[];
+/**
+ * Render the manifest. `skills` is passed in rather than loaded here so the one
+ * caller that must fail loudly on an unreadable SKILL.md can do so once.
+ */
+export declare function generatePluginManifest(manifest: PackageManifest, skills: readonly SkillMetadata[]): GeneratedPluginManifest;
+/** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
+export declare function serializePluginManifest(manifest: GeneratedPluginManifest): string;
+/** Absolute path of the committed artifact for a package root. */
+export declare function pluginManifestPath(root?: string): string;
+/**
+ * The whole render for a package root: read the two sources, refuse a skill tree
+ * that did not fully parse, and serialize.
+ *
+ * The `failures` refusal is the load-bearing part. `loadSkillRegistry` reports an
+ * unreadable `SKILL.md` in a `failures` array instead of throwing, so a render
+ * that ignored it would DROP a skill from the manifest and still be
+ * byte-stable — a green CI over a manifest that had silently lost entries. A
+ * drift assertion cannot be stronger than its input, so the input is required to
+ * be complete.
+ */
+export declare function renderPluginManifest(root?: string): Promise<string>;
+export {};

package/dist/services/distribution/plugin-manifest.js

@@ -0,0 +1,126 @@
+// src/services/distribution/plugin-manifest.ts
+//
+// The plugin/distribution manifest as a GENERATED artefact (spec §4.1). One
+// source, two renders: the whitelist artifact is what the read-only claim is
+// made of, and this file is what the distribution channel is told.
+//
+// WHY IT IS GENERATED. The hand-authored `.claude-plugin/marketplace.json` had
+// rotted in the only two fields anybody could check and nobody did: it declared
+// version `2.0.3` while the package was `4.1.2`, and 12 skills while the tree
+// held 22. Root cause is not carelessness — it is that the current distribution
+// channel is `npm i -g`, so nothing ever read the plugin manifest and no failure
+// could be observed from it. A file whose author is a human and whose reader is
+// nobody will drift; the fix is to remove the human from the loop, not to be
+// more careful.
+//
+// CHANGE THE SOURCE, NOT THIS FILE. Everything below is derived, and
+// `tests/unit/services/distribution/plugin-manifest.test.ts` fails the moment
+// the committed artefact differs from a fresh render. A hand edit is therefore
+// not merely overwritten, it is RED. To change the manifest, change
+// `package.json` (a plugin-level field) or the skill's own `SKILL.md`
+// (a skill entry) and re-run `pnpm plugin:manifest`.
+//
+// DETERMINISM. No timestamp, no `Date`, no unordered iteration: skills come back
+// from `loadSkillRegistry`, which sorts by name, and every plugin-level field is
+// copied from `package.json` in a fixed order. Two consecutive runs are
+// byte-identical, which is what makes the CI equality assertion mean something.
+import { readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { repoRoot } from 'peaks-loop-shared/paths';
+import { loadSkillRegistry } from '../skills/skill-registry.js';
+/** Where the generator writes, relative to the package root. */
+export const PLUGIN_MANIFEST_RELATIVE_PATH = '.claude-plugin/marketplace.json';
+/**
+ * The server key peaks registers itself under. It is OUR key, not a harness's —
+ * the adapter profiles that name it (`IdeMcpInstallProfile.serverName`) and the
+ * tool-name templates that match it (`IdeAdapter.mcp`) must agree with this one,
+ * which is why it is declared once.
+ */
+export const MCP_SERVER_KEY = 'peaks';
+/** `package.json`, parsed. A missing version is a refusal, not a default. */
+export function loadPackageManifest(root = repoRoot) {
+    const parsed = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
+        throw new Error('package.json version must be a non-empty string');
+    }
+    return parsed;
+}
+/** A repository URL as a manifest reads it: npm's `.git` suffix is not part of the link. */
+function repositoryUrl(manifest) {
+    const raw = typeof manifest.repository === 'string' ? manifest.repository : manifest.repository?.url;
+    return (raw ?? '').replace(/\.git$/, '');
+}
+/** POSIX-separated, so the artifact is byte-identical whichever OS generated it. */
+function posix(value) {
+    return value.split('\\').join('/');
+}
+/**
+ * The skill entries, in the registry's order.
+ *
+ * `visibility: internal` is the skill's own declaration that it is an internal
+ * role rather than a front door, and it is the ONE source for `userInvocable` —
+ * the field is emitted only when it is `false`, which is the contract
+ * `skill:visibility` reads ("internal: userInvocable false; public: omitted").
+ */
+export function skillEntriesOf(skills) {
+    return skills
+        .filter((skill) => skill.name.startsWith('peaks-'))
+        .map((skill) => ({
+        name: skill.name,
+        path: `./${posix(relative(repoRoot, dirname(skill.skillPath)))}`,
+        description: skill.description,
+        ...(skill.visibility === 'internal' ? { userInvocable: false } : {})
+    }));
+}
+/**
+ * Render the manifest. `skills` is passed in rather than loaded here so the one
+ * caller that must fail loudly on an unreadable SKILL.md can do so once.
+ */
+export function generatePluginManifest(manifest, skills) {
+    return {
+        metadata: { pluginRoot: '.', version: manifest.version },
+        plugins: [
+            {
+                name: manifest.name,
+                description: manifest.description ?? '',
+                version: manifest.version,
+                author: { name: manifest.author ?? '' },
+                homepage: manifest.homepage ?? '',
+                repository: repositoryUrl(manifest),
+                license: manifest.license ?? '',
+                keywords: [...(manifest.keywords ?? [])],
+                mcpServers: {
+                    [MCP_SERVER_KEY]: { command: MCP_SERVER_KEY, args: ['mcp', 'serve'] }
+                },
+                skills: skillEntriesOf(skills)
+            }
+        ]
+    };
+}
+/** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
+export function serializePluginManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+/** Absolute path of the committed artifact for a package root. */
+export function pluginManifestPath(root = repoRoot) {
+    return join(root, PLUGIN_MANIFEST_RELATIVE_PATH);
+}
+/**
+ * The whole render for a package root: read the two sources, refuse a skill tree
+ * that did not fully parse, and serialize.
+ *
+ * The `failures` refusal is the load-bearing part. `loadSkillRegistry` reports an
+ * unreadable `SKILL.md` in a `failures` array instead of throwing, so a render
+ * that ignored it would DROP a skill from the manifest and still be
+ * byte-stable — a green CI over a manifest that had silently lost entries. A
+ * drift assertion cannot be stronger than its input, so the input is required to
+ * be complete.
+ */
+export async function renderPluginManifest(root = repoRoot) {
+    const skills = await loadSkillRegistry(join(root, 'skills'));
+    if (skills.failures.length > 0) {
+        const named = skills.failures.map((failure) => failure.skillPath).join(', ');
+        throw new Error(`Refusing to render the plugin manifest: unreadable skill(s): ${named}`);
+    }
+    return serializePluginManifest(generatePluginManifest(loadPackageManifest(root), skills.skills));
+}

package/dist/services/doctor/doctor-service/checks/codegraph-capability.js

@@ -17,14 +17,14 @@
  * `createRequire(import.meta.url)` to find the package.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { dirname, join, resolve as resolvePath } from 'node:path';
+import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { getErrorMessage } from 'peaks-loop-shared/result';
 import { resolveCodegraphProjectRoot } from '../../../codegraph/codegraph-service.js';
-const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
+import { codegraphUpstreamLayoutFor } from '../../../codegraph/codegraph-upstream-layout.js';
+const CODEGRAPH_EXPECTED_VERSION = '1.6.2';
 const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
 function findCodegraphPackageJsonFallback(startDir) {
-    // Slice rid-CG-007 (downstream safety): yarn-pnp / pnpm-strict /
     // sub-package consumers may not expose `@colbymchenry/codegraph` to
     // `createRequire(import.meta.url).resolve`. The fallback walks up
     // the directory tree from `startDir` looking for
@@ -78,9 +78,13 @@ function defaultCodegraphProbe() {
         // Fall through with version='unknown'; the binary-existence
         // check below is the load-bearing assertion.
     }
+    // Probing, not path-joining: 1.6.x keeps the entry in the per-platform
+    // bundle's `lib/dist/`, not in the main package's own `dist/`. The shared
+    // resolver is the same one the spawn path uses, so the doctor cannot
+    // report "binary exists" at a path the spawn would not use.
     let binaryPath;
     try {
-        binaryPath = resolvePath(dirname(packagePath), 'dist', 'bin', 'codegraph.js');
+        binaryPath = codegraphUpstreamLayoutFor(packagePath).binaryPath;
     }
     catch {
         binaryPath = '';
@@ -131,18 +135,22 @@ function runCheck(probe, managedPathProbe) {
         const versionOk = result.version === CODEGRAPH_EXPECTED_VERSION;
         const managedPathSuffix = renderManagedPathSuffix(managedPath);
         if (!versionOk) {
-            // rid-CG-007: downstream consumers may pull a different
-            // version via yarn-pnp / pnpm-strict. Surface as a warning
-            // (ok: false, severity: warning) so the check does NOT flip
-            // the doctor exit code. Upstream 0.7.x binaries are wire-
-            // compatible with 0.7.10 for the subset peaks-loop exercises
-            // (status / init / index / query / files / context / affected).
+            // version via yarn-pnp / pnpm-strict. Still a warning rather than an
+            // error — the pinned subcommand surface is stable, and a drift is not
+            // by itself a broken install — but the tolerance is NOT the wire
+            // compatibility the old `0.7.x` band had, where patch drift really was
+            // wire-compatible with the pin. 1.6.x is a rewrite of the runtime and
+            // of the index's on-disk schema: opening a 0.7.10-built `.codegraph/`
+            // with it migrates the database, and the migration is not reversible.
+            // So the message states the drift and the pin command and names the
+            // axis that actually moves, instead of reassuring the reader about a
+            // compatibility that does not hold across 0.7.x → 1.6.x.
             return [
                 {
                     id: 'capability:codegraph',
                     ok: false,
                     severity: 'warning',
-                    message: `@colbymchenry/codegraph version drift: expected ${CODEGRAPH_EXPECTED_VERSION}, resolved ${result.version} at ${result.packagePath} — peaks-loop uses an allow-list of subcommands and tolerates 0.7.x wire-compat. Run \`pnpm install @colbymchenry/codegraph@${CODEGRAPH_EXPECTED_VERSION}\` to pin.${managedPathSuffix}`
+                    message: `@colbymchenry/codegraph version drift: expected ${CODEGRAPH_EXPECTED_VERSION}, resolved ${result.version} at ${result.packagePath} — peaks-loop uses an allow-list of subcommands, but the index schema is NOT stable across a major version (0.7.x and 1.6.x cannot share one .codegraph/ directory). Run \`pnpm install @colbymchenry/codegraph@${CODEGRAPH_EXPECTED_VERSION}\` to pin.${managedPathSuffix}`
                 }
             ];
         }
@@ -181,7 +189,6 @@ function run({ options }) {
 function defaultCodegraphManagedPathProbe() {
     return detectManagedCodegraphPath(process.cwd());
 }
-// Slice S3b (rid-s3b-doctor-check-typing): `satisfies` instead of a
 // `: DoctorCheckPlugin` annotation. The annotation widened this object
 // literal to the interface's `run` return type
 // (`readonly DoctorCheck[] | Promise<readonly DoctorCheck[]>`) — an

package/dist/services/doctor/doctor-service/checks/codegraph-index-integrity.js

@@ -62,7 +62,6 @@ function elide(paths) {
 }
 /**
  * 2026-09-17 — `projectRoot` is the doctor's resolved L3 root, NOT
- * `process.cwd()`. It used to read `process.cwd()`, which is a different
  * thing from the root the rest of the doctor was pointed at: a caller that
  * injects `projectRootResolver` (e.g.
  * `tests/unit/doctor/doctor-exit-code-warn-only.test.ts`) got every other
@@ -100,7 +99,7 @@ function renderGapMessage(includeGap, admittedTrackedCount, trackedSourceCount,
 // none while none existed); the command name is a shared constant, so this
 // message cannot drift from the CLI surface it points at.
 function remediation() {
-    return `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`;
+    return `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to drop the blocking exclude rules and rebuild the index without the stale rows.`;
 }
 function run({ options, resolvedL3Root }) {
     const probe = options.codegraphIndexIntegrityProbe ?? (() => defaultProbe(resolvedL3Root));

package/dist/services/doctor/doctor-service/checks/l3-memory-health.d.ts

@@ -1,7 +1,6 @@
 /**
  * Checks for `.peaks/memory/` health (`L3:l3-memory-health` and siblings).
  *
- * Slice 2026-06-13-repair-pre-existing-test-failures: the
  * production MemoryIndex schema (see
  * `src/services/memory/project-memory-service.ts`) uses
  * `version: 1` as the schema marker, NOT `schema_version`.
@@ -11,7 +10,6 @@
  * When no `.peaks/memory/index.json` exists yet, the check passes
  * (fresh project — no memories have been extracted).
  *
- * Slice 2026-09-09-memory-system-overhaul (D) extends the check with the
  * drift findings the original version could not see. It used to report
  * `ok: true` for "index.json is well-formed JSON; 100 hot + 131 warm" and
  * never looked at coverage, orphans, or unclassified files. It now emits,

package/dist/services/doctor/doctor-service/checks/l3-memory-health.js

@@ -1,7 +1,6 @@
 /**
  * Checks for `.peaks/memory/` health (`L3:l3-memory-health` and siblings).
  *
- * Slice 2026-06-13-repair-pre-existing-test-failures: the
  * production MemoryIndex schema (see
  * `src/services/memory/project-memory-service.ts`) uses
  * `version: 1` as the schema marker, NOT `schema_version`.
@@ -11,7 +10,6 @@
  * When no `.peaks/memory/index.json` exists yet, the check passes
  * (fresh project — no memories have been extracted).
  *
- * Slice 2026-09-09-memory-system-overhaul (D) extends the check with the
  * drift findings the original version could not see. It used to report
  * `ok: true` for "index.json is well-formed JSON; 100 hot + 131 warm" and
  * never looked at coverage, orphans, or unclassified files. It now emits,

package/dist/services/doctor/doctor-service/checks/l3-orphan-sessions.d.ts

@@ -6,7 +6,6 @@
  * subdirs that intentionally live under `.peaks/_runtime/`
  * (e.g. `change/`, which routes reviewable artifacts per F3).
  *
- * Slice 2026-06-24-doctor-1xdetector-residual regression net: the
  * reducer MUST exclude `change/` (and other system subdirs added
  * by future F3 changes) — without the exclude-list the doctor
  * flips the summary to fail on every clean workspace, which broke

package/dist/services/doctor/doctor-service/checks/l3-orphan-sessions.js

@@ -6,7 +6,6 @@
  * subdirs that intentionally live under `.peaks/_runtime/`
  * (e.g. `change/`, which routes reviewable artifacts per F3).
  *
- * Slice 2026-06-24-doctor-1xdetector-residual regression net: the
  * reducer MUST exclude `change/` (and other system subdirs added
  * by future F3 changes) — without the exclude-list the doctor
  * flips the summary to fail on every clean workspace, which broke

package/dist/services/doctor/doctor-service/checks/multi-binary-drift.d.ts

@@ -2,7 +2,6 @@
  * Check: PATH-scoped `peaks-loop` binary drift
  * (`build:multi-binary-drift`).
  *
- * Slice 2026-08-05-statusline-sid-only-marker-and-multi-binary-drift-guard
  * (G3/G4). When more than one `peaks-loop` binary is discoverable on
  * `process.env.PATH` AND the discovered versions disagree, the doctor
  * emits a `PEAKS_MULTI_BINARY_DRIFT` warning. The user-reported