@holmes-lab/holmes-kit 0.19.2 → 0.19.4

package/dist/holmes/cli/doctor.js

@@ -34,10 +34,13 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STRIPPED_FOR_PROBE = void 0;
+exports.resolvesToPackage = resolvesToPackage;
 exports.globalInstallDir = globalInstallDir;
 exports.npmCliEntry = npmCliEntry;
+exports.probeWritable = probeWritable;
 exports.prefixVerdict = prefixVerdict;
 exports.grammarProbe = grammarProbe;
+exports.resolveDepDir = resolveDepDir;
 exports.gatherNativeEvidence = gatherNativeEvidence;
 exports.probeEnv = probeEnv;
 exports.resolveWiringPath = resolveWiringPath;
@@ -48,6 +51,9 @@ exports.formatChecks = formatChecks;
 exports.wiringHandshakeChecks = wiringHandshakeChecks;
 exports.semanticTierVerdict = semanticTierVerdict;
 exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
+// @implements A-SPEC-594
+// @implements A-SPEC-592
+// @implements A-SPEC-591
 // @implements A-SPEC-442
 // @implements A-SPEC-207
 // @implements A-SPEC-100.2
@@ -57,6 +63,7 @@ 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 probe_process_1 = require("./probe-process");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
 const blind_spots_1 = require("../guardrail/blind-spots");
@@ -81,8 +88,20 @@ function resolvesToPackage(filePath, packageRoot) {
     try {
         if (path.resolve(filePath).startsWith(path.resolve(packageRoot) + path.sep))
             return true;
-        const realFile = fs.realpathSync(filePath);
-        const realPkg = fs.realpathSync(packageRoot);
+        // @implements A-SPEC-586.2 — canonical, not merely real: the JS `realpathSync` walks lstat and
+        // leaves a Windows 8.3 short name (`HOLMES~1`) as it is, so the very hook path init writes for a
+        // spaced install read as "another install". `realpathSync.native` asks the OS for the final
+        // path, which expands short names and follows links alike (measured 2026-09-10).
+        const canonical = (p) => {
+            try {
+                return fs.realpathSync.native(p);
+            }
+            catch {
+                return fs.realpathSync(p);
+            }
+        };
+        const realFile = canonical(filePath);
+        const realPkg = canonical(packageRoot);
         return realFile.startsWith(realPkg + path.sep);
     }
     catch {
@@ -146,6 +165,31 @@ function npmCliEntry(env = process.env, execPath = process.execPath) {
     }
     return null;
 }
+/**
+ * @implements A-SPEC-584
+ * Is `dir` writable by THIS account? Asked by TRYING, not by `fs.accessSync(W_OK)`: on Windows the
+ * mode bits accessSync consults do not carry the ACL, so it answered "writable" for
+ * `C:\Program Files\nodejs` on a non-admin account while `mkdir` died EPERM (measured 2026-09-10).
+ * A mkdir is the very syscall npm's own EPERM comes from (creating the scope directory), so the probe
+ * makes one and removes it. A probe entry that could not be removed is reported, never hidden.
+ * Nothing thrown; a missing or non-directory `dir` is simply not writable.
+ */
+function probeWritable(dir) {
+    const probe = path.join(dir, `.holmes-doctor-probe-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+    try {
+        fs.mkdirSync(probe);
+    }
+    catch {
+        return { writable: false };
+    }
+    try {
+        fs.rmdirSync(probe);
+        return { writable: true };
+    }
+    catch {
+        return { writable: true, leftover: probe };
+    }
+}
 /**
  * Judge the global prefix. Pure — the probing lives with the caller.
  *
@@ -170,6 +214,11 @@ function prefixVerdict(input) {
     }
     const prefix = input.prefix;
     if (input.writable) {
+        // @implements A-SPEC-584 — writable, but the probe left something behind: a PASS would hide a
+        // file the user now has to clean up. Say where it is.
+        if (typeof input.leftover === 'string' && input.leftover !== '') {
+            return { level: 'WARN', detail: `Global prefix (${prefix}) is writable by the current account, but doctor's probe directory could not be removed: ${input.leftover} — delete it by hand.` };
+        }
         return { level: 'PASS', detail: `Global prefix (${prefix}) is writable by the current account — npm install -g works without permission trouble.` };
     }
     const fix = input.platform === 'win32'
@@ -241,13 +290,39 @@ function observe(file, args) {
  * 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';
-    const pkgDir = path.join(packageRoot, 'node_modules', name);
-    const bindingPresent = fs.existsSync(path.join(pkgDir, 'build', 'Release', 'better_sqlite3.node'));
+    // @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;
+        packageVersion = JSON.parse(fs.readFileSync(path.join(pkgDir ?? '', 'package.json'), 'utf8')).version ?? packageVersion;
     }
     catch { /* not installed */ }
     let loadError;
@@ -354,7 +429,8 @@ 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.');
@@ -1011,7 +1087,14 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             }
             else {
                 const entry = (0, codex_toml_1.readCodexHolmesEntry)(raw);
-                if (!entry) {
+                // @implements A-SPEC-585 — an invalid basic-string escape (a raw Windows backslash path is the
+                // measured case) is not "half-done": Codex refuses the whole file, and the reader must not
+                // hand doctor a mangled path to judge. Name the escape and the line.
+                const badEscape = entry ? null : (0, codex_toml_1.invalidTomlEscape)(raw);
+                if (!entry && badEscape) {
+                    add('codex wiring', 'WARN', `${cdxToml} has an invalid escape ${badEscape.escape} on line ${badEscape.line} inside [mcp_servers.${init_1.SERVER_NAME}] — Codex refuses this file. On Windows, double each backslash ("C:\\\\path") or use a single-quoted literal string ('C:\\path').`, 'Rewire with holmes-kit init --target <dir> --agent codex --force (it writes valid TOML).');
+                }
+                else if (!entry) {
                     add('codex wiring', 'WARN', `${cdxToml} has no runnable [mcp_servers.${init_1.SERVER_NAME}] entry — a half-done wiring`, 'Rewire with holmes-kit init --target <dir> --agent codex.');
                 }
                 else if (entry.command === 'node') {
@@ -1142,13 +1225,10 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                     break;
                 probe = parent;
             }
-            let writable = false;
-            try {
-                fs.accessSync(probe, fs.constants.W_OK);
-                writable = true;
-            }
-            catch { /* not writable */ }
-            verdict = prefixVerdict({ prefix, dir, writable, platform: process.platform });
+            // @implements A-SPEC-584 — TRY, do not ask: the mode-bit question said "writable" for a
+            // protected Windows prefix (ACLs are invisible to it) and sent users into npm's EPERM.
+            const tried = probeWritable(probe);
+            verdict = prefixVerdict({ prefix, dir, writable: tried.writable, leftover: tried.leftover, platform: process.platform });
         }
         catch (e) {
             verdict = prefixVerdict({ unreadable: e instanceof Error ? e.message.split('\n')[0] : String(e) });
@@ -1260,15 +1340,15 @@ cwd) {
                 return;
             done = true;
             clearTimeout(timer);
-            try {
-                child.kill();
-            }
-            catch { /* already gone */ }
-            resolve({ name: 'mcp wiring spawn', level, detail, fix });
+            void (0, probe_process_1.stopProbeProcess)(child).then(released => resolve(released
+                ? { name: 'mcp wiring spawn', level, detail, fix }
+                : { name: 'mcp wiring spawn', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed`,
+                    fix: `${fix ?? ''} Close the remaining diagnostic process for \`${command}\`, then retry doctor.` }));
         };
-        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);
+        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 for \`${command}\`, then re-run doctor.`), timeoutMs);
         try {
-            child = (0, node_child_process_1.spawn)(spec.command, spec.args, { stdio: ['pipe', 'pipe', 'pipe'], ...(cwd === undefined ? {} : { cwd }) });
+            child = (0, node_child_process_1.spawn)(spec.command, spec.args, { ...probe_process_1.PROBE_SPAWN_OPTIONS, stdio: ['pipe', 'pipe', 'pipe'], ...(cwd === undefined ? {} : { cwd }) });
+            (0, probe_process_1.trackProbeProcess)(child);
         }
         catch (e) {
             finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, spawnFailFix(e));
@@ -1312,7 +1392,8 @@ cwd) {
 function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
     return new Promise((resolve) => {
         const mcpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-doctor-mcp-'));
-        const child = (0, node_child_process_1.spawn)(process.execPath, [path.join(packageRoot, 'bin', 'holmes-mcp.js')], { stdio: ['pipe', 'pipe', 'pipe'], cwd: mcpCwd });
+        let child;
+        let timer;
         let pending = ''; // the unterminated tail of the stdout stream, never the whole history
         let err = '';
         let done = false;
@@ -1325,30 +1406,29 @@ function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
                 return;
             done = true;
             clearTimeout(timer);
-            // Escalate (round-9): SIGTERM alone leaves a wedged server running with doctor's pipes open.
-            child.kill();
-            // round-10: an unref'd timer never fires in a doctor run that ends in ~0.4s, so the escalation
-            // was decoration. The timer holds the loop for its 500ms and is cleared the moment the child
-            // actually exits, so a healthy run pays nothing.
-            const hard = setTimeout(() => { try {
-                child.kill('SIGKILL');
-            }
-            catch { /* already gone */ } }, 500);
-            child.once('exit', () => clearTimeout(hard));
-            child.stdout.destroy();
-            child.stderr.destroy();
-            child.stdin.destroy();
-            child.unref?.();
-            // Cleanup HERE, not on 'close' — doctor's process can exit before a close handler runs,
-            // stranding the isolated cwd (round-6 §7e measured the leak). A signal death still strands it;
-            // `cleanupOnSignal` below covers that (round-9).
-            try {
-                fs.rmSync(mcpCwd, { recursive: true, force: true });
-            }
-            catch { /* tmp cleaner's job */ }
-            resolve({ name: 'MCP server', level, detail, fix });
+            void (0, probe_process_1.stopProbeProcess)(child).then(async (released) => {
+                let removed = false;
+                try {
+                    await fs.promises.rm(mcpCwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+                    DOCTOR_TEMP_DIRS.delete(mcpCwd);
+                    removed = true;
+                }
+                catch { /* signal cleanup retains the path for a later attempt */ }
+                resolve(released && removed
+                    ? { name: 'MCP server', level, detail, fix }
+                    : { name: 'MCP server', level: 'FAIL', detail: `${detail}; probe cleanup could not be confirmed`,
+                        fix: 'Close the remaining diagnostic process and retry doctor.' });
+            });
         };
         cleanupOnSignal(mcpCwd);
+        try {
+            child = (0, node_child_process_1.spawn)(process.execPath, [path.join(packageRoot, 'bin', 'holmes-mcp.js')], { ...probe_process_1.PROBE_SPAWN_OPTIONS, stdio: ['pipe', 'pipe', 'pipe'], cwd: mcpCwd });
+            (0, probe_process_1.trackProbeProcess)(child);
+        }
+        catch (error) {
+            finish('FAIL', `could not spawn the MCP server: ${error.message}`, 'Check the install and executable permissions, then retry doctor.');
+            return;
+        }
         // EPIPE arrives as an ASYNC 'error' event, not a synchronous throw — the try/catch below never
         // sees it, and an unhandled stream error would crash doctor itself (round-1 REQ-192).
         child.stdin.on('error', () => { });
@@ -1376,7 +1456,7 @@ function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
             child.stdin.write(JSON.stringify(o) + '\n');
         }
         catch { /* server gone */ } };
-        const timer = setTimeout(() => finish('FAIL', `no tools/list response within ${timeoutMs}ms (stderr: ${err.slice(0, 160)})`, 'The MCP server did not start. A missing tree-sitter grammar is the usual cause (see above).'), timeoutMs);
+        timer = setTimeout(() => finish('FAIL', `no tools/list response within ${timeoutMs}ms (stderr: ${err.slice(0, 160)})`, 'The MCP server did not start. A missing tree-sitter grammar is the usual cause (see above).'), timeoutMs);
         // Line-oriented and stateful. The old shape re-scanned the whole accumulated buffer on every
         // chunk (quadratic, and it re-fired past triggers) and judged `tools` by
         // `typeof result.tools.length === 'number'` — which a NON-ARRAY or an EMPTY list satisfies, so a
@@ -1572,9 +1652,22 @@ function semanticTierVerdict(t) {
         };
     }
     if (t.tier === 'local') {
+        return {
+            level: 'WARN',
+            detail: `Semantic search tier: local (${t.model}, ${(0, tier_1.POOLING_OF)(t.model ?? '')} pooling) — no egress during inference. Runtime and model readiness are unverified by this lightweight check.`,
+            fix: 'Run holmes-kit semantic-check for actual offline inference; if unavailable, run holmes-kit semantic-setup.',
+        };
+    }
+    // @implements A-SPEC-594 — two different 'none' states need two different sentences. When the
+    // runtime is already installed, telling the user to install it is noise; the missing piece is
+    // the model, and the command that fetches it is the whole fix. Both stay PASS: a user who never
+    // asked for a semantic tier is not misconfigured, and a WARN that cannot be resolved by any
+    // action teaches people to skip doctor's output entirely.
+    if (t.localRuntimePresent) {
         return {
             level: 'PASS',
-            detail: `Semantic search tier: local (${t.model}, ${(0, tier_1.POOLING_OF)(t.model ?? '')} pooling) — no egress. Recovers 52% of requests lexical search misses (measured).`,
+            detail: 'Semantic search tier: none — the local runtime is installed but its model was never prepared, so no embedding is produced. Requests lexical search misses (measured 16.4%) have 0% recall.',
+            fix: 'Run `holmes-kit semantic-setup` to download the public model once (shared across projects) — lexical-zero recall 0→52%, no egress. Cloud tier (opt-in, consent to external transfer): set GEMINI_API_KEY — 0→92%.',
         };
     }
     return {

package/dist/holmes/cli/index.js

@@ -37,6 +37,7 @@ exports.isBrokenPipe = void 0;
 exports.packageRoot = packageRoot;
 exports.main = main;
 exports.installPipeGuard = installPipeGuard;
+// @implements A-SPEC-591
 // @implements A-SPEC-100.2
 // @implements A-SPEC-213
 // @implements A-SPEC-215
@@ -82,6 +83,8 @@ const KNOWN_FLAGS = {
     ledger: ['help', 'target', 'ref', 'dry-run'],
     // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
     'semantic-key': ['help'],
+    'semantic-setup': ['help'],
+    'semantic-check': ['help'],
     // @implements A-SPEC-509.1 — the explicit installation act for the pre-push evidence gate.
     'install-push-gate': ['help', 'target'],
     // @implements A-SPEC-543.2 — one-command upgrade: install + re-pin every registered workspace.
@@ -219,6 +222,8 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
     --target <dir>             project root (default: cwd)
 
   holmes-kit semantic-key set|unset|status   manage the cloud semantic tier opt-in key
+  holmes-kit semantic-setup                install and verify the default local BGE-M3 model
+  holmes-kit semantic-check                verify BGE-M3 offline without downloading
                              set reads from stdin only (the value never appears in argv or output).
                              Setting the key is consent to egress (spec prose, paths, symbol names sent externally).
 
@@ -310,6 +315,10 @@ async function main(argv) {
         process.stdout.write((0, colophon_1.colophon)());
         return 0;
     }
+    if (cmd === 'semantic-setup' || cmd === 'semantic-check') {
+        const { runModelSetup } = await Promise.resolve().then(() => __importStar(require('../semantic/local-model')));
+        return runModelSetup({ offline: cmd === 'semantic-check' });
+    }
     if (cmd === 'semantic-key') {
         // @implements A-SPEC-477 — set|unset|status; the key rides stdin, never argv.
         const { runSemanticKey } = await Promise.resolve().then(() => __importStar(require('./semantic-key')));
@@ -1141,6 +1150,10 @@ async function main(argv) {
                 catch { /* registry failure never fails init */ }
             }
         }
+        if (res.ok && !opts.dryRun && !opts.remove) {
+            const { runModelSetup } = await Promise.resolve().then(() => __importStar(require('../semantic/local-model')));
+            runModelSetup({ automatic: true });
+        }
         return res.exitCode;
     }
     // @implements A-SPEC-543.2 — one-command upgrade. Preparation is zero-config (init records the

package/dist/holmes/cli/init.js

@@ -472,9 +472,16 @@ function runInit(opts) {
                 }
                 changes.push({ path: f.path, before, after: f.content });
             }
-            messages.push(agents_1.HARNESS_ENFORCES[agent]
-                ? `${agent}: the gate is enforced (hooks wired).`
-                : `${agent}: only tools and instructions were wired — this harness does not enforce the gate.`);
+            // @implements A-SPEC-586 — an antigravity hook whose path still carries a space is a hook the
+            // launcher never runs (it splits on whitespace). Saying "enforced" over it was a false PASS
+            // measured on a Windows install under a spaced user directory; the warning replaces the claim.
+            const spaced = agent === 'antigravity' ? (0, agents_1.antigravityHookWarnings)(opts.packageRoot) : [];
+            if (spaced.length > 0)
+                messages.push(...spaced);
+            else
+                messages.push(agents_1.HARNESS_ENFORCES[agent]
+                    ? `${agent}: the gate is enforced (hooks wired).`
+                    : `${agent}: only tools and instructions were wired — this harness does not enforce the gate.`);
             // a link is placement, not content — a dry-run only says so, and only the real run creates it.
             for (const link of (0, agents_1.agentLinks)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir })) {
                 if (opts.dryRun) {

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

@@ -4,6 +4,7 @@ exports.installKind = installKind;
 exports.recoveryCommands = recoveryCommands;
 exports.powershellPolicyNote = powershellPolicyNote;
 exports.nativeVerdict = nativeVerdict;
+// @implements A-SPEC-599
 // @implements A-SPEC-580
 // @implements A-SPEC-580.1
 const npx_bin_1 = require("../project/npx-bin");
@@ -94,7 +95,9 @@ function nativeVerdict(ev) {
             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(' && ')}`,
+                fix: `Approve the one script that must run, then rebuild: ${recoveryCommands(ev).join(isWin
+                    ? "; if ($LASTEXITCODE -ne 0) { throw 'Native dependency recovery failed' }; "
+                    : ' && ')}`,
             };
         }
         // 6b. Early npm 11 did not block scripts, so a missing approval proves nothing about why the

package/dist/holmes/cli/playbook-skills.js

@@ -45,6 +45,7 @@ exports.skillLabel = skillLabel;
 exports.playbookSkillStates = playbookSkillStates;
 exports.classifyExtraEntries = classifyExtraEntries;
 exports.installedPlaybookCount = installedPlaybookCount;
+// @implements A-SPEC-190
 // @implements A-SPEC-142
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -199,13 +200,14 @@ function aliasGroupsOf(packageRoot, target) {
     // playbook's body overwrite the other's — the exact harm the round-8 pre-scan was added to stop.
     const identity = (name) => {
         const real = realOf(name);
+        // NTFS file IDs can exceed Number precision; rounded IDs alias unrelated files.
         try {
-            const st = fs.statSync(real);
+            const st = fs.statSync(real, { bigint: true });
             return `${st.dev}:${st.ino}`;
         }
         catch { /* not yet there */ }
         try {
-            const st = fs.statSync(path.dirname(real));
+            const st = fs.statSync(path.dirname(real), { bigint: true });
             return `${st.dev}:${st.ino}:${path.basename(real).toLowerCase()}`;
         }
         catch { /* dangling */ }
@@ -652,8 +654,8 @@ function playbookSkillStates(packageRoot, target) {
     }
     for (const entry of classifyExtraEntries(entries, shipped, (entry2, canonical) => {
         try {
-            const a = fs.statSync(path.join(skillsDir, entry2));
-            const b = fs.statSync(path.join(skillsDir, canonical));
+            const a = fs.statSync(path.join(skillsDir, entry2), { bigint: true });
+            const b = fs.statSync(path.join(skillsDir, canonical), { bigint: true });
             return a.ino === b.ino && a.dev === b.dev;
         }
         catch {

package/dist/holmes/cli/probe-process.d.ts

@@ -0,0 +1,8 @@
+import { type ChildProcess } from 'node:child_process';
+/** Each POSIX probe gets its own process group; Windows taskkill targets only its owned PID. */
+export declare const PROBE_SPAWN_OPTIONS: {
+    detached: boolean;
+    windowsHide: boolean;
+};
+export declare function trackProbeProcess(child: ChildProcess): void;
+export declare function stopProbeProcess(child?: ChildProcess): Promise<boolean>;

package/dist/holmes/cli/probe-process.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROBE_SPAWN_OPTIONS = void 0;
+exports.trackProbeProcess = trackProbeProcess;
+exports.stopProbeProcess = stopProbeProcess;
+// @implements A-SPEC-592
+const node_child_process_1 = require("node:child_process");
+/** Each POSIX probe gets its own process group; Windows taskkill targets only its owned PID. */
+exports.PROBE_SPAWN_OPTIONS = { detached: process.platform !== 'win32', windowsHide: true };
+const states = new WeakMap();
+function trackProbeProcess(child) {
+    if (states.has(child))
+        return;
+    const state = { closed: false };
+    states.set(child, state);
+    child.once('close', () => { state.closed = true; });
+}
+async function stopProbeProcess(child) {
+    if (!child)
+        return true;
+    trackProbeProcess(child);
+    let closed = states.get(child).closed;
+    let onClose = () => { };
+    let closeTimer;
+    const closure = new Promise(resolve => {
+        onClose = () => { closed = true; clearTimeout(closeTimer); resolve(true); };
+        child.once('close', onClose);
+        closeTimer = setTimeout(() => resolve(false), 3000);
+        if (closed || !child.pid)
+            onClose();
+    });
+    let stopped = true;
+    try {
+        if (child.pid && process.platform === 'win32' && !closed) {
+            stopped = await new Promise(resolve => {
+                (0, node_child_process_1.execFile)('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 2500 }, error => {
+                    resolve(!error);
+                });
+            });
+        }
+        else if (child.pid && process.platform !== 'win32') {
+            const signalGroup = (signal) => {
+                try {
+                    process.kill(-child.pid, signal);
+                }
+                catch (error) {
+                    if (error.code !== 'ESRCH')
+                        throw error;
+                    if (!closed)
+                        child.kill(signal);
+                }
+            };
+            signalGroup('SIGTERM');
+            // Escalate the group even if its wrapper exits first: a descendant may ignore SIGTERM.
+            await new Promise(resolve => setTimeout(resolve, 100));
+            signalGroup('SIGKILL');
+        }
+    }
+    catch {
+        stopped = false;
+    }
+    // Terminate the tree before closing stdin: an EOF could make the wrapper exit first,
+    // leaving Windows taskkill with no parent from which to enumerate its descendants.
+    child.stdin?.destroy();
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+    const released = await closure;
+    clearTimeout(closeTimer);
+    child.removeListener('close', onClose);
+    if (!released)
+        child.unref();
+    return stopped && released;
+}

package/dist/holmes/cli/spawn-spec.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.spawnSpecFor = spawnSpecFor;
+// @implements A-SPEC-592
 // @implements A-SPEC-499.1
 /**
  * Platform adapter for spawning a WIRING command verbatim. On win32, `npx` is `npx.cmd`, and a
@@ -14,7 +15,8 @@ exports.spawnSpecFor = spawnSpecFor;
  * PURE — platform arrives as an argument so every branch is testable off-Windows.
  */
 function spawnSpecFor(command, args, platform) {
-    if (platform !== 'win32')
+    const shim = /\.(cmd|bat)$/i.test(command) || /(?:^|[\\/])(npm|npx)$/i.test(command);
+    if (platform !== 'win32' || !shim)
         return { command, args: [...args] };
     const joined = [command, ...args].map((t) => (/\s/.test(t) ? `"${t}"` : t)).join(' ');
     return { command: 'cmd.exe', args: ['/d', '/s', '/c', joined] };

package/dist/holmes/cli/test-platform.d.ts

@@ -23,3 +23,40 @@ export declare function posixOnly(reason: string, platform?: string): typeof it
  * it belongs in the same choice rather than in a second early return inside the body.
  */
 export declare function posixOnlyNonRoot(reason: string, platform?: string, uid?: number | undefined): typeof it | typeof it.skip;
+/**
+ * @implements A-SPEC-597
+ * Whether THIS directory's filesystem folds case — measured, never inferred from the platform.
+ *
+ * macOS defaults to case-insensitive APFS and Linux to case-sensitive ext4, but neither is a rule:
+ * a case-sensitive volume mounts fine on macOS, and `os.tmpdir()` need not share the repository's
+ * volume. The same reasoning already governs the write gate (`pre-tool-use.ts`), which probes the
+ * project root rather than trusting `process.platform`; a test must probe the directory it actually
+ * writes into.
+ *
+ * An unanswerable probe returns FALSE. Claiming "folds" when it cannot tell would let a
+ * folding-world assertion run — and pass vacuously — on a case-sensitive box; claiming "sensitive"
+ * merely runs the other assertion, which fails loudly if it is wrong. Be wrong toward the side that
+ * still produces information.
+ */
+export declare function foldsCase(dir: string): boolean;
+/**
+ * @implements A-SPEC-597
+ * As `posixOnlyNonRoot`, and additionally skipped when `command` is not on PATH.
+ *
+ * `chflags` is macOS/BSD only. Guarded by platform and uid alone, the assertion that uses it RAN on
+ * Linux and died with ENOENT — which reads as a defect in the code under test rather than as a tool
+ * this machine does not have. Availability of the tool is knowable at definition time, exactly like
+ * the platform and the uid, so it belongs in the same choice.
+ */
+export declare function posixOnlyWithCommand(reason: string, command: string, platform?: string, uid?: number | undefined, lookup?: (command: string) => boolean): typeof it | typeof it.skip;
+/**
+ * @implements A-SPEC-255
+ * The mirror of `posixOnly`: a test whose SUBJECT only exists on Windows.
+ *
+ * Without this, the Windows work had nowhere to put such a test and improvised
+ * `(process.platform === 'win32' ? it : it.skip)('…')` — a skip with no stated reason, which is the
+ * silence `posixOnly` was written to end, in different syntax. NTFS ACLs, PowerShell 5.1 parsing and
+ * 8.3 short names are real subjects; they simply cannot be exercised on a POSIX box, and saying so
+ * in the report is the honest form. `reason` is required for the same reason it is required there.
+ */
+export declare function win32Only(reason: string, platform?: string): typeof it | typeof it.skip;