@holmes-lab/holmes-kit 0.19.0 → 0.19.3

package/dist/holmes/cli/doctor.js

@@ -37,7 +37,11 @@ exports.STRIPPED_FOR_PROBE = void 0;
 exports.globalInstallDir = globalInstallDir;
 exports.npmCliEntry = npmCliEntry;
 exports.prefixVerdict = prefixVerdict;
+exports.grammarProbe = grammarProbe;
+exports.resolveDepDir = resolveDepDir;
+exports.gatherNativeEvidence = gatherNativeEvidence;
 exports.probeEnv = probeEnv;
+exports.resolveWiringPath = resolveWiringPath;
 exports.runDoctor = runDoctor;
 exports.wiringSpawnCheck = wiringSpawnCheck;
 exports.pushGateCheck = pushGateCheck;
@@ -48,8 +52,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 +182,140 @@ 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`.
+ */
+// @implements A-SPEC-583.1
+/**
+ * Where an installed dependency actually lives, asked of NODE rather than guessed from a path.
+ *
+ * 0.19.2 shipped a false FAIL to every third-party consumer: it built the directory by joining
+ * `packageRoot/node_modules/<name>`, and npm HOISTS dependencies to the project root, so for an
+ * install at `<proj>/node_modules/@holmes-lab/holmes-kit` the joined path never existed — while the
+ * binding sat at `<proj>/node_modules/better-sqlite3` and loaded fine. Hoisting is npm's default,
+ * which made the false verdict the default path of a normal install.
+ *
+ * `package.json` is the resolution target because we want the DIRECTORY, not the entry point: a
+ * package whose `exports` hides its main still resolves its own manifest by convention. A failure
+ * to resolve returns null, and the caller reports "absent" exactly as before — the repair changes
+ * how we look, never whether a real miss is reported.
+ */
+function resolveDepDir(fromRoot, name) {
+    if (name === '')
+        return null;
+    try {
+        return path.dirname(require.resolve(`${name}/package.json`, { paths: [fromRoot] }));
+    }
+    catch {
+        return null;
+    }
+}
+function gatherNativeEvidence(packageRoot) {
+    const name = 'better-sqlite3';
+    // @implements A-SPEC-583.1 — resolved, not joined. A hoisted install is the npm default.
+    const pkgDir = resolveDepDir(packageRoot, name);
+    const bindingPresent = pkgDir !== null && 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 +349,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 });
@@ -223,39 +381,39 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     // 2. Node version vs better-sqlite3's declared range (WARN only — a mismatch still often works).
     let sqliteRange = '(unknown)';
     try {
-        sqliteRange = JSON.parse(fs.readFileSync(path.join(packageRoot, 'node_modules', 'better-sqlite3', 'package.json'), 'utf8')).engines?.node ?? '(none)';
+        // @implements A-SPEC-583.1 — the SIBLING of the evidence lookup; both move together.
+        sqliteRange = JSON.parse(fs.readFileSync(path.join(resolveDepDir(packageRoot, 'better-sqlite3') ?? '', 'package.json'), 'utf8')).engines?.node ?? '(none)';
     }
     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 +967,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 +1048,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 +1262,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 +1296,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 +1557,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]

package/dist/holmes/cli/native-deps.d.ts

@@ -0,0 +1,65 @@
+import type { Coverage } from '../project/install-scripts-policy';
+/**
+ * @implements A-SPEC-580
+ * Why better-sqlite3 has no binary — judged from EVIDENCE, not from the load error's wording.
+ *
+ * Measured 2026-09-09 (Windows, npm 12.0.1, Node 24.19.0): doctor said "ABI-locked … reinstall"
+ * when the real cause was npm 12 skipping the install script for lack of an `allowScripts` entry.
+ * A reinstall reproduces the same state. At least five causes hide behind one FAIL and each has a
+ * different remedy, so this module collects what is observable and refuses to assert what is not:
+ * a prebuilt-download failure leaves no trace doctor can read, and is named as a possibility only.
+ *
+ * Pure. The caller (doctor) gathers the evidence; every process it spawns for that is optional,
+ * and "not observed" is carried as `undefined`, never as `false`.
+ */
+export type InstallKind = 'repo' | 'local' | 'global' | 'npx' | 'unknown';
+export type NativeCause = 'ok' | 'scripts-blocked' | 'abi-mismatch' | 'build-failed' | 'unknown';
+export type Level = 'PASS' | 'WARN' | 'FAIL';
+export interface NativeEvidence {
+    platform: string;
+    packageName: string;
+    packageVersion: string;
+    /** `build/Release/<name>.node` exists under the package. */
+    bindingPresent: boolean;
+    /** The first line of the `require` failure, when it failed. */
+    loadError?: string;
+    /** `npm --version` major; undefined when npm could not be consulted. */
+    npmMajor?: number;
+    /** How the ROOT package.json that governs this install covers the package (A-SPEC-579). */
+    coverage: Coverage;
+    installKind: InstallKind;
+    /** win32 only: whether a source build could even start. */
+    toolchain?: {
+        python: boolean;
+        msvc: boolean;
+    };
+    /** node-gyp is known to trip over spaces in the install path. */
+    pathHasSpace: boolean;
+    /** win32 only: `Get-ExecutionPolicy`, when observed. */
+    psPolicy?: string;
+}
+/** Where this package lives — the layout decides which package.json (if any) holds the policy. */
+export declare function installKind(packageRoot: string, globalDir?: string): InstallKind;
+/**
+ * The narrowest commands that repair each layout. `--allow-scripts=<pkg>` is a per-invocation flag
+ * scoped to ONE package — never `--dangerously-allow-all-scripts`, never a change to npm config.
+ *
+ * Global targets the DEPENDENCY, not the holmes-kit package: measured 2026-09-09 (npm 12.0.1,
+ * Windows), `npm rebuild -g @holmes-lab/holmes-kit` re-links the bin and dies EEXIST on the
+ * existing `holmes-kit` shim before any script runs, while `npm rebuild -g better-sqlite3
+ * --allow-scripts=better-sqlite3` runs `prebuild-install` in place. (It then needs the global
+ * prefix to be writable — a protected prefix fails EPERM there, which is the `global prefix`
+ * check's territory, not this one's.)
+ */
+export declare function recoveryCommands(ev: Pick<NativeEvidence, 'platform' | 'installKind' | 'packageName' | 'packageVersion'>): string[];
+/**
+ * What a PowerShell execution policy means for the emitted commands. Only the two policies that
+ * refuse every unsigned local script block the `npm.ps1`/`npx.ps1` shims; the rest add nothing.
+ */
+export declare function powershellPolicyNote(policy: string | undefined): string;
+export declare function nativeVerdict(ev: NativeEvidence): {
+    cause: NativeCause;
+    level: Level;
+    detail: string;
+    fix?: string;
+};

package/dist/holmes/cli/native-deps.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installKind = installKind;
+exports.recoveryCommands = recoveryCommands;
+exports.powershellPolicyNote = powershellPolicyNote;
+exports.nativeVerdict = nativeVerdict;
+// @implements A-SPEC-580
+// @implements A-SPEC-580.1
+const npx_bin_1 = require("../project/npx-bin");
+const install_scripts_policy_1 = require("../project/install-scripts-policy");
+const HOLMES_PKG = '@holmes-lab/holmes-kit';
+/** Where this package lives — the layout decides which package.json (if any) holds the policy. */
+function installKind(packageRoot, globalDir) {
+    const norm = packageRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (norm.split('/').includes('_npx'))
+        return 'npx';
+    if (globalDir) {
+        const g = globalDir.replace(/\\/g, '/').replace(/\/+$/, '');
+        if (norm.toLowerCase().startsWith(`${g.toLowerCase()}/`))
+            return 'global';
+    }
+    if (/\/node_modules\/@holmes-lab\/holmes-kit$/.test(norm))
+        return 'local';
+    return 'repo';
+}
+/**
+ * The narrowest commands that repair each layout. `--allow-scripts=<pkg>` is a per-invocation flag
+ * scoped to ONE package — never `--dangerously-allow-all-scripts`, never a change to npm config.
+ *
+ * Global targets the DEPENDENCY, not the holmes-kit package: measured 2026-09-09 (npm 12.0.1,
+ * Windows), `npm rebuild -g @holmes-lab/holmes-kit` re-links the bin and dies EEXIST on the
+ * existing `holmes-kit` shim before any script runs, while `npm rebuild -g better-sqlite3
+ * --allow-scripts=better-sqlite3` runs `prebuild-install` in place. (It then needs the global
+ * prefix to be writable — a protected prefix fails EPERM there, which is the `global prefix`
+ * check's territory, not this one's.)
+ */
+function recoveryCommands(ev) {
+    const npm = (0, npx_bin_1.npmBin)(ev.platform);
+    const project = [
+        (0, install_scripts_policy_1.approveCommand)(ev.packageName, ev.packageVersion, npm),
+        `${npm} rebuild ${ev.packageName} --foreground-scripts`,
+    ];
+    switch (ev.installKind) {
+        case 'global': return [`${npm} rebuild -g ${ev.packageName} --foreground-scripts --allow-scripts=${ev.packageName}`];
+        case 'npx': return [`${npm} install --save-dev ${HOLMES_PKG}`, ...project];
+        default: return project;
+    }
+}
+/** A rebuild alone (the script is approved or the policy is not the problem). */
+function rebuildCommand(ev) {
+    const npm = (0, npx_bin_1.npmBin)(ev.platform);
+    return ev.installKind === 'global'
+        ? `${npm} rebuild -g ${ev.packageName} --foreground-scripts --allow-scripts=${ev.packageName}`
+        : `${npm} rebuild ${ev.packageName} --foreground-scripts`;
+}
+/**
+ * What a PowerShell execution policy means for the emitted commands. Only the two policies that
+ * refuse every unsigned local script block the `npm.ps1`/`npx.ps1` shims; the rest add nothing.
+ */
+function powershellPolicyNote(policy) {
+    if (policy === 'Restricted' || policy === 'AllSigned') {
+        return `PowerShell execution policy ${policy} blocks the npm.ps1/npx.ps1 shims — use npm.cmd/npx.cmd (the commands above already do).`;
+    }
+    return '';
+}
+const ABI_RE = /NODE_MODULE_VERSION|compiled against a different Node\.js version/;
+function nativeVerdict(ev) {
+    const pkg = `${ev.packageName}@${ev.packageVersion}`;
+    const isWin = ev.platform === 'win32';
+    const psNote = isWin ? powershellPolicyNote(ev.psPolicy) : '';
+    const withPs = (detail) => (psNote ? `${detail} ${psNote}` : detail);
+    const approved = ev.coverage === 'approved-pinned' || ev.coverage === 'approved-unpinned';
+    const policyHome = ev.installKind === 'repo' || ev.installKind === 'local'
+        ? 'the project package.json (allowScripts)'
+        : `no package.json can carry the approval for a ${ev.installKind} install — approve per command instead`;
+    // 1. Loads → nothing to diagnose. The wording is read by other suites; keep it byte-identical.
+    if (ev.bindingPresent && !ev.loadError) {
+        return { cause: 'ok', level: 'PASS', detail: 'loads and executes against :memory:' };
+    }
+    // 2. The binary exists but was built for another Node ABI — the ONE case the old wording fit.
+    if (ev.loadError && ABI_RE.test(ev.loadError)) {
+        return {
+            cause: 'abi-mismatch', level: 'FAIL',
+            detail: withPs(`${pkg} was built for a different Node ABI (running ${process.version}): ${ev.loadError}`),
+            fix: `Rebuild against this Node: ${rebuildCommand(ev)}`,
+        };
+    }
+    if (!ev.bindingPresent && !approved) {
+        // 3. npm ≥ 12 skips the script without an approval. That the approval is missing IS observed;
+        //    an unobserved npm version does not change the remedy, so it is said and the same commands go out.
+        if (ev.npmMajor === undefined || ev.npmMajor >= 12) {
+            const npmSaid = ev.npmMajor === undefined ? 'npm (npm version not observed)' : `npm ${ev.npmMajor}`;
+            const denied = ev.coverage === 'denied' ? ` (allowScripts explicitly denied ${ev.packageName})` : '';
+            return {
+                cause: 'scripts-blocked', level: 'FAIL',
+                detail: withPs(`no binary — ${npmSaid} blocks dependency install scripts unless allowScripts covers ${pkg}${denied}; policy home: ${policyHome}.`),
+                fix: `Approve the one script that must run, then rebuild: ${recoveryCommands(ev).join(' && ')}`,
+            };
+        }
+        // 6b. Early npm 11 did not block scripts, so a missing approval proves nothing about why the
+        //     script left no binary — say so instead of inventing a cause.
+        return {
+            cause: 'unknown', level: 'FAIL',
+            detail: withPs(`no binary — npm ${ev.npmMajor} may or may not have run the install script; rerun with --foreground-scripts to see what happened.`),
+            fix: `${rebuildCommand(ev)} — then run doctor again.`,
+        };
+    }
+    // 4. Approved, yet no binary: the script ran and produced nothing. What it could not do is
+    //    partly observable (toolchain, path); a failed prebuild download is not.
+    if (!ev.bindingPresent) {
+        const missing = [];
+        if (ev.toolchain?.python === false)
+            missing.push('Python is not on PATH (node-gyp needs it)');
+        if (ev.toolchain?.msvc === false)
+            missing.push('Visual Studio C++ Build Tools (MSVC) were not found');
+        if (ev.pathHasSpace)
+            missing.push('the install path contains a space, which node-gyp is known to mishandle');
+        const because = missing.length ? ` Observed obstacles to a source build: ${missing.join('; ')}.` : '';
+        return {
+            cause: 'build-failed', level: 'FAIL',
+            detail: withPs(`the install script for ${pkg} is approved but produced no binary — a prebuilt download failure is not observable here.${because} Rerun with --foreground-scripts to see the script's own output.`),
+            fix: `${rebuildCommand(ev)} — install the missing toolchain (or use a Node version with a prebuilt binary) if the output shows a compile step.`,
+        };
+    }
+    // 6a. Present but failing to load for a reason we do not recognise — quote it, do not classify it.
+    return {
+        cause: 'unknown', level: 'FAIL',
+        detail: withPs(`${pkg} is present but failed to load: ${ev.loadError ?? '(no error text)'}`),
+        fix: `${rebuildCommand(ev)} — then run doctor again.`,
+    };
+}

package/dist/holmes/cpg/cycle-observation.d.ts

@@ -0,0 +1,65 @@
+import { type Cycle } from './cycle-detect';
+/**
+ * How many cycles one record lists before it starts counting instead.
+ *
+ * A record must not grow with the tree: a repository with a thousand cycles would otherwise write a
+ * thousand-entry line every turn, and the ledger this exists to make readable would be the thing
+ * that makes it unreadable. What is dropped is COUNTED, never silently cut.
+ */
+export declare const CYCLE_LIST_CAP = 50;
+/**
+ * One turn's observation — paths, integers and enums only.
+ *
+ * ADR-012's redaction rule is what lets this file be git-tracked at all: no prose, no command
+ * strings, no file content. `files` are the scanner's project-relative paths, which the impact and
+ * density ledgers already carry.
+ */
+export interface CycleObservationRecord {
+    ts: string;
+    mode: 'strict' | 'track' | 'off';
+    cycles: Array<{
+        key: string;
+        files: string[];
+        runtime: boolean;
+        edges: number;
+    }>;
+    /** Cycles beyond CYCLE_LIST_CAP: counted, so a truncation is never mistaken for a clean tree. */
+    cyclesOmitted: number;
+    /** Keys of the runtime cycles nobody allowed — the ratchet's verdict at this moment. */
+    violations: string[];
+    allowed: number;
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+    replica?: string;
+}
+/** The cycle evidence the Stop hook computes, in the shape it already holds it. */
+export interface CycleEvidence {
+    current: Cycle[];
+    allowed: string[];
+    mode: 'strict' | 'track' | 'off';
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+}
+/**
+ * Build the record. PURE — the clock is an argument, so a test can pin it and two callers cannot
+ * disagree about what "now" was.
+ *
+ * A CLEAN run produces a record too. That is the whole design: a false-positive RATE is violations
+ * over chances, and a ledger that only speaks when something is wrong records the numerator and
+ * throws the denominator away.
+ */
+export declare function buildCycleObservation(ev: CycleEvidence, ts: string): CycleObservationRecord;
+/**
+ * Append one record. Never throws, and never creates `.ax` where governance was not opted into
+ * (A-SPEC-191 §25 — the same refusal the approval queue makes).
+ *
+ * A failure returns `false` and changes nothing else: this is an OBSERVATION, and an observation
+ * that could alter a verdict would be a gate wearing a different name.
+ */
+export declare function appendCycleObservation(root: string, rec: CycleObservationRecord): boolean;
+/** Every replica's records, merged. A corrupt line is skipped, never fatal. */
+export declare function readCycleObservations(root: string): CycleObservationRecord[];