@holmes-lab/holmes-kit 0.19.0 → 0.19.2

package/CHANGELOG.md

@@ -5,6 +5,86 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.19.2] - 2026-09-10
+
+Wiring diagnosis no longer depends on where you run it. No API change.
+
+### Fixed
+- **`doctor` gave opposite verdicts for the same wiring depending on the directory it was run
+  from** (REQ-581). A relative executable path in a wiring file is resolved by Node against
+  `process.cwd()`, and a relative path is the CONVENTION here — `.mcp.json` has always carried
+  `bin/holmes-mcp.js`. Measured: the same project under the same `--target` read
+  `PASS codex wiring` from the repository root and `FAIL — points at a missing file` from `/tmp`,
+  with the fix line telling the operator to re-init a wiring that was never wrong. All four
+  affected checks (`mcp wiring spawn`, `codex wiring`, and the `wiringHandshakeChecks` that cover
+  all three harnesses) now resolve against the TARGET project, and the handshake launches the
+  server FROM that project — the way a harness actually starts it. Absolute wirings (antigravity's)
+  are returned untouched, and a path that is genuinely missing still fails. The message keeps the
+  string exactly as written in the wiring file: what an operator must fix is that string, not our
+  arithmetic.
+- **The same wiring could read PASS from one check and FAIL from its sibling.** Measured on a
+  third-party tarball install: `claude wiring handshake` passed while `mcp wiring spawn` failed on
+  the identical `npx` command, because only one of the two spawn paths had been moved. Both now
+  launch from the target.
+
+### Verified on a third-party install (macOS, npm 11.17.0, Node 26.5.1)
+- Tarball installed into a clean project: `better-sqlite3` binding present, `:memory:` query ok.
+- With install scripts blocked (`--ignore-scripts`, the npm 12 condition): the CLI still starts,
+  `init` still wires, the MCP server still answers — and `doctor` names the cause and prints a
+  recovery command that works verbatim (`npm rebuild better-sqlite3 --foreground-scripts`).
+- Diagnosed from an unrelated working directory with the consumer's own CLI: claude / codex /
+  antigravity handshakes 3/3 PASS, `target wiring — 3 holmes hook(s) resolve to this install`.
+
+### Corrected from 0.19.1's notes
+- 0.19.1 recorded that `codexMcpBlock` "writes Windows backslash paths into `config.toml`
+  unescaped". Re-measured: it does not. `tomlStr` escapes `\` correctly and the write→read
+  round-trip returns `C:\Users\name\proj\bin\holmes-mcp.js` byte-identical (pure functions, so
+  the result is platform-independent). The `doctor-wiring-handshake` failure seen on a Windows
+  checkout is therefore unexplained by escaping — and is a candidate instance of the cwd defect
+  fixed above, which is a HYPOTHESIS for the next Windows run, not a conclusion.
+
+## [0.19.1] - 2026-09-10
+
+Windows install hardening, measured on Windows 11 / npm 12.0.1 / Node 24.19.0. No API change.
+
+### Fixed
+- **npm 12 skipped `better-sqlite3`'s install script and nothing said so** (REQ-579). npm ≥ 12
+  (and npm 11.19+) blocks dependency install scripts unless the root `package.json` approves
+  them; `npm ci` then succeeds with no `better_sqlite3.node`, and every SQLite-backed feature
+  fails on first use. `package.json` now declares `allowScripts: { "better-sqlite3@12.11.1": true }`
+  — the ONE dependency that needs its script, pinned to the lockfile version so a bump forces a
+  fresh review (a test goes red until the pin is updated). The 8 tree-sitter packages are
+  deliberately not approved: measured, they load from their shipped `prebuilds/` with the script
+  blocked. Older npm 11 ignores the field.
+- **doctor misdiagnosed every missing SQLite binary as an ABI mismatch** (REQ-580). The
+  `better-sqlite3` check now judges from evidence — binary present or not, the load error's
+  wording, the npm major, the governing `allowScripts`, the install layout (repository / project
+  dependency / global / npx), and on Windows the toolchain and a spaced path — and names the
+  cause: `scripts-blocked`, `abi-mismatch`, `build-failed`, or `unknown` with the raw error. A
+  prebuilt-download failure is stated as unobservable, never asserted. The fix line is the exact
+  command for that layout; for a global install it targets the dependency
+  (`npm rebuild -g better-sqlite3 --foreground-scripts --allow-scripts=better-sqlite3`), because
+  `rebuild -g @holmes-lab/holmes-kit` dies `EEXIST` re-linking the bin under npm 12 (measured).
+- **doctor's grammar check only resolved packages.** It now parses a source with all 8 grammars
+  (typescript, tsx, python, c-sharp, java, go, rust, cpp) in a fresh child process — in-process
+  parsing is unreliable after another module registry has loaded tree-sitter's native addon.
+- **Windows recovery commands are runnable.** npm commands are emitted as `npm.cmd` on win32
+  (`npmBin`, the twin of `npxBin`), and when a `Restricted`/`AllSigned` PowerShell execution policy
+  is observed the verdict says the `.ps1` shims are blocked and the `.cmd` ones are not.
+
+### Docs
+- `docs/install-guide.md`: npm 12 section, per-layout recovery table, PowerShell policy note,
+  build-failed evidence. `docs/windows-test-plan-2026-09.md`: items E/F/G updated with the
+  2026-09-09/10 measurements and the known Windows-only baseline failures.
+
+### Known, not fixed (recorded honestly)
+- macOS/Linux were not exercised on hardware in this release; their behaviour is covered by
+  platform-injected unit tests and the three-harness parity suite only.
+- `codexMcpBlock` writes Windows backslash paths into `config.toml` unescaped
+  (`doctor-wiring-handshake` fails on a Windows checkout); doctor's `global prefix` check reports a
+  protected `C:\Program Files\nodejs` as writable. Both are pre-existing and tracked as follow-ups.
+  **(The escaping half of this was re-measured in 0.19.2 and does not reproduce — see that entry.)**
+
 ## [0.19.0] - 2026-09-08
 
 ### Added

package/dist/.build-id

@@ -1 +1 @@
-0043954-mtspy09e
+e63e589-mtuemhhb

package/dist/holmes/cli/agents.d.ts

@@ -62,6 +62,28 @@ export declare function antigravityHookCommand(scriptPath: string): string;
 /** win32-only, best-effort: a spaced path becomes its 8.3 short name (no spaces); anything else — or
  *  any lookup failure — returns the input unchanged. */
 export declare function shortPathIfSpaced(p: string): string;
+export declare const MANAGED_BEGIN = "<!-- holmes-kit:managed:begin -->";
+export declare const MANAGED_END = "<!-- holmes-kit:managed:end -->";
+/**
+ * @implements A-SPEC-576.2
+ * The regeneration that keeps what it did not write.
+ *
+ * Measured cause: `init` rewrote AGENTS.md from the template, deleting the ADR-018 parity rule a
+ * commit had added the day before — and said nothing, so the loss was found weeks later by grep.
+ * Generated text now lives inside a MANAGED BLOCK; everything outside it belongs to the person
+ * whose repository this is.
+ *
+ * PURE, and it takes the whole file rather than a path: the caller reads `before` during init's
+ * COMPUTE phase, so a dry-run predicts the same bytes the real run writes (A-SPEC-190 §9).
+ *
+ * `preserved` is the report, not a courtesy. A run that moved something and returned an empty list
+ * would be the same silent loss in a new costume.
+ */
+export declare function mergeAgentsMd(existing: string | null, generated: string): {
+    content: string;
+    preserved: string[];
+    note: string | null;
+};
 /**
  * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
  *

package/dist/holmes/cli/agents.js

@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
+exports.MANAGED_END = exports.MANAGED_BEGIN = exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
 exports.antigravityHookCommand = antigravityHookCommand;
 exports.shortPathIfSpaced = shortPathIfSpaced;
+exports.mergeAgentsMd = mergeAgentsMd;
 exports.agentFiles = agentFiles;
 exports.agentLinks = agentLinks;
 // @implements A-SPEC-442
@@ -197,6 +198,80 @@ ${enforced
     ? `Gates are **enforced**. Tool calls that write un-anchored code or target unapproved specifications will be denied. Unresolved critical findings block completion.`
     : `This harness does not have measured **hook enforcement points**. Holmes-Kit provides tools and guidance here without active gate blocking.`}
 `;
+exports.MANAGED_BEGIN = '<!-- holmes-kit:managed:begin -->';
+exports.MANAGED_END = '<!-- holmes-kit:managed:end -->';
+const PRESERVED_NOTE = '<!-- kept from this file by holmes-kit init — holmes-kit does not write below this line -->';
+/**
+ * @implements A-SPEC-576.2
+ * The regeneration that keeps what it did not write.
+ *
+ * Measured cause: `init` rewrote AGENTS.md from the template, deleting the ADR-018 parity rule a
+ * commit had added the day before — and said nothing, so the loss was found weeks later by grep.
+ * Generated text now lives inside a MANAGED BLOCK; everything outside it belongs to the person
+ * whose repository this is.
+ *
+ * PURE, and it takes the whole file rather than a path: the caller reads `before` during init's
+ * COMPUTE phase, so a dry-run predicts the same bytes the real run writes (A-SPEC-190 §9).
+ *
+ * `preserved` is the report, not a courtesy. A run that moved something and returned an empty list
+ * would be the same silent loss in a new costume.
+ */
+function mergeAgentsMd(existing, generated) {
+    const block = exports.MANAGED_BEGIN + '\n' + (generated.endsWith('\n') ? generated : generated + '\n') + exports.MANAGED_END + '\n';
+    if (existing === null || existing === '')
+        return { content: block, preserved: [], note: null };
+    const b = existing.indexOf(exports.MANAGED_BEGIN);
+    const e = existing.indexOf(exports.MANAGED_END);
+    if (b !== -1 && e > b) {
+        // The ordinary case once a file has been through here: swap the block, and do not touch a
+        // single byte on either side of it.
+        const body = generated.endsWith('\n') ? generated : generated + '\n';
+        return {
+            content: existing.slice(0, b) + exports.MANAGED_BEGIN + '\n' + body + exports.MANAGED_END + existing.slice(e + exports.MANAGED_END.length),
+            preserved: [],
+            note: null,
+        };
+    }
+    // LEGACY: a file written before the markers existed — every AGENTS.md in the field today. Its
+    // lines are compared to the generated ones, and whatever the generator never wrote is carried
+    // below the block. Line terminators are kept as read, so a CRLF checkout stays CRLF.
+    const known = new Set(generated.split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== ''));
+    const lines = existing.split(/(?<=\n)/);
+    const runs = [];
+    let run = [];
+    let pendingBlanks = [];
+    for (const line of lines) {
+        const t = line.trim();
+        if (t === '') {
+            if (run.length > 0)
+                pendingBlanks.push(line);
+            continue;
+        }
+        if (known.has(t)) {
+            run = closeRun(runs, run);
+            pendingBlanks = [];
+            continue;
+        }
+        // A blank line INSIDE a run is part of it; blanks trailing a run are not.
+        run.push(...pendingBlanks, line);
+        pendingBlanks = [];
+    }
+    closeRun(runs, run);
+    if (runs.length === 0)
+        return { content: block, preserved: [], note: null };
+    const preserved = runs.map((r) => (r.find((l) => l.trim() !== '') ?? '').trim());
+    return {
+        content: block + '\n' + PRESERVED_NOTE + '\n\n' + runs.map((r) => r.join('')).join('\n'),
+        preserved,
+        note: `kept ${runs.length} section(s) this generator did not write`,
+    };
+}
+/** Close the current run into `runs` (dropping an empty one) and hand back a fresh one. */
+function closeRun(runs, run) {
+    if (run.length > 0)
+        runs.push(run);
+    return [];
+}
 /**
  * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
  *

package/dist/holmes/cli/approve.js

@@ -78,7 +78,12 @@ const DEFAULT_TTL_MINUTES = 30;
 const MAX_TTL_MINUTES = 7 * 24 * 60;
 const DEFAULT_RATIONALE = 'approved via holmes-kit approve';
 const findPending = (root, id) => {
-    const state = (0, approval_queue_1.readQueue)(root);
+    // @implements A-SPEC-576.1 — RESOLUTION reads everything; the human's LIST reads decisions only.
+    // The inbox filter hides gate refusals from the screen, but `approve <id>` must still find one:
+    // the fallback below only holds entries written after the REQ-563 split, so anything refused
+    // before it lives in the queue alone. Filtering here would cut the out-of-band approval path the
+    // deny message itself promises.
+    const state = (0, approval_queue_1.readQueue)(root, { includeAllKinds: true });
     const pending = state.pending.find((p) => p.id === id);
     if (pending)
         return { entry: pending, state };

package/dist/holmes/cli/doctor.d.ts

@@ -1,3 +1,4 @@
+import { NativeEvidence } from './native-deps';
 import { type SemanticTier } from '../semantic/tier';
 /**
  * `holmes-kit doctor` — install diagnostics.
@@ -82,6 +83,28 @@ export declare function prefixVerdict(input: PrefixProbe): {
     detail: string;
     fix?: string;
 };
+/**
+ * @implements A-SPEC-580
+ * Parse a trivial source with every grammar, in a child node whose module resolution starts at
+ * `packageRoot`. `parsed` counts typescript and tsx separately (8 for the 7 grammar packages).
+ */
+export declare function grammarProbe(packageRoot: string): {
+    parsed: number;
+    failed: string[];
+    error?: string;
+};
+/**
+ * @implements A-SPEC-580
+ * Everything observable about the better-sqlite3 install, gathered for `nativeVerdict`. Each probe
+ * is independent and optional: a spawn that fails leaves its field `undefined` (not observed), and
+ * the verdict says so rather than treating silence as evidence.
+ *
+ * Which package.json holds the approval policy depends on the layout: this checkout's own for a
+ * repository run, the PROJECT's (three levels up from node_modules/@holmes-lab/holmes-kit) for a
+ * local dependency. A global or npx install has no project package.json that npm consults, so its
+ * coverage is `uncovered` by construction and the remedy is the per-command `--allow-scripts`.
+ */
+export declare function gatherNativeEvidence(packageRoot: string): NativeEvidence;
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */
@@ -94,6 +117,18 @@ export interface ProbeRunner {
         stderr?: string;
     };
 }
+/**
+ * Where a wiring's executable actually is, judged from the PROJECT rather than from the caller.
+ *
+ * Measured 2026-09-10: the same `.codex/config.toml` under the same `--target` read PASS from the
+ * repository root and FAIL from `/tmp`, because a relative arg is resolved by Node against
+ * `process.cwd()`. A relative arg is the CONVENTION here — `.mcp.json` has always carried
+ * `bin/holmes-mcp.js` — so the verdict was decided by where the person diagnosing stood.
+ *
+ * An absolute arg is returned untouched: agy's wiring is absolute and must not move. An empty arg
+ * stays empty — resolving it would conjure the target directory itself into a "file that exists".
+ */
+export declare function resolveWiringPath(target: string, arg: string): string;
 export declare function runDoctor(packageRoot: string, target?: string, opts?: DoctorOptions, extraChecks?: Check[]): Promise<Check[]>;
 /**
  * Drive a real MCP stdio handshake: initialize -> initialized -> tools/list, with a timeout.
@@ -101,7 +136,7 @@ export declare function runDoctor(packageRoot: string, target?: string, opts?: D
  * and closes stdin makes the server exit before answering (a false FAIL this check produced on its
  * very first run against a healthy server).
  */
-export declare function wiringSpawnCheck(command: string, args: string[], timeoutMs?: number, platform?: NodeJS.Platform): Promise<Check>;
+export declare function wiringSpawnCheck(command: string, args: string[], timeoutMs?: number, platform?: NodeJS.Platform, cwd?: string): Promise<Check>;
 /**
  * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
  * AND has git. Absence or a hook without our signature is a WARN carrying the install command —

package/dist/holmes/cli/doctor.js

@@ -37,7 +37,10 @@ exports.STRIPPED_FOR_PROBE = void 0;
 exports.globalInstallDir = globalInstallDir;
 exports.npmCliEntry = npmCliEntry;
 exports.prefixVerdict = prefixVerdict;
+exports.grammarProbe = grammarProbe;
+exports.gatherNativeEvidence = gatherNativeEvidence;
 exports.probeEnv = probeEnv;
+exports.resolveWiringPath = resolveWiringPath;
 exports.runDoctor = runDoctor;
 exports.wiringSpawnCheck = wiringSpawnCheck;
 exports.pushGateCheck = pushGateCheck;
@@ -48,8 +51,11 @@ exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
 // @implements A-SPEC-442
 // @implements A-SPEC-207
 // @implements A-SPEC-100.2
+// @implements A-SPEC-580
 const fs = __importStar(require("node:fs"));
 const npx_bin_1 = require("../project/npx-bin");
+const install_scripts_policy_1 = require("../project/install-scripts-policy");
+const native_deps_1 = require("./native-deps");
 const tier_1 = require("../semantic/tier");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
@@ -175,6 +181,114 @@ function prefixVerdict(input) {
         fix,
     };
 }
+/**
+ * @implements A-SPEC-580
+ * Parse a trivial source with every grammar, in a child node whose module resolution starts at
+ * `packageRoot`. `parsed` counts typescript and tsx separately (8 for the 7 grammar packages).
+ */
+function grammarProbe(packageRoot) {
+    const script = `
+    const out = { parsed: 0, failed: [] };
+    let Parser;
+    try { Parser = require('tree-sitter'); }
+    catch (e) { process.stdout.write(JSON.stringify({ ...out, error: String(e && e.message || e).split('\\n')[0] })); process.exit(0); }
+    const loaders = [
+      ['typescript', () => require('tree-sitter-typescript').typescript],
+      ['tsx', () => require('tree-sitter-typescript').tsx],
+    ];
+    for (const g of ${JSON.stringify(GRAMMARS.filter((g) => g !== 'tree-sitter-typescript'))}) {
+      loaders.push([g.replace('tree-sitter-', ''), () => require(g)]);
+    }
+    for (const [name, load] of loaders) {
+      try {
+        const p = new Parser();
+        p.setLanguage(load());
+        const node = p.parse('x').rootNode;
+        const root = node && node.type;
+        if (!root) throw new Error('parse produced no root node');
+        out.parsed++;
+      } catch (e) { out.failed.push(name + ': ' + String(e && e.message || e).split('\\n')[0]); }
+    }
+    process.stdout.write(JSON.stringify(out));
+  `;
+    try {
+        const r = (0, node_child_process_1.spawnSync)(process.execPath, ['-e', script], { cwd: packageRoot, encoding: 'utf8', timeout: 30000, env: { ...process.env, NODE_PATH: path.join(packageRoot, 'node_modules') } });
+        if (r.status !== 0 || !r.stdout)
+            return { parsed: 0, failed: [], error: (r.stderr || `exit ${r.status}`).split('\n')[0] };
+        return JSON.parse(r.stdout);
+    }
+    catch (e) {
+        return { parsed: 0, failed: [], error: e.message.split('\n')[0] };
+    }
+}
+/** A short spawn whose failure means "not observed" — never a verdict. */
+function observe(file, args) {
+    try {
+        return (0, node_child_process_1.execFileSync)(file, args, { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * @implements A-SPEC-580
+ * Everything observable about the better-sqlite3 install, gathered for `nativeVerdict`. Each probe
+ * is independent and optional: a spawn that fails leaves its field `undefined` (not observed), and
+ * the verdict says so rather than treating silence as evidence.
+ *
+ * Which package.json holds the approval policy depends on the layout: this checkout's own for a
+ * repository run, the PROJECT's (three levels up from node_modules/@holmes-lab/holmes-kit) for a
+ * local dependency. A global or npx install has no project package.json that npm consults, so its
+ * coverage is `uncovered` by construction and the remedy is the per-command `--allow-scripts`.
+ */
+function gatherNativeEvidence(packageRoot) {
+    const name = 'better-sqlite3';
+    const pkgDir = path.join(packageRoot, 'node_modules', name);
+    const bindingPresent = fs.existsSync(path.join(pkgDir, 'build', 'Release', 'better_sqlite3.node'));
+    let packageVersion = '(unknown)';
+    try {
+        packageVersion = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')).version ?? packageVersion;
+    }
+    catch { /* not installed */ }
+    let loadError;
+    try {
+        const Database = require(name);
+        const db = new Database(':memory:');
+        db.prepare('SELECT 1 AS ok').get();
+        db.close();
+    }
+    catch (e) {
+        loadError = e.message.split('\n')[0];
+    }
+    const npmCli = npmCliEntry();
+    const npmVersion = npmCli !== null ? observe(process.execPath, [npmCli, '--version']) : observe('npm', ['--version']);
+    const npmMajor = npmVersion !== undefined && /^\d+/.test(npmVersion) ? Number(npmVersion.match(/^\d+/)[0]) : undefined;
+    const prefix = npmCli !== null ? observe(process.execPath, [npmCli, 'config', 'get', 'prefix']) : observe('npm', ['config', 'get', 'prefix']);
+    const kind = (0, native_deps_1.installKind)(packageRoot, prefix ? globalInstallDir(prefix, process.platform) : undefined);
+    let coverage = 'uncovered';
+    const policyJson = kind === 'repo' ? path.join(packageRoot, 'package.json')
+        : kind === 'local' ? path.join(packageRoot, '..', '..', '..', 'package.json')
+            : undefined;
+    if (policyJson !== undefined) {
+        try {
+            const allow = JSON.parse(fs.readFileSync(policyJson, 'utf8')).allowScripts;
+            coverage = (0, install_scripts_policy_1.allowScriptsCoverage)(allow, name, packageVersion);
+        }
+        catch { /* unreadable → uncovered, which is what npm would see too */ }
+    }
+    const ev = {
+        platform: process.platform, packageName: name, packageVersion, bindingPresent, loadError, npmMajor,
+        coverage, installKind: kind, pathHasSpace: packageRoot.includes(' '),
+    };
+    if (process.platform === 'win32') {
+        const python = observe('where.exe', ['python']) !== undefined || observe('where.exe', ['py']) !== undefined;
+        const vswhere = path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Microsoft Visual Studio', 'Installer', 'vswhere.exe');
+        const msvc = fs.existsSync(vswhere) || observe('where.exe', ['cl']) !== undefined || process.env.VCINSTALLDIR !== undefined;
+        ev.toolchain = { python, msvc };
+        ev.psPolicy = observe('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', 'Get-ExecutionPolicy']);
+    }
+    return ev;
+}
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 function probeEnv(parent) {
     const out = { ...parent };
@@ -208,6 +322,23 @@ function wiredSettingsPath(target) {
         return (0, init_1.settingsPathOf)(target, 'project');
     return (0, init_1.settingsPathOf)(target, fs.existsSync((0, init_1.settingsPathOf)(target, 'local')) ? 'local' : 'project');
 }
+// @implements A-SPEC-581.1
+/**
+ * Where a wiring's executable actually is, judged from the PROJECT rather than from the caller.
+ *
+ * Measured 2026-09-10: the same `.codex/config.toml` under the same `--target` read PASS from the
+ * repository root and FAIL from `/tmp`, because a relative arg is resolved by Node against
+ * `process.cwd()`. A relative arg is the CONVENTION here — `.mcp.json` has always carried
+ * `bin/holmes-mcp.js` — so the verdict was decided by where the person diagnosing stood.
+ *
+ * An absolute arg is returned untouched: agy's wiring is absolute and must not move. An empty arg
+ * stays empty — resolving it would conjure the target directory itself into a "file that exists".
+ */
+function resolveWiringPath(target, arg) {
+    if (arg === '')
+        return '';
+    return path.isAbsolute(arg) ? arg : path.resolve(target, arg);
+}
 async function runDoctor(packageRoot, target, opts, extraChecks) {
     const checks = [];
     const add = (name, level, detail, fix) => checks.push({ name, level, detail, fix });
@@ -227,35 +358,34 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     }
     catch { /* not resolvable from here */ }
     add('node version', 'PASS', `node ${process.version}; better-sqlite3 declares engines.node=${sqliteRange}`, 'If a native module fails to load after a Node major upgrade, reinstall holmes-kit.');
-    // 3. tree-sitter + EACH grammar. language-parser.ts require.resolve's all of them at module scope,
-    //    so ONE missing grammar kills MCP server startup entirely — report them individually.
-    try {
-        require('tree-sitter');
-        const missing = GRAMMARS.filter((g) => { try {
-            require.resolve(g);
-            return false;
+    // 3. tree-sitter + EACH grammar — PARSED, not merely resolved. `require.resolve` only proves the
+    //    package directory exists; a grammar whose prebuilt binding is missing for this platform
+    //    resolves fine and dies at `setLanguage`. language-parser.ts loads them at module scope, so
+    //    ONE dead grammar kills MCP server startup — name the dead ones individually.
+    // @implements A-SPEC-580
+    //    Measured in a FRESH process: tree-sitter's native addon binds to the first module registry
+    //    that loads it, so a second `require` inside the same process (jest workers; any host that
+    //    already loaded it) hands back a Parser whose `parse()` yields no rootNode — a false FAIL that
+    //    says nothing about the install. The probe therefore runs in a child node, which is also
+    //    exactly what the MCP server does at startup.
+    {
+        const g = grammarProbe(packageRoot);
+        if (g.error !== undefined) {
+            add('tree-sitter grammars', 'FAIL', `tree-sitter failed to load: ${g.error}`, 'The tree-sitter runtime binding for this platform is missing from its prebuilds. Reinstall; a source build needs Python and a C++ toolchain.');
+        }
+        else if (g.failed.length === 0) {
+            add('tree-sitter grammars', 'PASS', `tree-sitter + ${g.parsed} grammars parse`);
+        }
+        else {
+            add('tree-sitter grammars', 'FAIL', `failed to parse with: ${g.failed.join('; ')}`, 'Grammars load from shipped prebuilds (no install script needed) — reinstall the package. A single dead grammar prevents the MCP server from starting.');
         }
-        catch {
-            return true;
-        } });
-        if (missing.length === 0)
-            add('tree-sitter grammars', 'PASS', `tree-sitter + ${GRAMMARS.length} grammars resolve`);
-        else
-            add('tree-sitter grammars', 'FAIL', `missing: ${missing.join(', ')}`, 'A single missing grammar prevents the MCP server from starting. Reinstall; if a native build failed, ensure a C++ toolchain is available.');
-    }
-    catch (e) {
-        add('tree-sitter grammars', 'FAIL', `tree-sitter failed to load: ${e.message}`, 'Native module build failed. Install Xcode Command Line Tools (macOS) or build-essential, then reinstall.');
-    }
-    // 4. better-sqlite3 — ABI-locked (not N-API), the most fragile dependency.
-    try {
-        const Database = require('better-sqlite3');
-        const db = new Database(':memory:');
-        db.prepare('SELECT 1 AS ok').get();
-        db.close();
-        add('better-sqlite3', 'PASS', 'loads and executes against :memory:');
     }
-    catch (e) {
-        add('better-sqlite3', 'FAIL', e.message, 'better-sqlite3 is ABI-locked to the Node version. Reinstall holmes-kit after any Node major change; a source build needs a C++ toolchain.');
+    // 4. better-sqlite3 — the one dependency whose install script must RUN (prebuild-install ||
+    //    node-gyp rebuild). Its failure has at least five causes with five different remedies, so the
+    //    verdict is computed from evidence (A-SPEC-580), never from the load error's wording alone.
+    {
+        const v = (0, native_deps_1.nativeVerdict)(gatherNativeEvidence(packageRoot));
+        add('better-sqlite3', v.level, v.detail, v.fix);
     }
     // 5. Hooks actually gate — prove it with a live allow AND a live deny (exit 2).
     if (built) {
@@ -809,11 +939,18 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                         // the whole check for the common wiring, so "the file is there" was reported as if the
                         // server had been proven to start. `wiringHandshakeChecks` below now proves that, for
                         // every wired harness; this stays as the cheap, fast FAIL for a path that is simply gone.
+                        // @implements A-SPEC-581.1 — resolved against the TARGET; the message keeps the string
+                        // as written, because what the operator must fix is the wiring file, not our arithmetic.
                         const bin = server.args[0] ?? '';
-                        add('mcp wiring spawn', fs.existsSync(bin) ? 'PASS' : 'FAIL', fs.existsSync(bin) ? `node wiring resolves: ${bin} (handshake proven separately)` : `node wiring points at a missing file: ${bin}`, fs.existsSync(bin) ? undefined : 'Run `holmes-kit init` in the target to rewire the absolute path.');
+                        const binAt = resolveWiringPath(target, bin);
+                        add('mcp wiring spawn', fs.existsSync(binAt) ? 'PASS' : 'FAIL', fs.existsSync(binAt) ? `node wiring resolves: ${bin} (handshake proven separately)` : `node wiring points at a missing file: ${bin}`, fs.existsSync(binAt) ? undefined : 'Run `holmes-kit init` in the target to rewire the absolute path.');
                     }
                     else {
-                        checks.push(await wiringSpawnCheck(server.command, server.args));
+                        // @implements A-SPEC-581.1 — the SIBLING of the handshake spawn, and it must move with
+                        // it. Measured on a consumer install: the same npx wiring read PASS from the handshake
+                        // (launched in the target) and FAIL here (launched in doctor's cwd) — two checks, one
+                        // wiring, opposite verdicts.
+                        checks.push(await wiringSpawnCheck(server.command, server.args, undefined, undefined, target));
                     }
                 }
                 catch {
@@ -883,17 +1020,19 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                     // the "resolves" claim stronger than the check (adversarial round, Finding 2). Verify the
                     // basename too, to close that gap.
                     const bin = entry.args[0] ?? '';
+                    // @implements A-SPEC-581.1 — against the TARGET, not the cwd.
+                    const binAt = resolveWiringPath(target, bin);
                     // Resolve the link before judging the name (round-2 F4): a symlink literally named
                     // `holmes-mcp.js` pointing at /etc/hosts must not read as "resolves to this install".
                     const realBin = (() => { try {
-                        return fs.realpathSync(bin);
+                        return fs.realpathSync(binAt);
                     }
                     catch {
                         return '';
                     } })();
                     const resolvesHere = realBin !== '' && path.basename(realBin) === 'holmes-mcp.js';
                     add('codex wiring', resolvesHere ? 'PASS' : 'FAIL', resolvesHere ? `MCP wiring resolves to this install: ${bin}`
-                        : (fs.existsSync(bin) ? `MCP wiring points at a file that is not holmes-mcp.js: ${bin}` : `MCP wiring points at a missing file: ${bin}`), resolvesHere ? undefined : 'Run holmes-kit init --target <dir> --agent codex --force to refresh the absolute path.');
+                        : (fs.existsSync(binAt) ? `MCP wiring points at a file that is not holmes-mcp.js: ${bin}` : `MCP wiring points at a missing file: ${bin}`), resolvesHere ? undefined : 'Run holmes-kit init --target <dir> --agent codex --force to refresh the absolute path.');
                 }
                 else {
                     const pin = (0, mcp_version_1.mcpLaunchVersion)({ command: entry.command, args: entry.args });
@@ -1095,7 +1234,12 @@ function cleanupOnSignal(dir) {
 // harness will actually run reaches a server — the gap the dead npx form lived in.
 // @implements A-SPEC-499.1 — exported for the prescription tests; `platform` is injectable so the
 // win32 branch is testable off-Windows.
-function wiringSpawnCheck(command, args, timeoutMs = 30000, platform = process.platform) {
+function wiringSpawnCheck(command, args, timeoutMs = 30000, platform = process.platform, 
+// @implements A-SPEC-581.1 — the directory the wiring is launched FROM. A harness starts the
+// server in the project, so a relative arg (`bin/holmes-mcp.js`, the .mcp.json convention)
+// resolves there. Left undefined the child inherits doctor's cwd, which made the handshake
+// verdict depend on where doctor ran — measured 2026-09-10.
+cwd) {
     // The DISPLAYED command stays the original wiring string even when the win32 adapter rewraps the
     // execution — the user compares this against their wiring file, not against cmd.exe plumbing.
     const quoted = `${command} ${args.join(' ')}`;
@@ -1124,7 +1268,7 @@ function wiringSpawnCheck(command, args, timeoutMs = 30000, platform = process.p
         };
         const timer = setTimeout(() => finish('FAIL', `wiring did not answer initialize within ${timeoutMs / 1000}s: \`${quoted}\``, 'Re-run `holmes-kit init` in the target to rewrite the wiring, then re-run doctor.'), timeoutMs);
         try {
-            child = (0, node_child_process_1.spawn)(spec.command, spec.args, { stdio: ['pipe', 'pipe', 'pipe'] });
+            child = (0, node_child_process_1.spawn)(spec.command, spec.args, { stdio: ['pipe', 'pipe', 'pipe'], ...(cwd === undefined ? {} : { cwd }) });
         }
         catch (e) {
             finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, spawnFailFix(e));
@@ -1385,13 +1529,16 @@ async function wiringHandshakeChecks(target) {
         }
         if (entry.command === 'node') {
             const bin = entry.args[0] ?? '';
-            if (!fs.existsSync(bin)) {
+            // @implements A-SPEC-581.1 — the handshake covers ALL THREE harnesses, so the cwd-dependent
+            // read here was the widest instance of the same defect.
+            if (!fs.existsSync(resolveWiringPath(target, bin))) {
                 out.push({ name, level: 'FAIL', detail: `The wiring points at a missing file: ${bin}`,
                     fix: `Run holmes-kit init --target <dir> --agent ${wiring.label} --force to refresh the path.` });
                 continue;
             }
         }
-        const check = await wiringSpawnCheck(entry.command, entry.args);
+        // @implements A-SPEC-581.1 — launched FROM the target, exactly as the harness would.
+        const check = await wiringSpawnCheck(entry.command, entry.args, undefined, undefined, target);
         out.push({ ...check, name });
     }
     return out;

package/dist/holmes/cli/index.js

@@ -770,7 +770,13 @@ async function main(argv) {
         // The detail row travels with it: round-5 measured the one-line form at 81 columns, so the flag
         // path prints the same two rows the screen does — subject read, id acted on.
         const resolveRef = (ref) => {
-            const r = resolveRequestRef(readQueue(root).pending, ref);
+            // @implements A-SPEC-576.1 — the grammar decides which queue the reference is resolved against.
+            // A NUMBER is an index into the list the operator was just shown, so it must resolve against
+            // the same filtered list or `--grant 3` would act on a row nobody saw. An ID or prefix is the
+            // operator naming a specific request — including a `shell` refusal they approved out of band
+            // (A-SPEC-563.2), which the inbox filter hides from the list but must never make ungrantable.
+            const byIndex = /^\d+$/.test(ref.trim());
+            const r = resolveRequestRef(readQueue(root, byIndex ? undefined : { includeAllKinds: true }).pending, ref);
             return r.ok ? { id: r.entry.id, subject: (prefix) => decisionSubject(r.entry, prefix), detail: (tail) => decisionDetail(r.entry, tail) } : { refusal: r.reason };
         };
         const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();

package/dist/holmes/cli/init.js

@@ -458,6 +458,18 @@ function runInit(opts) {
         for (const agent of opts.agents ?? []) {
             for (const f of (0, agents_1.agentFiles)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir, launcher: opts.mcpLauncher })) {
                 const before = fs.existsSync(f.path) ? fs.readFileSync(f.path, 'utf8') : null;
+                // @implements A-SPEC-576.2 — AGENTS.md is the one file here a PERSON edits. Regeneration
+                // used to overwrite it whole: it deleted the ADR-018 parity rule a commit had just added,
+                // and said nothing. The merge runs in the COMPUTE phase so `--dry-run` predicts the same
+                // bytes the write produces (A-SPEC-190 §9), and whatever it moves, it names.
+                if (path.basename(f.path) === 'AGENTS.md') {
+                    const merged = (0, agents_1.mergeAgentsMd)(before, f.content);
+                    changes.push({ path: f.path, before, after: merged.content });
+                    if (merged.preserved.length > 0) {
+                        messages.push(`${f.path}: ${merged.note} — ${merged.preserved.join(' | ')}`);
+                    }
+                    continue;
+                }
                 changes.push({ path: f.path, before, after: f.content });
             }
             messages.push(agents_1.HARNESS_ENFORCES[agent]