@holmes-lab/holmes-kit 0.19.2 → 0.19.4

package/dist/holmes/project/install-scripts-policy.d.ts

@@ -12,8 +12,22 @@
  * This module is the pure re-statement of that rule: no I/O, no process, no platform — the same
  * verdict on every OS, shared by the test that pins package.json and by doctor (A-SPEC-580).
  */
-/** Dependencies whose install script must actually RUN for the module to load. */
-export declare const NATIVE_INSTALL_SCRIPT_DEPS: readonly ["better-sqlite3"];
+/**
+ * Dependencies whose install script must actually RUN for the module to load.
+ *
+ * A-SPEC-595, measured 2026-09-10: `sharp@0.32.6` belongs here on EVERY platform, not just the
+ * Windows machine that first hit it. `npm pack sharp@0.32.6` yields a tarball with zero entries
+ * matching `.node`, `prebuilds/` or `vendor/`; its declared hook is
+ * `(node install/libvips && node install/dll-copy && prebuild-install) || (node install/can-compile
+ * && node-gyp rebuild && node install/dll-copy)`; the lockfile records `hasInstallScript: true`;
+ * and this repository's macOS tree holds `build/Release/sharp-darwin-arm64v8.node` and
+ * `vendor/8.14.5` only because that script ran. (sharp 0.33+ moved to platform packages that DO
+ * ship prebuilds — a version bump makes this entry a re-measurement, not a given.)
+ *
+ * This list is what doctor reads, and `allowScripts` is a root-manifest policy that does not
+ * transfer to consumers — so a name missing here is a name no consumer is ever told to approve.
+ */
+export declare const NATIVE_INSTALL_SCRIPT_DEPS: readonly ["better-sqlite3", "sharp"];
 /** Native dependencies that ship prebuilds and load with the script blocked (measured). */
 export declare const PREBUILT_NATIVE_DEPS: readonly ["tree-sitter", "tree-sitter-typescript", "tree-sitter-python", "tree-sitter-c-sharp", "tree-sitter-java", "tree-sitter-go", "tree-sitter-rust", "tree-sitter-cpp"];
 export type AllowScripts = Record<string, boolean>;

package/dist/holmes/project/install-scripts-policy.js

@@ -20,8 +20,22 @@ exports.policyVerdict = policyVerdict;
  * This module is the pure re-statement of that rule: no I/O, no process, no platform — the same
  * verdict on every OS, shared by the test that pins package.json and by doctor (A-SPEC-580).
  */
-/** Dependencies whose install script must actually RUN for the module to load. */
-exports.NATIVE_INSTALL_SCRIPT_DEPS = ['better-sqlite3'];
+/**
+ * Dependencies whose install script must actually RUN for the module to load.
+ *
+ * A-SPEC-595, measured 2026-09-10: `sharp@0.32.6` belongs here on EVERY platform, not just the
+ * Windows machine that first hit it. `npm pack sharp@0.32.6` yields a tarball with zero entries
+ * matching `.node`, `prebuilds/` or `vendor/`; its declared hook is
+ * `(node install/libvips && node install/dll-copy && prebuild-install) || (node install/can-compile
+ * && node-gyp rebuild && node install/dll-copy)`; the lockfile records `hasInstallScript: true`;
+ * and this repository's macOS tree holds `build/Release/sharp-darwin-arm64v8.node` and
+ * `vendor/8.14.5` only because that script ran. (sharp 0.33+ moved to platform packages that DO
+ * ship prebuilds — a version bump makes this entry a re-measurement, not a given.)
+ *
+ * This list is what doctor reads, and `allowScripts` is a root-manifest policy that does not
+ * transfer to consumers — so a name missing here is a name no consumer is ever told to approve.
+ */
+exports.NATIVE_INSTALL_SCRIPT_DEPS = ['better-sqlite3', 'sharp'];
 /** Native dependencies that ship prebuilds and load with the script blocked (measured). */
 exports.PREBUILT_NATIVE_DEPS = [
     'tree-sitter', 'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp',

package/dist/holmes/review/point-in-time-replay.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.materializeTreeAt = materializeTreeAt;
 exports.verifyTreeFidelity = verifyTreeFidelity;
+// @implements A-SPEC-599
 // @implements A-SPEC-297
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
@@ -56,12 +57,14 @@ function git(repoRoot, args) {
 }
 /** `path mode sha` triples the commit records for the pathspec, keyed by repo-relative path. */
 function blobsAt(repoRoot, commitish, pathspec) {
-    const out = git(repoRoot, ['ls-tree', '-r', `${commitish}^{tree}`, '--', pathspec]);
+    const out = git(repoRoot, ['ls-tree', '-rz', `${commitish}^{tree}`, '--', pathspec]);
     const blobs = new Map();
-    for (const line of out.split('\n')) {
+    for (const line of out.split('\0')) {
         if (line.trim() === '')
             continue;
-        const [meta, file] = line.split('\t');
+        const tab = line.indexOf('\t');
+        const meta = line.slice(0, tab);
+        const file = line.slice(tab + 1);
         const parts = meta.split(/\s+/);
         if (parts[1] !== 'blob')
             continue; // submodules and trees are not files we can compare
@@ -119,6 +122,43 @@ function materializeTreeAt(repoRoot, commitish, pathspec, destDir, opts) {
         const tar = (0, node_child_process_1.execFileSync)('git', ['-C', repoRoot, 'archive', '--format=tar', commitish, '--', pathspec], { maxBuffer: 512 * 1024 * 1024 });
         fs.writeFileSync(tarPath, tar);
         (0, node_child_process_1.execFileSync)('tar', ['-x', '-C', destDir, '-f', tarPath], { maxBuffer: 512 * 1024 * 1024 });
+        // Archive preserves modes/layout, but applies EOL/export substitutions. Read raw objects in
+        // one batch so fidelity is independent of user config and committed attributes alike.
+        const refsPath = path.join(path.dirname(tarPath), 'objects.txt');
+        fs.writeFileSync(refsPath, [...blobs.values()].join('\n') + '\n');
+        const refs = fs.openSync(refsPath, 'r');
+        let raw;
+        try {
+            raw = (0, node_child_process_1.execFileSync)('git', ['-C', repoRoot, 'cat-file', '--batch'], {
+                stdio: [refs, 'pipe', 'pipe'], maxBuffer: 512 * 1024 * 1024,
+            });
+        }
+        finally {
+            fs.closeSync(refs);
+        }
+        let offset = 0;
+        for (const [file, sha] of blobs) {
+            const end = raw.indexOf(10, offset);
+            const header = raw.subarray(offset, end).toString('ascii').split(' ');
+            const size = Number(header[2]);
+            if (end < offset || header[0] !== sha || header[1] !== 'blob' || !Number.isSafeInteger(size)
+                || size < 0 || end + 1 + size >= raw.length)
+                throw new Error('invalid cat-file response');
+            const bytes = raw.subarray(end + 1, end + 1 + size);
+            offset = end + 1 + size + 1;
+            const target = path.join(destDir, file);
+            // Keep archive's symlink representation; never follow it to overwrite a target.
+            try {
+                if (fs.lstatSync(target).isSymbolicLink())
+                    continue;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, bytes);
+        }
     }
     catch (err) {
         return { ok: false, reason: `archive-or-extract-failed: could not materialize ${commitish}: ${err.message}` };

package/dist/holmes/rtm/graph-store.d.ts

@@ -27,6 +27,8 @@ export interface GraphBasis {
      */
     scanDigest: string;
 }
+/** Deterministic content fingerprint for every spec field consumed by buildRtm. */
+export declare function specFingerprint(specs: readonly unknown[]): string;
 /**
  * Content address of a scan: every file's path and its symbols/edges, sorted so the digest depends
  * on the scan's CONTENT and not on the order the scanner happened to walk the tree in.

package/dist/holmes/rtm/graph-store.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.specFingerprint = specFingerprint;
 exports.scanDigest = scanDigest;
 exports.openReusableGraph = openReusableGraph;
 // @implements A-SPEC-282
@@ -43,6 +44,19 @@ const rtm_graph_1 = require("./rtm-graph");
 const BASIS_FIELDS = [
     'graphSchema', 'extractorVersion', 'sourceCommit', 'specFingerprint', 'scanDigest',
 ];
+/** Deterministic content fingerprint for every spec field consumed by buildRtm. */
+function specFingerprint(specs) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value !== null && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value)
+                .sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, canonical(v)]));
+        }
+        return value;
+    };
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(JSON.stringify(specs.map(canonical))).digest('hex')}`;
+}
 /**
  * Content address of a scan: every file's path and its symbols/edges, sorted so the digest depends
  * on the scan's CONTENT and not on the order the scanner happened to walk the tree in.

package/dist/holmes/rtm/rtm-graph.js

@@ -66,16 +66,17 @@ class RtmGraph {
     // full rebuild.
     constructor(dbPath = ':memory:') {
         this.db = new better_sqlite3_1.default(dbPath);
-        // @implements A-SPEC-283
-        // Only a FILE-backed store can be contended. Several MCP servers can be live at once, and the
-        // hook and the CLI can touch the same project, so a reader must not be blocked by a writer and a
-        // busy file must be waited on rather than thrown at. `:memory:` is private to this process and
-        // cannot use WAL at all — setting it there would be a pragma that cannot apply.
-        if (dbPath !== ':memory:') {
-            this.db.pragma('journal_mode = WAL');
-            this.db.pragma('busy_timeout = 5000');
-        }
-        this.db.exec(`CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, kind TEXT NOT NULL, source_path TEXT, summary TEXT);
+        try {
+            // @implements A-SPEC-283
+            // Only a FILE-backed store can be contended. Several MCP servers can be live at once, and the
+            // hook and the CLI can touch the same project, so a reader must not be blocked by a writer and a
+            // busy file must be waited on rather than thrown at. `:memory:` is private to this process and
+            // cannot use WAL at all — setting it there would be a pragma that cannot apply.
+            if (dbPath !== ':memory:') {
+                this.db.pragma('journal_mode = WAL');
+                this.db.pragma('busy_timeout = 5000');
+            }
+            this.db.exec(`CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, kind TEXT NOT NULL, source_path TEXT, summary TEXT);
       CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, rel TEXT NOT NULL, source_path TEXT, PRIMARY KEY (src,dst,rel));
       -- The PK covers src-prefixed lookups; nothing covered dst or source_path, so every reverse
       -- traversal and every removeBySource was a full table scan. Measured on a 240k-node graph:
@@ -86,28 +87,39 @@ class RtmGraph {
       CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst);
       CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_path);
       CREATE INDEX IF NOT EXISTS idx_nodes_source ON nodes(source_path);`);
-        // @implements A-SPEC-281
-        // `CREATE TABLE IF NOT EXISTS` leaves an EXISTING database on its old schema, so a store written
-        // before provenance existed would silently reject every new insert. Add the missing columns in
-        // place; existing rows keep their data and simply report null provenance, which is the honest
-        // record for a fact nobody annotated.
-        // @implements A-SPEC-282 — a small key/value side table so a persisted graph can carry the basis
-        // it was built on. Kept out of `nodes`/`edges` because it describes the WHOLE graph, not a fact.
-        this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
-        for (const table of ['nodes', 'edges']) {
-            const present = new Set(this.db.prepare(`PRAGMA table_info(${table})`).all()
-                .map((c) => c.name));
-            for (const column of PROVENANCE_COLUMNS) {
-                if (present.has(column))
-                    continue;
-                const type = column === 'confidence' ? 'REAL' : 'TEXT';
-                this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+            // @implements A-SPEC-281
+            // `CREATE TABLE IF NOT EXISTS` leaves an EXISTING database on its old schema, so a store written
+            // before provenance existed would silently reject every new insert. Add the missing columns in
+            // place; existing rows keep their data and simply report null provenance, which is the honest
+            // record for a fact nobody annotated.
+            // @implements A-SPEC-282 — a small key/value side table so a persisted graph can carry the basis
+            // it was built on. Kept out of `nodes`/`edges` because it describes the WHOLE graph, not a fact.
+            this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+            for (const table of ['nodes', 'edges']) {
+                const present = new Set(this.db.prepare(`PRAGMA table_info(${table})`).all()
+                    .map((c) => c.name));
+                for (const column of PROVENANCE_COLUMNS) {
+                    if (present.has(column))
+                        continue;
+                    const type = column === 'confidence' ? 'REAL' : 'TEXT';
+                    this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+                }
+                // @implements A-SPEC-568.1 — same in-place migration rule as provenance: an rtm-graph/2 file
+                // must keep OPENING (openReusableGraph decides reuse; an unreadable file would look corrupt).
+                if (table === 'nodes' && !present.has('summary')) {
+                    this.db.exec('ALTER TABLE nodes ADD COLUMN summary TEXT');
+                }
             }
-            // @implements A-SPEC-568.1 — same in-place migration rule as provenance: an rtm-graph/2 file
-            // must keep OPENING (openReusableGraph decides reuse; an unreadable file would look corrupt).
-            if (table === 'nodes' && !present.has('summary')) {
-                this.db.exec('ALTER TABLE nodes ADD COLUMN summary TEXT');
+        }
+        catch (error) {
+            // A corrupt file can fail during pragma/schema setup after better-sqlite3 has opened it.
+            // Release that native handle before propagating the original error so the caller can replace
+            // the file on Windows instead of receiving a second EPERM/SQLITE_NOTADB failure (A-SPEC-588).
+            try {
+                this.db.close();
             }
+            catch { /* preserve the initialization error */ }
+            throw error;
         }
     }
     // @implements A-SPEC-139

package/dist/holmes/semantic/credentials.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSemanticKey = resolveSemanticKey;
 exports.storeSemanticKey = storeSemanticKey;
 exports.removeSemanticKey = removeSemanticKey;
+// @implements A-SPEC-592
 // @implements A-SPEC-477
 /**
  * The cloud tier's credential: WHERE the consent lives, and in what order it is looked up.
@@ -49,9 +50,9 @@ exports.removeSemanticKey = removeSemanticKey;
  * Resolution chain, the order being the contract:
  *   1. HOLMES_SEMANTIC_API_KEY  — dedicated name, CI/headless.
  *   2. GEMINI_API_KEY           — ecosystem-compatible name.
- *   3. macOS keychain           — `security` via injected exec (absent elsewhere; win32 is a
- *                                 recorded Windows-agent follow-up).
- *   4. ~/.holmes/credentials.json — 0600 under 0700, the everywhere-fallback.
+ *   3. macOS keychain           — `security` via injected exec (absent elsewhere).
+ *   4. ~/.holmes/credentials.json — POSIX0600 under0700, or protected current-user-only
+ *                                 Windows DACLs, the everywhere-fallback.
  *
  * The VALUE never appears in argv (ps/history surfaces), logs, reports, or error messages.
  * Keychain writes feed the secret over STDIN (`security -i`) for the same reason.
@@ -60,11 +61,59 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
 const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
 const SERVICE = 'holmes-kit';
 const ACCOUNT = 'semantic';
 const defaultExec = (cmd, args, stdin) => (0, node_child_process_1.execFileSync)(cmd, args, { encoding: 'utf8', input: stdin, stdio: ['pipe', 'pipe', 'pipe'] });
 const credFile = (home) => path.join(home, '.holmes', 'credentials.json');
 const nonBlank = (v) => typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
+// Fixed command: its stdin contains only encoded paths, never credential content. Fresh security
+// descriptors discard both inherited and explicit broad grants; chmod cannot do that on Windows.
+const PRIVATE_WINDOWS_ACL = `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$targets = ConvertFrom-Json ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([Console]::In.ReadToEnd())))
+$sid = [Security.Principal.WindowsIdentity]::GetCurrent().User
+foreach ($target in $targets) {
+  $item = Get-Item -LiteralPath $target.path -Force
+  if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Credential path is a reparse point' }
+  if ($target.directory) {
+    $acl = [Security.AccessControl.DirectorySecurity]::new()
+    $rule = [Security.AccessControl.FileSystemAccessRule]::new($sid, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
+  } else {
+    $acl = [Security.AccessControl.FileSecurity]::new()
+    $rule = [Security.AccessControl.FileSystemAccessRule]::new($sid, 'FullControl', 'Allow')
+  }
+  $acl.SetAccessRuleProtection($true, $false)
+  $acl.AddAccessRule($rule)
+  # Persist only the DACL. Set-Acl can request SACL privileges during a repeated protected update.
+  if ($target.directory) { [IO.Directory]::SetAccessControl($target.path, $acl) }
+  else { [IO.File]::SetAccessControl($target.path, $acl) }
+  $actual = Get-Acl -LiteralPath $target.path
+  $rules = @($actual.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier]))
+  if (-not $actual.AreAccessRulesProtected -or $rules.Count -ne 1 -or
+      $rules[0].IdentityReference.Value -ne $sid.Value -or $rules[0].IsInherited -or
+      $rules[0].AccessControlType -ne 'Allow' -or
+      $rules[0].FileSystemRights -ne [Security.AccessControl.FileSystemRights]::FullControl) {
+    throw 'Credential ACL verification failed'
+  }
+}
+`;
+function protectWindowsPaths(targets) {
+    try {
+        (0, node_child_process_1.execFileSync)('powershell.exe', [
+            '-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand',
+            Buffer.from(PRIVATE_WINDOWS_ACL, 'utf16le').toString('base64'),
+        ], {
+            input: Buffer.from(JSON.stringify(targets), 'utf8').toString('base64'),
+            encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, timeout: 15000,
+        });
+    }
+    catch {
+        // Native errors may carry command output. Keep the public error stable and free of values.
+        throw new Error('Unable to protect semantic credentials with a private Windows ACL; the new key was not stored.');
+    }
+}
 function resolveSemanticKey(opts = {}) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? os.homedir();
@@ -109,12 +158,40 @@ function storeSemanticKey(key, opts = {}) {
         catch { /* fall through to the file */ }
     }
     const file = credFile(home);
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    fs.chmodSync(path.dirname(file), 0o700);
-    const tmp = file + '.tmp';
-    fs.writeFileSync(tmp, JSON.stringify({ semantic: { provider: 'gemini', key } }), { mode: 0o600 });
-    fs.renameSync(tmp, file);
-    fs.chmodSync(file, 0o600);
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    // opts.platform selects a credential source in tests. Permissions must follow the actual host.
+    if (process.platform === 'win32') {
+        protectWindowsPaths([
+            { path: directory, directory: true },
+            ...(fs.existsSync(file) ? [{ path: file, directory: false }] : []),
+        ]);
+    }
+    else {
+        fs.chmodSync(directory, 0o700);
+    }
+    const tmp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    let fd;
+    let created = false;
+    try {
+        fd = fs.openSync(tmp, 'wx', 0o600);
+        created = true;
+        if (process.platform === 'win32')
+            protectWindowsPaths([{ path: tmp, directory: false }]);
+        else
+            fs.fchmodSync(fd, 0o600);
+        // The empty file is private before the first secret byte, and the descriptor stays owned.
+        fs.writeFileSync(fd, JSON.stringify({ semantic: { provider: 'gemini', key } }));
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.renameSync(tmp, file);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+        if (created)
+            fs.rmSync(tmp, { force: true });
+    }
     return 'file';
 }
 function removeSemanticKey(opts = {}) {

package/dist/holmes/semantic/embedder.js

@@ -1,39 +1,7 @@
 "use strict";
-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.makeTierEmbedder = makeTierEmbedder;
+// @implements A-SPEC-591
 // @implements A-SPEC-478
 /**
  * The tier adapters — the productized form of exactly what the measurement scripts proved:
@@ -54,6 +22,7 @@ exports.makeTierEmbedder = makeTierEmbedder;
  */
 const tier_1 = require("./tier");
 const credentials_1 = require("./credentials");
+const local_model_1 = require("./local-model");
 const CLOUD_BATCH = 25;
 const CLOUD_BACKOFF_MS = 30_000;
 function makeTierEmbedder(tier, cache, opts = {}) {
@@ -61,15 +30,11 @@ function makeTierEmbedder(tier, cache, opts = {}) {
         return null;
     const model = tier.model;
     if (tier.tier === 'local') {
-        const tag = `${model}@q8-${(0, tier_1.POOLING_OF)(model)}`;
+        const tag = `${model}@${local_model_1.LOCAL_REVISION}-q8-${(0, tier_1.POOLING_OF)(model)}`;
         let pipe = null;
         const load = () => {
             if (pipe === null) {
-                pipe = (opts.pipelineLoader ?? (async (m) => {
-                    const specifier = '@xenova/transformers';
-                    const mod = await Promise.resolve(`${specifier}`).then(s => __importStar(require(s)));
-                    return mod.pipeline('feature-extraction', m, { quantized: true });
-                }))(model);
+                pipe = (opts.pipelineLoader ?? local_model_1.loadLocalPipeline)(model);
             }
             return pipe;
         };
@@ -79,6 +44,8 @@ function makeTierEmbedder(tier, cache, opts = {}) {
                 return Array.from((await p(text, { pooling: (0, tier_1.POOLING_OF)(model), normalize: true })).data);
             }
             catch {
+                pipe = null;
+                (opts.log ?? ((line) => process.stderr.write(`${line}\n`)))('Local embedding unavailable. Run holmes-kit semantic-setup, then holmes-kit semantic-check.');
                 return null;
             }
         };

package/dist/holmes/semantic/local-model.d.ts

@@ -0,0 +1,30 @@
+import { spawnSync } from 'node:child_process';
+import { modelCacheDir, modelCacheReady } from './model-cache';
+export { modelCacheDir, modelCacheReady };
+export declare const LOCAL_REVISION = "4de13258303883538bd53b696b452bf8099f0858";
+type Pipeline = (text: string, options: {
+    pooling: string;
+    normalize: boolean;
+}) => Promise<{
+    data: Float32Array;
+}>;
+interface Runtime {
+    pipeline(task: string, model: string, options: Record<string, unknown>): Promise<Pipeline>;
+}
+export declare function loadLocalPipeline(model?: string, options?: {
+    download?: boolean;
+    importer?: () => Promise<Runtime>;
+    cacheDir?: string;
+}): Promise<Pipeline>;
+export declare function verifyLocalModel(options?: Parameters<typeof loadLocalPipeline>[1]): Promise<{
+    ready: boolean;
+    dimension?: number;
+    message: string;
+}>;
+/** Isolate setup from the MCP and bound slow downloads/inference; all platforms share this path. */
+export declare function runModelSetup(options?: {
+    automatic?: boolean;
+    offline?: boolean;
+    env?: NodeJS.ProcessEnv;
+    spawn?: typeof spawnSync;
+}): number;

package/dist/holmes/semantic/local-model.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_REVISION = exports.modelCacheReady = exports.modelCacheDir = void 0;
+exports.loadLocalPipeline = loadLocalPipeline;
+exports.verifyLocalModel = verifyLocalModel;
+exports.runModelSetup = runModelSetup;
+// @implements A-SPEC-591
+const node_child_process_1 = require("node:child_process");
+const tier_1 = require("./tier");
+const model_cache_1 = require("./model-cache");
+Object.defineProperty(exports, "modelCacheDir", { enumerable: true, get: function () { return model_cache_1.modelCacheDir; } });
+Object.defineProperty(exports, "modelCacheReady", { enumerable: true, get: function () { return model_cache_1.modelCacheReady; } });
+exports.LOCAL_REVISION = '4de13258303883538bd53b696b452bf8099f0858';
+// TypeScript's CommonJS transform rewrites import() into require(), which cannot load this ESM
+// dependency on supported Node 20 versions. Preserve native dynamic import without shell code.
+const importRuntime = new Function('return import("@xenova/transformers")');
+const pipelines = new WeakMap();
+async function loadLocalPipeline(model = tier_1.LOCAL_MODEL, options = {}) {
+    const importer = options.importer ?? importRuntime;
+    const cacheDir = options.cacheDir ?? (0, model_cache_1.modelCacheDir)();
+    const key = JSON.stringify([model, cacheDir, !!options.download]);
+    let cache = pipelines.get(importer);
+    if (!cache) {
+        cache = new Map();
+        pipelines.set(importer, cache);
+    }
+    const existing = cache.get(key);
+    if (existing)
+        return existing;
+    const pending = importer().then(runtime => runtime.pipeline('feature-extraction', model, {
+        quantized: true,
+        revision: model === tier_1.LOCAL_MODEL ? exports.LOCAL_REVISION : 'main',
+        cache_dir: cacheDir,
+        local_files_only: !options.download,
+    })).catch(error => { cache.delete(key); throw error; });
+    cache.set(key, pending);
+    return pending;
+}
+async function verifyLocalModel(options = {}) {
+    try {
+        const pipe = await loadLocalPipeline(tier_1.LOCAL_MODEL, options);
+        // Fixed public probe: no repository data is involved in setup.
+        const { data } = await pipe('Holmes-Kit local model verification', { pooling: (0, tier_1.POOLING_OF)(tier_1.LOCAL_MODEL), normalize: true });
+        const norm = Math.hypot(...data);
+        if (data.length !== 1024 || !Array.from(data).every(Number.isFinite) || Math.abs(norm - 1) > 0.001) {
+            return { ready: false, dimension: data.length, message: 'BGE-M3 produced an invalid embedding. Select a clean HOLMES_MODEL_CACHE and run holmes-kit semantic-setup.' };
+        }
+        return { ready: true, dimension: data.length, message: 'BGE-M3 ready: verified 1024-dimensional normalized local embedding.' };
+    }
+    catch (error) {
+        const sharp = String(error instanceof Error ? error.message : '').includes('sharp');
+        return { ready: false, message: sharp
+                ? 'BGE-M3 runtime unavailable: sharp native installation failed. Review npm install-scripts ls and approve the sharp version, rebuild it, then run holmes-kit semantic-setup.'
+                : 'BGE-M3 unavailable: runtime/model load failed. Check network access during setup and cache permissions, then run holmes-kit semantic-setup; use semantic-check to verify offline.' };
+    }
+}
+/** Isolate setup from the MCP and bound slow downloads/inference; all platforms share this path. */
+function runModelSetup(options = {}) {
+    const env = options.env ?? process.env;
+    // @implements A-SPEC-594 — the automatic path does not start a large download the user did not
+    // ask for. An explicit refusal outranks an opt-in: someone who set SKIP meant it, and reading
+    // AUTO as permission to override that would silently reverse their decision. The two skips say
+    // DIFFERENT things, because telling a user "you opted out" when they never did is a lie.
+    if (options.automatic) {
+        if (env.HOLMES_SKIP_MODEL_INSTALL === '1') {
+            process.stderr.write('BGE-M3 automatic setup skipped (HOLMES_SKIP_MODEL_INSTALL=1). Run holmes-kit semantic-setup when ready.\n');
+            return 0;
+        }
+        if (env.HOLMES_AUTO_MODEL_INSTALL !== '1') {
+            process.stderr.write('BGE-M3 is not prepared automatically. Run `holmes-kit semantic-setup` to download the public model once (shared across projects), or set HOLMES_AUTO_MODEL_INSTALL=1 to prepare it during installation. Graph features work without it.\n');
+            return 0;
+        }
+    }
+    process.stderr.write(options.offline ? 'Checking BGE-M3 offline...\n' : 'Preparing BGE-M3 (public model download on first installation)...\n');
+    const result = (options.spawn ?? node_child_process_1.spawnSync)(process.execPath, [__filename, '--worker', ...(options.offline ? ['--offline'] : [])], { env, stdio: 'inherit', timeout: 900_000, windowsHide: true });
+    if (result.error || result.status !== 0) {
+        process.stderr.write('BGE-M3 setup/check failed or timed out. Graph features remain available; run holmes-kit semantic-setup to retry.\n');
+        return options.automatic ? 0 : 1;
+    }
+    return 0;
+}
+if (require.main === module) {
+    if (process.argv.includes('--worker')) {
+        verifyLocalModel({ download: !process.argv.includes('--offline') }).then(result => {
+            process[result.ready ? 'stdout' : 'stderr'].write(`${result.message}\n`);
+            process.exitCode = result.ready ? 0 : 1;
+        }).catch(() => { process.stderr.write('BGE-M3 verification failed. Run holmes-kit semantic-setup.\n'); process.exitCode = 1; });
+    }
+    else {
+        process.exitCode = runModelSetup({ automatic: process.argv.includes('--automatic'), offline: process.argv.includes('--offline') });
+    }
+}

package/dist/holmes/semantic/model-cache.d.ts

@@ -0,0 +1,8 @@
+export declare function modelCacheDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * Ready means the cache holds SOMETHING. An interrupted download leaves the directory created
+ * and empty, and reading that as ready is the whole failure mode this predicate exists to stop.
+ * Proof of a working model is `semantic-check`'s actual inference — deliberately not here, because
+ * doctor calls this on every run and must stay cheap and offline.
+ */
+export declare function modelCacheReady(cacheDir?: string): boolean;