@holmes-lab/holmes-kit 0.19.2 → 0.19.4

package/CHANGELOG.md

@@ -5,6 +5,183 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.19.4] - 2026-09-10
+
+Three Windows diagnoses that pointed the wrong way, found by running the Windows plan on a real
+non-admin machine (Windows 11, Node 24.19, npm 12.0.1, codex 0.153.4); then two things the new
+required dependency broke on every operating system, found by reviewing that work on macOS.
+
+### Changed
+- **Preparing the local model is now opt-in** (REQ-594). Installing the package, running
+  `holmes-kit init`, and the Windows bootstrap no longer download model assets on their own; each
+  names `holmes-kit semantic-setup` instead. Set `HOLMES_AUTO_MODEL_INSTALL=1` to prepare during
+  installation. `HOLMES_SKIP_MODEL_INSTALL=1` still refuses and OUTRANKS the opt-in, so an explicit
+  refusal is never overridden, and the two skips say different things — telling someone they opted
+  out when they did not is a lie. All three operating systems share the default: the bootstrap
+  invokes the explicit command, which always downloads, so the gate had to live in the bootstrap too
+  or Windows would keep fetching after macOS and Linux stopped.
+
+### Fixed
+- **The semantic tier reported a capability it did not have** (REQ-594). Availability was decided by
+  `require.resolve('@xenova/transformers')`. Once that package became a required dependency the
+  predicate answered true for every install and stopped discriminating, so every user without a
+  cloud key was reported as `tier: local` — including users who had never downloaded a model, for
+  whom no embedding is produced at all. Availability is now a conjunction of runtime AND a prepared
+  model cache; an empty cache directory counts as unprepared, because an interrupted download leaves
+  exactly that. Until the model is prepared, `doctor` reports tier `none`, names what it costs
+  (requests lexical search misses, measured 16.4%, have 0% recall) and the one command that changes
+  it — as `PASS`, since a warning no action can resolve teaches people to skip the report.
+- **A new native dependency was approved without the rule that justifies it** (REQ-595).
+  `sharp@0.32.6` was added to `allowScripts` while the measured required-script list still held one
+  package, so the policy told readers sharp "loads from its shipped prebuilds without an install
+  script". Measured 2026-09-10, that is false everywhere: its tarball ships no native binary, its
+  hook is `prebuild-install || node-gyp rebuild`, the lockfile records `hasInstallScript: true`.
+  Because `allowScripts` is a root-manifest policy that does not transfer to consumers, a rule that
+  did not know sharp meant no consumer was ever told to approve it. Both required packages are now
+  named. The guard was not loosened: every member of the list must be backed by the lockfile, and an
+  empty lock now reports every required package rather than only the first.
+
+### Added
+- **`spec_renumber`** (REQ-255). Two sessions working from the same base each issued number 596, and
+  the repository's own prescription for that was `renumber one (manual until REQ-255) and re-seal` —
+  a tool specified after the 2026-08-23 incident and never built. A hand renumber then moved two
+  anchors and left seven prose references, one of them inside the shipped `install.ps1`, and the bulk
+  regex brought in to finish the job rewrote REQ-253's own `source.ref` into a citation of itself.
+  The tool is deliberately asymmetric: it moves what has a definite grammar (filenames, frontmatter
+  `id`, every `depends_on`, `slice` tags, `@implements` anchors) and only REPORTS what needs context
+  (prose, comments, test titles, CHANGELOG). Re-sealing stays with `spec_approve`; the plan returns
+  the two orders instead, which are opposites because unsealing refuses child-first and approving
+  refuses parent-first. `dryRun` is the default.
+- **`win32Only`** (A-SPEC-255). The mirror of `posixOnly`, for tests whose subject only exists on
+  Windows — NTFS ACLs, PowerShell 5.1 parsing. Without it those tests were written as anonymous
+  `platform === 'win32' ? it : it.skip` ternaries: a skip with no stated reason, which is the silence
+  `posixOnly` exists to end, in different syntax. A reason is required, as it is there.
+
+### Fixed
+- **Windows 0.19.4 release qualification** (REQ-599, merged from the Windows branch; issued there as
+  596 and renumbered here — both sessions had forked from the same base and claimed that number).
+  Raw Git blob bytes are preserved during replay despite `autocrlf` and explicit EOL attributes;
+  native project/store paths are compared canonically, including 8.3 short aliases; npm's JavaScript
+  entry is invoked through Node and the Windows prepublish Jest run is held to two workers, because
+  seven concurrent workers produced startup failures in six suites; PowerShell 5.1 recovery commands
+  are failure-aware and the SQLite plus sharp script approvals are documented. Windows fixtures were
+  repaired for filesystem permissions, branch names, paths, environment key case, npm JSON versions
+  and line endings **while keeping their negative assertions**. File identities are read as BigInt in
+  playbook skill alias detection: actual NTFS ids exceeded Number precision, so distinct ids collided
+  numerically and blocked refresh — genuine hard-link refusal is preserved.
+- **The release gate could not find npm and died looking** (REQ-600). `npmCommand` derived its
+  candidates from `process.execPath`, and Node resolves that through the symlink: Homebrew's
+  `/opt/homebrew/bin/node` becomes `/opt/homebrew/Cellar/node/<ver>/bin/node`, so `../lib` points
+  inside the Cellar while npm sits at `/opt/homebrew/lib/node_modules/npm`. It then THREW. Measured
+  when the evidence runner went red on nine assertions while the same suite was green under `npx`,
+  which sets `npm_execpath`. The search now also looks beside the node that is on PATH — the place
+  the symlink came from, which also covers nvm, fnm, volta and distribution packages — and when
+  nothing is found it degrades to the platform `npm` instead of dying. Running npm is the goal; the
+  JS entry point is only how the Windows shell is avoided, and `execFile` runs a `.cmd` without one.
+- **`doctor` called a protected global prefix writable** (REQ-584). The check asked
+  `fs.accessSync(W_OK)`, which on Windows reads POSIX mode bits and never the ACL: on a non-admin
+  account with prefix `C:\Program Files\nodejs` it answered "writable" while `mkdir` died EPERM —
+  the very error the user then met in `npm install -g`. The probe now TRIES: it creates and removes
+  a directory in the deepest existing ancestor (the same syscall npm fails on). Measured on that
+  machine: `WARN` with the user-space prefix prescription; `%APPDATA%\npm` still `PASS`. A probe
+  entry that cannot be removed is named, never hidden. POSIX verdicts are pinned unchanged.
+- **The antigravity 8.3 conversion had never fired** (REQ-586). `shortPathIfSpaced` handed cmd a
+  `for %I in ("<path>") do @echo %~sI` line through Node's default win32 quoting, which rewrites the
+  inner quotes as `\"`; cmd's `for` then answered `C:\"C:\Users\…\"` — spaced and quoted — and the
+  function fell back to the spaced path. `init --agent antigravity` on an install under
+  `C:\Users\<name with a space>\…` therefore wrote an unquoted spaced command agy's launcher can never
+  run, and printed "the gate is enforced". The line now goes to cmd verbatim
+  (`windowsVerbatimArguments`), the win32 test asserts a REAL conversion on a spaced temp path, and
+  when a space still survives (a volume without 8.3 names) init says so instead of claiming
+  enforcement. Its sibling: `doctor` then rejected the correct 8.3 wiring as "not this install",
+  because `fs.realpathSync` does not expand short names — `realpathSync.native` does, and all three
+  wiring checks that share `resolvesToPackage` now use it (A-SPEC-586.2). Measured end to end on
+  the spaced install: hook written as `HOLMES~1.JS`, hook runs, `antigravity wiring` PASS.
+- **The Windows `doctor-wiring-handshake` red had a third cause, and doctor hid it** (REQ-585).
+  Not the writer (0.19.1's note — `tomlStr` escapes correctly) and not cwd (0.19.2's hypothesis —
+  `doctor` now answers the same from `C:\` and the repo root): the test fixture wrote a Windows path
+  with raw backslashes into a TOML basic string, and the reader folded every unknown escape to its
+  bare letter, so `C:\ai_project\…` became `C:ai_project…` and doctor judged a path nobody wrote. A
+  hand-written `config.toml` does the same, and Codex refuses such a file outright. The reader now
+  accepts only the escapes TOML defines (`\b \t \n \f \r \" \\ \uXXXX \UXXXXXXXX`), an invalid one
+  makes the entry unreadable, and `codex wiring` names the escape and its line with the two valid
+  spellings. The fixture goes through `codexMcpBlock`, the same serializer init uses. The suite is
+  green on Windows for the first time.
+
+### Changed
+- **Autonomous approval now covers a low-risk slice's REQ and H-SPEC** (REQ-587). With
+  `HOLMES_AUTONOMOUS_APPROVAL` on, upstream documents were graded `hitl` by kind alone, so every
+  slice cost the operator two terminal sittings (`holmes-kit approve` for the REQ, again for the
+  H-SPEC) — six for the three fixes above. ADR-009's line is "self-approve by default, non-bypassable
+  HITL for high risk, risk decided deterministically", and a REQ or H-SPEC carries no code of its
+  own: its risk is the risk its A-SPECs declare. `specApprovalAutonomy` now takes the downstream
+  A-SPECs and derives the upstream grade — all auto → auto; any hitl (gate behaviour, a
+  governance/guardrail/hook/taint path), or no A-SPEC yet, → human. C-SPEC and ADR stay human
+  regardless. The ledger line names the A-SPECs the grade was derived from. Autonomy off is
+  byte-identical.
+- **`spec_slice_approve` is idempotent** (A-SPEC-587.2). Called again after the REQ was sealed it
+  requested a RE-SEAL of that REQ (same request id back in the queue) and stopped there, so the
+  H-SPEC was never attempted. Sealed specs are now skipped and reported under `alreadySealed`; the
+  chain resumes at the first unsealed spec.
+
+### Measured, no change needed
+- **codex hook commands on a spaced path** (the plan's prediction A/B): codex runs a command hook as
+  `%COMSPEC% /C "<command_line>"` (codex-rs `hooks/src/engine/command_runner.rs`; the 0.153.4
+  binary carries the same runner), a quote-respecting shell. The quoted `node "<path>"` form
+  succeeded 3/3 on a spaced install. `kernelCommand` is unchanged.
+- **npm 12 third-party install on Windows**: install scripts blocked → `doctor` diagnosed
+  `scripts-blocked` with the `.cmd` recovery line → pasted verbatim, the binding was built and
+  `doctor` went to 12 pass / 0 fail. Three-harness wiring from a foreign cwd: 3/3 handshakes.
+
+### Windows baseline, classified
+A clean `main` on this machine fails 49 of 416 suites in isolation — none are regressions from this
+change. Sixteen were `Cannot find module 'web-tree-sitter'` (a dependency added by a recent pull and
+not yet installed; `npm install` turns 17 of the 18 green). The rest are environment: spawn
+timeouts in doctor tests, jest-worker "circular structure" crashes (`approve`, `mcp-launcher`,
+`doctor-mcp-wiring-spawn`), `chmod`-based negatives that cannot fail on NTFS, git-history corpora,
+CRLF checkouts compared byte-for-byte, and SQLite "file is not a database" on a corrupt-store
+negative. The list with first-failure lines lives in `docs/goals/GOAL-windows-hardening-2026-09-10.md`.
+
+## [0.19.3] - 2026-09-10
+
+`doctor` told every third-party install its SQLite binding was missing while it sat on disk. No API change.
+
+### Fixed
+- **A false FAIL on the default install layout** (REQ-583). `gatherNativeEvidence` located
+  `better-sqlite3` by joining `packageRoot/node_modules/better-sqlite3`, and npm HOISTS
+  dependencies to the project root — so for a normal install at
+  `<proj>/node_modules/@holmes-lab/holmes-kit` the joined path never existed. Measured against the
+  published 0.19.2: the binding was present, `require('better-sqlite3')` executed a `:memory:`
+  query, and `doctor` still reported `no binary`. Hoisting is npm's default, which made this the
+  default experience of a correct install. The package directory is now RESOLVED
+  (`require.resolve('<name>/package.json', { paths: [root] })`) — Node's own rule, so hoisted,
+  nested and linked layouts all answer correctly, and a genuinely absent dependency still fails.
+  Its sibling — the `node version` check reading `engines.node` — carried the same join and moved
+  with it; it had been reporting `engines.node=(unknown)` for the same reason.
+- **The release gate ran the suite in the operator's environment** (REQ-582). `npm publish`
+  refused a green tree: `verify-release.js` called `npm test` with the shell's `HOLMES_APPROVAL`,
+  which the spawned-hook parity test (A-SPEC-338) legitimately reacts to — the spawned child
+  inherits the token while its in-process twin is handed `{approval: undefined}`. The gate now runs
+  under `cleanTestEnv`, the same scrub `test_run` uses (borrowed, never copied), and refuses to
+  proceed unscrubbed if it cannot load it. It also names the failing tests instead of saying only
+  "red" — finding out which test had failed previously cost two extra full-suite runs.
+
+- **A live session could block its own publish** (REQ-583). The `APPEND_ONLY_GOVERNANCE` list that
+  tells the release gate which dirty files are governance churn rather than unshipped code held
+  only the approval queue and provenance — while REQ-564/566/569/578 added `session-context`,
+  `impact-advisories`, `anchor-density` and `cycle-observations`, and `test-outcomes` was promoted
+  to tracking. Measured: `npm publish` refused because one `session-context` line was appended
+  between two `git status` snapshots inside the tree-untouched assertion, and the same list guards
+  the dirty-tree check a user meets first. The list now follows the ledgers, and a test pins that
+  nothing which ships (`src/`, `dist/`, the manifest, specs) is ever excused.
+
+### Verified against the published package
+- Installed `@holmes-lab/holmes-kit@0.19.2` from the registry into a clean project, applied this
+  fix, and re-diagnosed from an unrelated working directory: **0 FAIL**, three-harness handshakes
+  (claude / codex / antigravity) all PASS on the version-pinned npx wiring, `target wiring — 3
+  holmes hook(s) resolve to this install`, and `better-sqlite3 — loads and executes against
+  :memory:`.
+
 ## [0.19.2] - 2026-09-10
 
 Wiring diagnosis no longer depends on where you run it. No API change.

package/README.md

@@ -148,12 +148,27 @@ Out of the box Holmes-Kit runs tier **`none`** — lexical + citation + graph se
 egress**. Two opt-in tiers raise recall on requests your vocabulary can't reach (measured on 305
 traceability cases — see the feature list above):
 
-**Tier `local` — no egress, no account.** Install the optional embedding runtime next to
-holmes-kit and the local model (`bge-m3`) is picked up automatically:
+**Tier `local` — no egress, no account.** The embedding runtime ships with holmes-kit as of
+0.19.4, so nothing extra to install. Preparing the model is **opt-in**: neither installation nor
+`init` downloads it, because a large download nobody asked for is not a default. One command:
 ```bash
-npm install --save-dev @xenova/transformers
-npx holmes-kit doctor        # → semantic tier: local (no egress)
+npx holmes-kit semantic-setup    # downloads the public bge-m3 assets once, shared across projects
+npx holmes-kit semantic-check    # verifies OFFLINE inference — a real 1024-dim normalized vector
+npx holmes-kit doctor            # → semantic tier: local (no egress)
 ```
+Until it is prepared, `doctor` reports tier **`none`** and names what that costs — requests lexical
+search misses (measured 16.4%) have 0% recall — together with the command that changes it. A runtime
+that resolves is not a tier that answers.
+
+To prepare during installation instead, set `HOLMES_AUTO_MODEL_INSTALL=1` before installing.
+`HOLMES_SKIP_MODEL_INSTALL=1` refuses preparation and **outranks** the opt-in, so an explicit refusal
+is never overridden. Models live in `~/.holmes/models` (`%USERPROFILE%\.holmes\models` on Windows);
+`HOLMES_MODEL_CACHE` overrides that, including for a prepopulated offline cache.
+
+> On **ARM Linux**, install with Node 20 or 22: `tree-sitter@0.21.1` ships no `linux-arm64` prebuild,
+> so it compiles from source, and that compile fails against Node 24 headers. The failure happens
+> while npm is still installing dependencies — before Holmes-Kit exists — so `doctor` cannot diagnose
+> it. On x64 the prebuild is used and Node 24 is fine.
 
 **Tier `cloud` — highest recall, explicit consent (`gemini-embedding-001`).** Setting a key IS
 the consent act: with a key present, repository-derived text is sent to Google's embedding API.
@@ -213,6 +228,9 @@ flowchart LR
 | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
 | `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
 | `holmes-kit autonomy off` | End session autonomy immediately |
+| `holmes-kit semantic-setup` | Download and verify the local `bge-m3` model (opt-in; shared across projects) |
+| `holmes-kit semantic-check` | Verify local inference **offline**, without downloading anything |
+| `holmes-kit semantic-key set` | Store the cloud-tier key outside the tree (stdin only, never argv) |
 | `holmes-kit doctor` | Comprehensive health check of specs, hooks, MCP, and anchors |
 | `holmes-kit doctor --fix` | Automatically self-heal and repair broken hooks or missing skills |
 | `holmes-kit ci` | Run non-interactive headless governance gate for GitHub Actions / GitLab CI |

package/dist/.build-id

@@ -1 +1 @@
-e63e589-mtuemhhb
+bb0f4497-mtwbj9ia

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

@@ -62,6 +62,14 @@ export declare function antigravityHookCommand(scriptPath: string): string;
 /** win32-only, best-effort: a spaced path becomes its 8.3 short name (no spaces); anything else — or
  *  any lookup failure — returns the input unchanged. */
 export declare function shortPathIfSpaced(p: string): string;
+/**
+ * @implements A-SPEC-586
+ * The agy launcher splits its single command string on whitespace, so a hook path that still carries
+ * a space after the 8.3 attempt is a hook that never runs. One line per such hook — init prints
+ * these INSTEAD of "the gate is enforced". Empty when every path is space-free (posix without a
+ * space, or win32 where 8.3 resolved it).
+ */
+export declare function antigravityHookWarnings(packageRoot: string): string[];
 export declare const MANAGED_BEGIN = "<!-- holmes-kit:managed:begin -->";
 export declare const MANAGED_END = "<!-- holmes-kit:managed:end -->";
 /**

package/dist/holmes/cli/agents.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MANAGED_END = exports.MANAGED_BEGIN = exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
 exports.antigravityHookCommand = antigravityHookCommand;
 exports.shortPathIfSpaced = shortPathIfSpaced;
+exports.antigravityHookWarnings = antigravityHookWarnings;
 exports.mergeAgentsMd = mergeAgentsMd;
 exports.agentFiles = agentFiles;
 exports.agentLinks = agentLinks;
@@ -132,13 +133,36 @@ function shortPathIfSpaced(p) {
     if (process.platform !== 'win32' || !p.includes(' '))
         return p;
     try {
-        const out = (0, node_child_process_1.execFileSync)('cmd', ['/d', '/c', `for %I in ("${p}") do @echo %~sI`], { encoding: 'utf8' }).trim();
-        return out !== '' && !out.includes(' ') ? out : p;
+        // @implements A-SPEC-586 — VERBATIM. Node's default win32 quoting rewrites the inner `"` as `\"`
+        // (CRT rules), but cmd.exe is not a CRT program: its `for` then sees `(\"C:\…\")` and `%~sI`
+        // answers `C:\"C:\Users\…\"` — spaced and quoted, so the check below rejected it and the
+        // conversion had NEVER fired (measured 2026-09-10). Handing the line to cmd untouched yields
+        // the 8.3 form on the same path.
+        const r = (0, node_child_process_1.spawnSync)('cmd', ['/d', '/c', `for %I in ("${p}") do @echo %~sI`], { encoding: 'utf8', windowsVerbatimArguments: true });
+        const out = r.status === 0 && typeof r.stdout === 'string' ? r.stdout.trim() : '';
+        return out !== '' && !out.includes(' ') && !out.includes('"') ? out : p;
     }
     catch {
         return p;
     }
 }
+/**
+ * @implements A-SPEC-586
+ * The agy launcher splits its single command string on whitespace, so a hook path that still carries
+ * a space after the 8.3 attempt is a hook that never runs. One line per such hook — init prints
+ * these INSTEAD of "the gate is enforced". Empty when every path is space-free (posix without a
+ * space, or win32 where 8.3 resolved it).
+ */
+function antigravityHookWarnings(packageRoot) {
+    const out = [];
+    for (const script of ['holmes-hook-antigravity.js', 'holmes-stop-antigravity.js']) {
+        const final = shortPathIfSpaced(path.join(packageRoot, 'bin', script));
+        if (!/\s/.test(final))
+            continue;
+        out.push(`antigravity: the hook path still contains a space (${final.replace(/\\/g, '/')}) — agy's launcher splits the command on whitespace, so this hook never runs and the gate is NOT enforced. Install holmes-kit in a path without spaces${process.platform === 'win32' ? ' (or enable NTFS 8.3 names on this volume)' : ''}.`);
+    }
+    return out;
+}
 const antigravityHookEntry = (packageRoot, script) => ({
     type: 'command',
     command: antigravityHookCommand(shortPathIfSpaced(path.join(packageRoot, 'bin', script))),

package/dist/holmes/cli/codex-toml.d.ts

@@ -24,3 +24,13 @@ export declare function readCodexHolmesEntry(raw: string): {
     command: string;
     args: string[];
 } | null;
+/**
+ * @implements A-SPEC-585
+ * The first invalid basic-string escape inside OUR table's `command =` / `args =` lines, with its
+ * 1-based line — or null when every escape there is one TOML defines. Doctor turns this into the
+ * diagnosis Codex itself would give (it refuses the file), instead of judging a mangled path.
+ */
+export declare function invalidTomlEscape(raw: string): {
+    escape: string;
+    line: number;
+} | null;

package/dist/holmes/cli/codex-toml.js

@@ -5,6 +5,7 @@ exports.codexMcpBlock = codexMcpBlock;
 exports.mergeCodexToml = mergeCodexToml;
 exports.removeCodexToml = removeCodexToml;
 exports.readCodexHolmesEntry = readCodexHolmesEntry;
+exports.invalidTomlEscape = invalidTomlEscape;
 /** The one table holmes-kit owns in a Codex config.toml. */
 exports.CODEX_TABLE = 'mcp_servers.holmes-kit';
 const HEADER = `[${exports.CODEX_TABLE}]`;
@@ -251,24 +252,87 @@ function readCodexHolmesEntry(raw) {
         return null;
     let command = null;
     let args = null;
-    for (let i = region.start + 1; i < region.end; i++) {
-        const cmd = lines[i].match(/^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"\s*(#.*)?$/);
-        if (cmd)
-            command = unescapeToml(cmd[1]);
-        const arr = lines[i].match(/^\s*args\s*=\s*\[(.*)\]\s*(#.*)?$/);
-        if (arr)
-            args = parseTomlStringArray(arr[1]);
+    try {
+        for (let i = region.start + 1; i < region.end; i++) {
+            const cmd = lines[i].match(/^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"\s*(#.*)?$/);
+            if (cmd)
+                command = unescapeToml(cmd[1]);
+            const arr = lines[i].match(/^\s*args\s*=\s*\[(.*)\]\s*(#.*)?$/);
+            if (arr)
+                args = parseTomlStringArray(arr[1]);
+        }
+    }
+    catch (e) {
+        if (e instanceof InvalidTomlEscape)
+            return null; // @implements A-SPEC-585 — unreadable, not mangled
+        throw e;
     }
     if (command === null || args === null)
         return null;
     return { command, args };
 }
+/**
+ * @implements A-SPEC-585
+ * The first invalid basic-string escape inside OUR table's `command =` / `args =` lines, with its
+ * 1-based line — or null when every escape there is one TOML defines. Doctor turns this into the
+ * diagnosis Codex itself would give (it refuses the file), instead of judging a mangled path.
+ */
+function invalidTomlEscape(raw) {
+    const lines = raw.split('\n');
+    const region = ourRegion(lines);
+    if (!region)
+        return null;
+    for (let i = region.start + 1; i < region.end; i++) {
+        if (!/^\s*(command|args)\s*=/.test(lines[i]))
+            continue;
+        const re = /"((?:[^"\\]|\\.)*)"/g;
+        let mm;
+        while ((mm = re.exec(lines[i])) !== null) {
+            const bad = firstInvalidEscape(mm[1]);
+            if (bad !== null)
+                return { escape: bad, line: i + 1 };
+        }
+    }
+    return null;
+}
+class InvalidTomlEscape extends Error {
+    escape;
+    constructor(escape) {
+        super(`invalid TOML escape ${escape}`);
+        this.escape = escape;
+    }
+}
+const SIMPLE_ESCAPES = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+/** The offending escape (`\a`, or a `\u`/`\U` with too few hex digits), or null when all are valid. */
+function firstInvalidEscape(s) {
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] !== '\\')
+            continue;
+        const e = s[i + 1] ?? '';
+        if (e in SIMPLE_ESCAPES) {
+            i += 1;
+            continue;
+        }
+        const width = e === 'u' ? 4 : e === 'U' ? 8 : 0;
+        if (width > 0 && new RegExp(`^[0-9a-fA-F]{${width}}$`).test(s.slice(i + 2, i + 2 + width))) {
+            i += 1 + width;
+            continue;
+        }
+        return `\\${e}`;
+    }
+    return null;
+}
+// @implements A-SPEC-585 — strict: only the escapes TOML defines. Anything else THROWS, so the
+// caller answers "unreadable" — an unknown escape used to fold to its bare letter and turned
+// `C:\ai_project\…` into `C:ai_project…` (measured on every Windows checkout).
 function unescapeToml(s) {
-    return s.replace(/\\(u[0-9a-fA-F]{4}|.)/g, (_, e) => {
-        if (e[0] === 'u')
-            return String.fromCharCode(parseInt(e.slice(1), 16));
-        const map = { n: '\n', r: '\r', t: '\t', '"': '"', '\\': '\\' };
-        return map[e] ?? e;
+    const bad = firstInvalidEscape(s);
+    if (bad !== null)
+        throw new InvalidTomlEscape(bad);
+    return s.replace(/\\(U[0-9a-fA-F]{8}|u[0-9a-fA-F]{4}|.)/g, (_, e) => {
+        if (e[0] === 'u' || e[0] === 'U')
+            return String.fromCodePoint(parseInt(e.slice(1), 16));
+        return SIMPLE_ESCAPES[e];
     });
 }
 /** Parse a TOML inline array of basic strings: `"a", "b"` → ['a','b']. Non-conforming → []. */

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

@@ -1,5 +1,9 @@
 import { NativeEvidence } from './native-deps';
 import { type SemanticTier } from '../semantic/tier';
+/**
+ * Checks if a script path belongs to the packageRoot, supporting symlinked global installs.
+ */
+export declare function resolvesToPackage(filePath: string, packageRoot: string): boolean;
 /**
  * `holmes-kit doctor` — install diagnostics.
  *
@@ -62,7 +66,22 @@ export interface PrefixProbe {
     writable?: boolean;
     platform?: string;
     unreadable?: string;
+    /** @implements A-SPEC-584 — a probe entry the caller created but could not remove. */
+    leftover?: string;
 }
+/**
+ * @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.
+ */
+export declare function probeWritable(dir: string): {
+    writable: boolean;
+    leftover?: string;
+};
 /**
  * Judge the global prefix. Pure — the probing lives with the caller.
  *
@@ -104,6 +123,21 @@ export declare function grammarProbe(packageRoot: string): {
  * 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`.
  */
+/**
+ * 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.
+ */
+export declare function resolveDepDir(fromRoot: string, name: string): string | null;
 export declare function gatherNativeEvidence(packageRoot: string): NativeEvidence;
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;