@holmes-lab/holmes-kit 0.19.3 → 0.19.5

package/dist/holmes/cli/doctor.js

@@ -34,8 +34,10 @@ 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;
@@ -49,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
@@ -58,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");
@@ -82,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 {
@@ -147,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.
  *
@@ -171,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'
@@ -1039,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') {
@@ -1170,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) });
@@ -1288,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));
@@ -1340,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;
@@ -1353,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', () => { });
@@ -1404,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
@@ -1600,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;

package/dist/holmes/cli/test-platform.js

@@ -1,8 +1,48 @@
 "use strict";
-// @implements A-SPEC-220.3
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.posixOnly = posixOnly;
 exports.posixOnlyNonRoot = posixOnlyNonRoot;
+exports.foldsCase = foldsCase;
+exports.posixOnlyWithCommand = posixOnlyWithCommand;
+exports.win32Only = win32Only;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+// @implements A-SPEC-220.3
+// @implements A-SPEC-597
 /**
  * A test that cannot run here says so, instead of returning early and being counted as a pass.
  *
@@ -36,3 +76,88 @@ function posixOnlyNonRoot(reason, platform = process.platform, uid = typeof proc
     const base = posixOnly(reason, platform);
     return uid === 0 ? it.skip : base;
 }
+/**
+ * @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.
+ */
+function foldsCase(dir) {
+    if (typeof dir !== 'string' || dir === '')
+        return false;
+    const probe = path.join(dir, `.case-probe-${process.pid}-${(0, node_crypto_1.randomUUID)()}`);
+    try {
+        fs.writeFileSync(probe, '');
+        const flipped = path.join(dir, path.basename(probe).toUpperCase());
+        return fs.existsSync(flipped);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        // The probe leaves no trace, on every path out of here.
+        try {
+            fs.rmSync(probe, { force: true });
+        }
+        catch { /* nothing was created */ }
+    }
+}
+/** PATH lookup without a shell — spawning one to ask about a command is a cost and a surface. */
+function onPath(command) {
+    if (typeof command !== 'string' || command === '')
+        return false;
+    if (command.includes('/') || command.includes('\\'))
+        return fs.existsSync(command);
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const exts = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const dir of (process.env.PATH ?? '').split(sep)) {
+        if (dir === '')
+            continue;
+        for (const ext of exts) {
+            try {
+                if (fs.existsSync(path.join(dir, command + ext)))
+                    return true;
+            }
+            catch { /* unreadable PATH entry */ }
+        }
+    }
+    return false;
+}
+/**
+ * @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.
+ */
+function posixOnlyWithCommand(reason, command, platform = process.platform, uid = typeof process.getuid === 'function' ? process.getuid() : undefined, lookup = onPath) {
+    const base = posixOnlyNonRoot(reason, platform, uid); // reason is validated here, before anything else
+    return lookup(command) ? base : 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.
+ */
+function win32Only(reason, platform = process.platform) {
+    if (typeof reason !== 'string' || reason.trim().length === 0) {
+        throw new Error('win32Only(reason): 사유 없는 스킵은 문법만 바뀐 침묵입니다 — 왜 이 단언이 POSIX에서 무의미한지 적으십시오.');
+    }
+    return platform === 'win32' ? it : it.skip;
+}