peaks-loop 4.1.2 → 4.1.3

package/dist/services/ide/adapters/claude-code-local-state.js

@@ -0,0 +1,112 @@
+// src/services/ide/adapters/claude-code-local-state.ts
+//
+// The readers for Claude Code's OWN on-disk state — its statusline state file and
+// its transcript directory layout. Split out of `claude-code-adapter.ts`,
+// verbatim and with one import apiece, because that file sits far past the
+// 300-line cap and the repo's size ratchet only ever goes down: the adapter
+// needs room for new declared surface, and a self-contained reader leaving is
+// how a file earns that room instead of raising the ceiling.
+//
+// Nothing here is peaks-loop state. Every path below belongs to the harness, and
+// every function tolerates its absence by answering `null` — a machine without a
+// statusline file is not a broken machine.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Above this, a stored value is a percentage rather than a 0–1 fraction. Both
+ * spellings occur in the wild, and nothing needs to know which one the harness
+ * picked.
+ */
+const PERCENT_VERSUS_FRACTION = 1.5;
+/**
+ * Read Claude Code's statusline state file
+ * (`~/.claude/statusline-state.json`) and parse a context-percent key.
+ * Moved from the generic reader in slice
+ * only in the Claude Code adapter.
+ */
+export function readClaudeStatuslinePercent() {
+    const path = join(homedir(), '.claude', 'statusline-state.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const json = JSON.parse(readFileSync(path, 'utf8'));
+        const candidates = ['contextPercent', 'context_usage_percent', 'contextPercentUsed'];
+        for (const key of candidates) {
+            const raw = json[key];
+            if (typeof raw === 'number' && Number.isFinite(raw)) {
+                return raw > PERCENT_VERSUS_FRACTION ? raw / 100 : Math.max(0, Math.min(1, raw));
+            }
+        }
+    }
+    catch (err) {
+        // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs (e.g. broken statusline JSON)
+        return null; // only swallow IO errors
+    }
+    return null;
+}
+/** One directory's worth of the walk: recurse into directories, return a matching file. */
+function scanForFile(dir, fileName, pending) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            pending.push(full);
+        }
+        else if (entry.isFile() && entry.name === fileName) {
+            return full;
+        }
+    }
+    return null;
+}
+/**
+ * Recursive search for `<outerSessionId>.jsonl` under `projectsDir`. The
+ * Mac layout encodes the cwd as a single hash directory; on Mac Claude Code
+ * nests the transcript under that hash with an extra level of subdirectory we
+ * cannot predict ahead of time. A flat readdir misses that branch and returns
+ * null — the silent-failure mode this recursion closes.
+ *
+ * Moved from the generic reader in slice
+ * session id (Claude Code names its transcript by the outer session UUID),
+ * NOT the peaks session id.
+ */
+export function findTranscriptJsonl(projectsDir, outerSessionId) {
+    if (!existsSync(projectsDir))
+        return null;
+    const pending = [projectsDir];
+    try {
+        while (pending.length > 0) {
+            const dir = pending.pop();
+            if (dir === undefined)
+                continue;
+            const found = scanForFile(dir, `${outerSessionId}.jsonl`, pending);
+            if (found !== null)
+                return found;
+        }
+    }
+    catch (err) {
+        // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs
+        return null; // only swallow IO errors
+    }
+    return null;
+}
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export function resolveClaudeTranscriptPath(outerSessionId, projectsDir = join(homedir(), '.claude', 'projects')) {
+    if (typeof outerSessionId !== 'string' || outerSessionId.length === 0)
+        return null;
+    return findTranscriptJsonl(projectsDir, outerSessionId);
+}

package/dist/services/ide/adapters/claude-code-model-window.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 1M-context window size in tokens (documented single choice: 1,000,000).
+ * EXPORTED because the adapter's late 1M rescue (`resolveContextWindowTokens`)
+ * names it too — one number, one declaration, rather than a copy that can drift.
+ */
+export declare const ONE_MILLION_CONTEXT_TOKENS = 1000000;
+/**
+ * Safe-default (non-1M) context window size in tokens. Exported for the same
+ * reason: `resolveContextWindow` compares the heuristic against it.
+ */
+export declare const DEFAULT_CONTEXT_WINDOW_TOKENS = 200000;
+/**
+ * Resolve the currently-active Claude Code model id from a runtime env map.
+ * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or
+ * `undefined` when none is present. Pure + exported for tests; the caller falls
+ * back to the transcript `message.model` when this returns undefined.
+ */
+export declare function resolveClaudeModelFromEnv(env: NodeJS.ProcessEnv | undefined): string | undefined;
+/**
+ * Model-aware context-window size in tokens.
+ *
+ * Detection rule (documented):
+ *   1. Empty / unknown model → DEFAULT_CONTEXT_WINDOW_TOKENS (200_000).
+ *   2. Suffix heuristic — a model id containing `1m` (case-insensitive) is
+ *      treated as 1M-context.
+ *   3. Explicit allowlist — known 1M Claude model ids
+ *      (ONE_MILLION_CONTEXT_MODELS).
+ *   4. Everything else → 200_000 (the safe default).
+ *
+ * Callers MAY additionally infer ≥1M from the observed token count: if
+ * `contextTokens > DEFAULT_CONTEXT_WINDOW_TOKENS`, the model cannot be a
+ * 200K model and must be ≥1M (see `readClaudeTranscriptEstimate`).
+ *
+ * This is the HEURISTIC layer only. Explicit user overrides sit ABOVE it —
+ * see `resolveContextWindow`, which is what the probe actually calls.
+ */
+export declare function modelContextWindowTokens(model: string): number;

package/dist/services/ide/adapters/claude-code-model-window.js

@@ -0,0 +1,113 @@
+// src/services/ide/adapters/claude-code-model-window.ts
+//
+// Which Claude Code model is active, and how many tokens its context window
+// holds. Those are the two questions `resolveClaudeModelFromEnv` and
+// `modelContextWindowTokens` answer, and they are the pair that left
+// `claude-code-adapter.ts`: that file is far past the
+// 300-line cap, the repo's size ratchet only ever goes down, and the adapter
+// needed room for its `mcpInstall` declaration. Same technique, and the same
+// reason, as the `claude-code-local-state.ts` split before it — a self-contained
+// responsibility leaves, instead of the ceiling going up.
+//
+// WHY THIS BLOCK AND NOT ANOTHER. Both functions are PURE: the env map is an
+// argument, and nothing here reads a file, an env var or a process global. So
+// the move needs no rewiring in either direction — the adapter imports both
+// back and nothing here reaches for the adapter — which is what keeps the move
+// a move. It is also the one block in that file whose eslint findings are zero,
+// which a receiving file with no baseline row must be.
+//
+// The vendor spellings below (`ANTHROPIC_*`, `claude-opus-4`) are Claude Code's
+// own. An adapter is the only place they belong (spec §13), which is why this is
+// a second adapter module and not a shared one.
+/**
+ * 1M-context window size in tokens (documented single choice: 1,000,000).
+ * EXPORTED because the adapter's late 1M rescue (`resolveContextWindowTokens`)
+ * names it too — one number, one declaration, rather than a copy that can drift.
+ */
+export const ONE_MILLION_CONTEXT_TOKENS = 1_000_000;
+/**
+ * Safe-default (non-1M) context window size in tokens. Exported for the same
+ * reason: `resolveContextWindow` compares the heuristic against it.
+ */
+export const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
+/**
+ * Known 1M-context Claude model id prefixes whose ids do NOT carry a `1m`
+ * suffix (e.g. `claude-sonnet-4-5-20250929`). The substring match is
+ * intentionally generous — every `claude-sonnet-4*` / `claude-opus-4*`
+ * variant is 1M-context.
+ */
+const ONE_MILLION_CONTEXT_MODELS = ['claude-opus-4', 'claude-sonnet-4'];
+/**
+ * Claude Code runtime env vars that may carry the currently-active model id,
+ * in documented precedence order (first non-empty value wins):
+ *   1. ANTHROPIC_MODEL                — explicit per-run model override
+ *   2. ANTHROPIC_DEFAULT_OPUS_MODEL   — default Opus fallback
+ *   3. ANTHROPIC_DEFAULT_SONNET_MODEL — default Sonnet fallback
+ *   4. ANTHROPIC_DEFAULT_HAIKU_MODEL  — default Haiku fallback
+ *   5. ANTHROPIC_DEFAULT_FABLE_MODEL  — default Fable fallback
+ *   6. CLAUDE_CODE_SUBAGENT_MODEL     — sub-agent model (used when the others
+ *                                       are absent, e.g. a sub-agent-only env)
+ *
+ * Why env-first: the transcript's `message.model` often drops Claude Code's
+ * `[1M]` / `[200K]` suffix marker (observed: `deepseek-v4-flash`), while the
+ * runtime env vars above carry it (`deepseek-v4-flash[1M]`). Reading them
+ * first lets the window resolver see the true context window. This family is
+ * vendor-specific, so it lives ONLY in the claude-code adapter.
+ */
+const CLAUDE_CODE_MODEL_ENV_VARS = [
+    'ANTHROPIC_MODEL',
+    'ANTHROPIC_DEFAULT_OPUS_MODEL',
+    'ANTHROPIC_DEFAULT_SONNET_MODEL',
+    'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+    'ANTHROPIC_DEFAULT_FABLE_MODEL',
+    'CLAUDE_CODE_SUBAGENT_MODEL'
+];
+/**
+ * Resolve the currently-active Claude Code model id from a runtime env map.
+ * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or
+ * `undefined` when none is present. Pure + exported for tests; the caller falls
+ * back to the transcript `message.model` when this returns undefined.
+ */
+export function resolveClaudeModelFromEnv(env) {
+    if (!env)
+        return undefined;
+    for (const name of CLAUDE_CODE_MODEL_ENV_VARS) {
+        const value = env[name];
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+    }
+    return undefined;
+}
+/**
+ * Model-aware context-window size in tokens.
+ *
+ * Detection rule (documented):
+ *   1. Empty / unknown model → DEFAULT_CONTEXT_WINDOW_TOKENS (200_000).
+ *   2. Suffix heuristic — a model id containing `1m` (case-insensitive) is
+ *      treated as 1M-context.
+ *   3. Explicit allowlist — known 1M Claude model ids
+ *      (ONE_MILLION_CONTEXT_MODELS).
+ *   4. Everything else → 200_000 (the safe default).
+ *
+ * Callers MAY additionally infer ≥1M from the observed token count: if
+ * `contextTokens > DEFAULT_CONTEXT_WINDOW_TOKENS`, the model cannot be a
+ * 200K model and must be ≥1M (see `readClaudeTranscriptEstimate`).
+ *
+ * This is the HEURISTIC layer only. Explicit user overrides sit ABOVE it —
+ * see `resolveContextWindow`, which is what the probe actually calls.
+ */
+export function modelContextWindowTokens(model) {
+    const m = model.trim().toLowerCase();
+    if (m.length === 0)
+        return DEFAULT_CONTEXT_WINDOW_TOKENS;
+    if (m.includes('1m'))
+        return ONE_MILLION_CONTEXT_TOKENS;
+    for (const known of ONE_MILLION_CONTEXT_MODELS) {
+        if (m.includes(known))
+            return ONE_MILLION_CONTEXT_TOKENS;
+    }
+    return DEFAULT_CONTEXT_WINDOW_TOKENS;
+}

package/dist/services/ide/ide-mcp-install-types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The REGISTRATION profile of one harness's MCP entry point (spec §8.3).
+ *
+ * WHY THIS IS NOT `IdeMcpProfile`. That profile (on `IdeAdapter.mcp`) answers
+ * "how does this harness SPELL a peaks tool name", which the pre-tool branch
+ * needs. This one answers "how does this harness register a server", which only
+ * the distribution path needs. One field would conflate two questions asked by
+ * two callers that never run together.
+ *
+ * WHY IT DECLARES ARGV AND NOT A COMMAND STRING. Registering is the HARNESS's
+ * own operation: `peaks mcp install` calls the harness's entry point rather than
+ * hand-editing the harness's config file, because that file is full of the
+ * user's state and hand-editing it is neither safe nor version-stable (§8.3).
+ * The entry is declared as an ARRAY with three placeholders, so the engine that
+ * consumes it substitutes values into an array and never builds a command line.
+ *
+ * WHY add AND remove ARE BOTH DECLARED. A harness's register verb is not
+ * idempotent — same name, same scope, and it fails, with no `--force` and no
+ * `update` — so the install is delete-then-add (§8.3). Both halves are therefore
+ * part of the contract, and `scopes` exists because the entry can already sit in
+ * more than one of them: the delete is a sweep, not a targeted call.
+ *
+ * WHAT IS DELIBERATELY ABSENT: any harness name, any platform name, and any
+ * branch on either. A vendor's own spellings belong in its adapter, which is the
+ * only module that fills this type in.
+ */
+/** Placeholder for the server key the harness files peaks under. */
+export declare const MCP_NAME_PLACEHOLDER = "<name>";
+/** Placeholder for one scope the entry can live in; substituted once per removal. */
+export declare const MCP_SCOPE_PLACEHOLDER = "<scope>";
+/** Placeholder for the launched server argv — the command and every token after it. */
+export declare const MCP_SERVER_ARGV_PLACEHOLDER = "<server-argv>";
+/** The placeholders an argv template may carry, and nothing else may look like one. */
+export declare const MCP_ARGV_PLACEHOLDERS: readonly ["<name>", "<scope>", "<server-argv>"];
+/**
+ * How one harness registers, and unregisters, a peaks MCP server.
+ *
+ * Optional on `IdeAdapter`, like `skillInstall?` / `standardsProfile?`: an
+ * adapter that omits it is declaring "this harness has no registration entry
+ * peaks may call", and every consumer reads that as "nothing to do" rather than
+ * as an error.
+ */
+export interface IdeMcpInstallProfile {
+    /** The server key this harness files peaks under. The install touches only this one. */
+    readonly serverName: string;
+    /**
+     * Every scope the entry can live in. The delete sweeps all of them, because a
+     * previous install may have written a different one and the harness's own
+     * removal fails on the scope that is empty.
+     */
+    readonly scopes: readonly string[];
+    /** The scope the entry is (re-)written to. Must be one of `scopes`. */
+    readonly targetScope: string;
+    /** argv template that registers the server. Carries `<name>` and `<server-argv>`. */
+    readonly addArgv: readonly string[];
+    /** argv template that unregisters it. Carries `<name>` and `<scope>`. */
+    readonly removeArgv: readonly string[];
+}
+/** The values an argv template is expanded with. */
+export interface McpArgvValues {
+    readonly serverName: string;
+    readonly scope: string;
+    readonly serverArgv: readonly string[];
+}
+/**
+ * A declaration that cannot drive an install is a defect in the adapter, and it
+ * is reported as one rather than silently producing an argv the harness will
+ * reject. That is the whole argument for throwing here: a profile missing its
+ * server-argv placeholder would install a registration that launches nothing,
+ * and nothing would say so.
+ */
+export declare function assertMcpInstallProfile(profile: IdeMcpInstallProfile): void;
+/**
+ * Expand one argv template. A placeholder that stands for SEVERAL tokens expands
+ * to all of them, which is why this returns an array and why the launched server
+ * argv is passed as one: the caller never joins and never splits.
+ */
+export declare function expandMcpArgv(argv: readonly string[], values: McpArgvValues): readonly string[];

package/dist/services/ide/ide-mcp-install-types.js

@@ -0,0 +1,104 @@
+/**
+ * The REGISTRATION profile of one harness's MCP entry point (spec §8.3).
+ *
+ * WHY THIS IS NOT `IdeMcpProfile`. That profile (on `IdeAdapter.mcp`) answers
+ * "how does this harness SPELL a peaks tool name", which the pre-tool branch
+ * needs. This one answers "how does this harness register a server", which only
+ * the distribution path needs. One field would conflate two questions asked by
+ * two callers that never run together.
+ *
+ * WHY IT DECLARES ARGV AND NOT A COMMAND STRING. Registering is the HARNESS's
+ * own operation: `peaks mcp install` calls the harness's entry point rather than
+ * hand-editing the harness's config file, because that file is full of the
+ * user's state and hand-editing it is neither safe nor version-stable (§8.3).
+ * The entry is declared as an ARRAY with three placeholders, so the engine that
+ * consumes it substitutes values into an array and never builds a command line.
+ *
+ * WHY add AND remove ARE BOTH DECLARED. A harness's register verb is not
+ * idempotent — same name, same scope, and it fails, with no `--force` and no
+ * `update` — so the install is delete-then-add (§8.3). Both halves are therefore
+ * part of the contract, and `scopes` exists because the entry can already sit in
+ * more than one of them: the delete is a sweep, not a targeted call.
+ *
+ * WHAT IS DELIBERATELY ABSENT: any harness name, any platform name, and any
+ * branch on either. A vendor's own spellings belong in its adapter, which is the
+ * only module that fills this type in.
+ */
+/** Placeholder for the server key the harness files peaks under. */
+export const MCP_NAME_PLACEHOLDER = '<name>';
+/** Placeholder for one scope the entry can live in; substituted once per removal. */
+export const MCP_SCOPE_PLACEHOLDER = '<scope>';
+/** Placeholder for the launched server argv — the command and every token after it. */
+export const MCP_SERVER_ARGV_PLACEHOLDER = '<server-argv>';
+/** The placeholders an argv template may carry, and nothing else may look like one. */
+export const MCP_ARGV_PLACEHOLDERS = [
+    MCP_NAME_PLACEHOLDER,
+    MCP_SCOPE_PLACEHOLDER,
+    MCP_SERVER_ARGV_PLACEHOLDER
+];
+/**
+ * One template's structural requirements: it must carry something, its
+ * bracket-shaped tokens must be ones the engine knows how to substitute, and the
+ * placeholders the caller needs in it must be there. An unknown placeholder is a
+ * refusal rather than a literal, because passing it through would hand the
+ * harness an argument that means nothing to it.
+ */
+function assertArgvTemplate(label, argv, required, refuse) {
+    if (argv.length === 0)
+        refuse(`${label} is empty`);
+    for (const token of argv) {
+        const bracketShaped = token.startsWith('<') && token.endsWith('>');
+        const known = MCP_ARGV_PLACEHOLDERS.includes(token);
+        if (bracketShaped && !known)
+            refuse(`${label} carries unknown placeholder '${token}'`);
+    }
+    for (const placeholder of required) {
+        if (!argv.includes(placeholder))
+            refuse(`${label} does not carry ${placeholder}`);
+    }
+}
+/**
+ * A declaration that cannot drive an install is a defect in the adapter, and it
+ * is reported as one rather than silently producing an argv the harness will
+ * reject. That is the whole argument for throwing here: a profile missing its
+ * server-argv placeholder would install a registration that launches nothing,
+ * and nothing would say so.
+ */
+export function assertMcpInstallProfile(profile) {
+    const refuse = (reason) => {
+        throw new Error(`IdeMcpInstallProfile is not installable: ${reason}`);
+    };
+    if (profile.serverName.length === 0)
+        refuse('serverName is empty');
+    if (profile.scopes.length === 0)
+        refuse('scopes is empty');
+    if (!profile.scopes.includes(profile.targetScope)) {
+        refuse(`targetScope '${profile.targetScope}' is not one of the declared scopes`);
+    }
+    assertArgvTemplate('addArgv', profile.addArgv, [MCP_NAME_PLACEHOLDER, MCP_SCOPE_PLACEHOLDER, MCP_SERVER_ARGV_PLACEHOLDER], refuse);
+    assertArgvTemplate('removeArgv', profile.removeArgv, [MCP_NAME_PLACEHOLDER, MCP_SCOPE_PLACEHOLDER], refuse);
+}
+/**
+ * Expand one argv template. A placeholder that stands for SEVERAL tokens expands
+ * to all of them, which is why this returns an array and why the launched server
+ * argv is passed as one: the caller never joins and never splits.
+ */
+export function expandMcpArgv(argv, values) {
+    const expanded = [];
+    for (const token of argv) {
+        if (token === MCP_NAME_PLACEHOLDER) {
+            expanded.push(values.serverName);
+            continue;
+        }
+        if (token === MCP_SCOPE_PLACEHOLDER) {
+            expanded.push(values.scope);
+            continue;
+        }
+        if (token === MCP_SERVER_ARGV_PLACEHOLDER) {
+            expanded.push(...values.serverArgv);
+            continue;
+        }
+        expanded.push(token);
+    }
+    return expanded;
+}

package/dist/services/ide/ide-types.d.ts

@@ -13,12 +13,13 @@
  */
 import type { SubAgentDispatcher } from '../dispatch/sub-agent-dispatcher.js';
 import type { ContextPercentFallbackInput, IdeCompactProfile } from './ide-compact-types.js';
+import type { IdeMcpInstallProfile } from './ide-mcp-install-types.js';
 /**
  * Re-exported so every importer of `./ide-types.js` keeps seeing the whole
  * adapter type surface from the original path (b1 file-size campaign: the two
  * declarations now live in `./ide-compact-types.js`).
  */
-export type { ContextPercentFallbackInput, IdeCompactProfile };
+export type { ContextPercentFallbackInput, IdeCompactProfile, IdeMcpInstallProfile };
 export type IdeId = 'claude-code' | 'trae' | 'codex' | 'cursor' | 'qoder' | 'tongyi-lingma' | 'hermes' | 'openclaw' | 'zcode';
 export interface IdeCapabilities {
     /** peaks gate enforce 是否适用该 IDE(必备) */
@@ -171,6 +172,49 @@ export interface IdeAdapter {
      * funnelling all vendor signal through this method.
      */
     readonly resolveCallerId: (env?: NodeJS.ProcessEnv) => string;
+    /**
+     * How this harness SPELLS the MCP tool names of a peaks server.
+     *
+     * Optional, like `skillInstall?` / `standardsProfile?` / `compact?`: an adapter
+     * that leaves it undefined declares "this harness has no MCP tool surface I can
+     * name", and every consumer treats that as "nothing to match" rather than as an
+     * error.
+     *
+     * It exists because one tool has SEVERAL spellings. A server registered
+     * directly and the same server arriving through a plugin produce different
+     * tool names, and an enforcement matcher written against one of them does not
+     * fire on the other — silently. Declaring them here is what lets the
+     * pre-tool branch and the installed hook entry agree on the full set.
+     *
+     * `resolveCallerId` above is the precedent for the placement rule: a vendor's
+     * naming convention is vendor signal, and vendor signal is funnelled through
+     * the adapter so no other module has to know it.
+     */
+    readonly mcp?: IdeMcpProfile;
+    /**
+     * How this harness REGISTERS an MCP server (spec §8.3), consumed by
+     * `peaks mcp install/uninstall`. Optional, like `mcp` above: leaving it
+     * undefined declares "no registration entry peaks may call", and the install
+     * reads that as "nothing to do". See `ide-mcp-install-types.ts`.
+     */
+    readonly mcpInstall?: IdeMcpInstallProfile;
+}
+/**
+ * The MCP naming profile of one harness.
+ *
+ * Deliberately ONE field. Templates both MATCH a concrete tool name and
+ * CONSTRUCT one, which is what lets a conformance test build a call for a
+ * channel it has never seen (spec §6.3) instead of restating the harness's
+ * naming in the test — a restatement that would go stale the moment a channel
+ * is added.
+ */
+export interface IdeMcpProfile {
+    /**
+     * Tool-name templates. `*` is replaced by the bare MCP tool id, so
+     * `mcp__peaks__*` describes every tool of a server registered under the name
+     * `peaks` on the direct channel.
+     */
+    readonly toolNameTemplates: readonly string[];
 }
 /**
  * Per-IDE standards-file location + format profile. Used by the

package/dist/services/ide/mcp-tool-matcher.d.ts

@@ -0,0 +1,34 @@
+import type { IdeAdapter, IdeMcpProfile } from './ide-types.js';
+/** The placeholder an adapter's tool-name template uses for the bare tool id. */
+export declare const TOOL_ID_PLACEHOLDER = "*";
+/** A concrete tool name matched back to the adapter template that produced it. */
+export interface McpToolMatch {
+    /** The bare tool id — the part the template's placeholder stood for. */
+    readonly toolId: string;
+    /** The template that matched, so a caller can report which channel fired. */
+    readonly template: string;
+}
+/** The declared profile, or an empty one for an adapter that opts out. */
+export declare function mcpProfileOf(adapter: IdeAdapter): IdeMcpProfile | undefined;
+/** Every tool-name template the adapter declares, in declaration order. */
+export declare function mcpToolNameTemplates(adapter: IdeAdapter): readonly string[];
+/** The concrete harness tool name for a tool id under one template. */
+export declare function mcpToolName(template: string, toolId: string): string;
+/**
+ * The tool id a concrete name carries under one template, or `undefined`. The
+ * template is anchored: an unanchored match would let a longer name smuggle the
+ * id (and would make `matchMcpToolName` order-dependent).
+ */
+export declare function mcpToolIdFrom(template: string, toolName: string): string | undefined;
+/**
+ * Match a concrete harness tool name against every template the adapter
+ * declares, in declaration order. This is the ONE entry point the enforcement
+ * branch uses, so "which channels are covered" is answered by the adapter alone.
+ */
+export declare function matchMcpToolName(adapter: IdeAdapter, toolName: string): McpToolMatch | undefined;
+/**
+ * The PreToolUse `matcher` source covering every declared channel, ready to be
+ * joined into a hook entry's matcher field. `*` becomes `.*` and everything else
+ * is escaped, so the source matches exactly the names the templates describe.
+ */
+export declare function mcpHookMatcher(adapter: IdeAdapter): string | undefined;

package/dist/services/ide/mcp-tool-matcher.js

@@ -0,0 +1,84 @@
+// src/services/ide/mcp-tool-matcher.ts
+//
+// The vendor-translation layer for MCP tool NAMES (spec §6.3, §13).
+//
+// An MCP tool's name is harness-specific AND channel-specific: the very same
+// `peaks_status` tool is spelled one way when the server is registered directly
+// and another way when it arrives through a plugin. A matcher hard-coded against
+// one spelling keeps working on the channel it was written for and SILENTLY
+// stops firing on the other — the failure mode is an enforcement layer that
+// reports nothing because it never ran. So the spellings are declared by the
+// adapter (`IdeAdapter.mcp`) and this module is the only place that turns a
+// declaration into (a) a match against a concrete tool name and (b) the
+// PreToolUse matcher written into the harness's settings.
+//
+// Vendor names do not belong here: every string below is either generic syntax
+// or comes from the adapter. The isolation zone lives in `adapters/`.
+/** The placeholder an adapter's tool-name template uses for the bare tool id. */
+export const TOOL_ID_PLACEHOLDER = '*';
+/** The declared profile, or an empty one for an adapter that opts out. */
+export function mcpProfileOf(adapter) {
+    return adapter.mcp;
+}
+/** Every tool-name template the adapter declares, in declaration order. */
+export function mcpToolNameTemplates(adapter) {
+    return adapter.mcp?.toolNameTemplates ?? [];
+}
+/** Escape a literal segment so it cannot act as a pattern metacharacter. */
+function escapeLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Split a template on its placeholder. A template must carry EXACTLY one
+ * placeholder: zero would make the tool id unaddressable, and two would make the
+ * captured id ambiguous. Both are adapter bugs, so they throw with the template
+ * in the message rather than degrading to a matcher that matches nothing.
+ */
+function splitTemplate(template) {
+    const parts = template.split(TOOL_ID_PLACEHOLDER);
+    if (parts.length !== 2 || parts[0] === undefined || parts[1] === undefined) {
+        throw new Error(`MCP tool-name template '${template}' must contain exactly one '${TOOL_ID_PLACEHOLDER}' placeholder.`);
+    }
+    return [parts[0], parts[1]];
+}
+/** The concrete harness tool name for a tool id under one template. */
+export function mcpToolName(template, toolId) {
+    const [prefix, suffix] = splitTemplate(template);
+    return `${prefix}${toolId}${suffix}`;
+}
+/**
+ * The tool id a concrete name carries under one template, or `undefined`. The
+ * template is anchored: an unanchored match would let a longer name smuggle the
+ * id (and would make `matchMcpToolName` order-dependent).
+ */
+export function mcpToolIdFrom(template, toolName) {
+    const [prefix, suffix] = splitTemplate(template);
+    const pattern = new RegExp(`^${escapeLiteral(prefix)}(.*)${escapeLiteral(suffix)}$`);
+    const matched = pattern.exec(toolName);
+    return matched?.[1];
+}
+/**
+ * Match a concrete harness tool name against every template the adapter
+ * declares, in declaration order. This is the ONE entry point the enforcement
+ * branch uses, so "which channels are covered" is answered by the adapter alone.
+ */
+export function matchMcpToolName(adapter, toolName) {
+    for (const template of mcpToolNameTemplates(adapter)) {
+        const toolId = mcpToolIdFrom(template, toolName);
+        if (toolId !== undefined)
+            return { toolId, template };
+    }
+    return undefined;
+}
+/**
+ * The PreToolUse `matcher` source covering every declared channel, ready to be
+ * joined into a hook entry's matcher field. `*` becomes `.*` and everything else
+ * is escaped, so the source matches exactly the names the templates describe.
+ */
+export function mcpHookMatcher(adapter) {
+    const sources = mcpToolNameTemplates(adapter).map((template) => {
+        const [prefix, suffix] = splitTemplate(template);
+        return `${escapeLiteral(prefix)}.*${escapeLiteral(suffix)}`;
+    });
+    return sources.length === 0 ? undefined : sources.join('|');
+}

package/dist/services/lint/npx-resolver.js

@@ -17,6 +17,13 @@ import process from 'node:process';
 function locateNpmCliScript(scriptFile) {
     const candidates = process.platform === 'win32'
         ? [
+            // Standard Windows layout — the installer, the zip, and
+            // nvm-for-windows all put `node_modules/npm` beside `node.exe`, so the
+            // install is ONE level up from `process.execPath`, not two. This is the
+            // `npm` belonging to the very `node` that will run the script, so it is
+            // tried first; the three entries after it are the backstop for an `npm`
+            // installed elsewhere.
+            join(process.execPath, '..', 'node_modules', 'npm', 'bin', scriptFile),
             join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', scriptFile),
             `C:/nvm4w/nodejs/node_modules/npm/bin/${scriptFile}`,
             `C:/Program Files/nodejs/node_modules/npm/bin/${scriptFile}`