@holmes-lab/holmes-kit 0.41.1 → 0.41.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +29 -5
  3. package/bin/holmes-mcp.js +36 -1
  4. package/dist/.build-id +1 -1
  5. package/dist/holmes/cli/claude-switches.d.ts +9 -0
  6. package/dist/holmes/cli/claude-switches.js +11 -8
  7. package/dist/holmes/cli/doctor.d.ts +7 -1
  8. package/dist/holmes/cli/doctor.js +63 -20
  9. package/dist/holmes/cli/holmes-hook-id.d.ts +9 -0
  10. package/dist/holmes/cli/holmes-hook-id.js +22 -0
  11. package/dist/holmes/cli/hook-failure-posture.d.ts +44 -0
  12. package/dist/holmes/cli/hook-failure-posture.js +65 -0
  13. package/dist/holmes/cli/index.js +3 -1
  14. package/dist/holmes/cli/init.d.ts +6 -0
  15. package/dist/holmes/cli/init.js +151 -3
  16. package/dist/holmes/cli/native-deps.d.ts +10 -4
  17. package/dist/holmes/cli/native-deps.js +30 -29
  18. package/dist/holmes/cli/release-history.d.ts +21 -0
  19. package/dist/holmes/cli/release-history.js +116 -0
  20. package/dist/holmes/cli/run-wiring.js +4 -2
  21. package/dist/holmes/cli/runtime-binding.d.ts +24 -0
  22. package/dist/holmes/cli/runtime-binding.js +67 -25
  23. package/dist/holmes/cli/settings-merge.d.ts +3 -2
  24. package/dist/holmes/cli/settings-merge.js +11 -9
  25. package/dist/holmes/config/config.d.ts +6 -0
  26. package/dist/holmes/config/config.js +23 -3
  27. package/dist/holmes/config/judgement-keys.d.ts +20 -0
  28. package/dist/holmes/config/judgement-keys.js +100 -0
  29. package/dist/holmes/config/project-caps.js +3 -2
  30. package/dist/holmes/governance/autonomous-shell.js +1 -1
  31. package/dist/holmes/governance/autonomy.d.ts +27 -1
  32. package/dist/holmes/governance/autonomy.js +126 -6
  33. package/dist/holmes/governance/wiring-receipt.d.ts +7 -0
  34. package/dist/holmes/governance/wiring-receipt.js +84 -0
  35. package/dist/holmes/guardrail/cli-root.d.ts +31 -0
  36. package/dist/holmes/guardrail/cli-root.js +261 -0
  37. package/dist/holmes/guardrail/command-traits.d.ts +2 -0
  38. package/dist/holmes/guardrail/command-traits.js +26 -1
  39. package/dist/holmes/guardrail/impact-gate.d.ts +17 -1
  40. package/dist/holmes/guardrail/impact-gate.js +44 -5
  41. package/dist/holmes/guardrail/outward-acts.js +10 -3
  42. package/dist/holmes/guardrail/package-manager-acts.d.ts +41 -0
  43. package/dist/holmes/guardrail/package-manager-acts.js +1298 -0
  44. package/dist/holmes/guardrail/refusal-codes.js +9 -1
  45. package/dist/holmes/guardrail/shell-syntax.d.ts +3 -0
  46. package/dist/holmes/guardrail/shell-syntax.js +7 -2
  47. package/dist/holmes/guardrail/write-target.d.ts +20 -0
  48. package/dist/holmes/guardrail/write-target.js +168 -2
  49. package/dist/holmes/hooks/pre-tool-use.d.ts +110 -3
  50. package/dist/holmes/hooks/pre-tool-use.js +1208 -60
  51. package/dist/holmes/mcp/evidence-artifact.d.ts +112 -0
  52. package/dist/holmes/mcp/evidence-artifact.js +2 -0
  53. package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +2 -1
  54. package/dist/holmes/mcp/handlers/maintenance-evidence.js +24 -2
  55. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +1 -1
  56. package/dist/holmes/mcp/handlers/operator-inspection.js +2 -2
  57. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +1 -1
  58. package/dist/holmes/mcp/handlers/requirement-triage.js +3 -2
  59. package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
  60. package/dist/holmes/mcp/handlers/spec-approval.js +6 -6
  61. package/dist/holmes/mcp/handlers/test-execution.d.ts +8 -0
  62. package/dist/holmes/mcp/handlers/test-execution.js +12 -6
  63. package/dist/holmes/mcp/handlers.d.ts +16 -7
  64. package/dist/holmes/mcp/maintenance-evidence.d.ts +11 -82
  65. package/dist/holmes/mcp/maintenance-evidence.js +57 -2
  66. package/dist/holmes/mcp/outcome-replay.d.ts +18 -0
  67. package/dist/holmes/mcp/outcome-replay.js +85 -0
  68. package/dist/holmes/mcp/outcome-windows.d.ts +136 -0
  69. package/dist/holmes/mcp/outcome-windows.js +236 -0
  70. package/dist/holmes/mcp/tool-schemas.js +1 -1
  71. package/dist/holmes/project/hook-specs-arg.d.ts +4 -0
  72. package/dist/holmes/project/hook-specs-arg.js +39 -0
  73. package/dist/holmes/project/install-layout.d.ts +11 -0
  74. package/dist/holmes/project/install-layout.js +109 -0
  75. package/dist/holmes/project/install-scripts-policy.d.ts +4 -1
  76. package/dist/holmes/project/install-scripts-policy.js +6 -3
  77. package/dist/holmes/project/native-recovery.d.ts +29 -0
  78. package/dist/holmes/project/native-recovery.js +62 -0
  79. package/dist/holmes/project/root.d.ts +6 -0
  80. package/dist/holmes/project/root.js +15 -3
  81. package/dist/holmes/project/wiring-receipt-format.d.ts +20 -0
  82. package/dist/holmes/project/wiring-receipt-format.js +42 -0
  83. package/dist/holmes/project/workspace-preflight.d.ts +9 -0
  84. package/dist/holmes/project/workspace-preflight.js +40 -1
  85. package/dist/holmes/review/classification-replay.d.ts +53 -0
  86. package/dist/holmes/review/classification-replay.js +78 -0
  87. package/dist/holmes/review/head-worktree.js +5 -4
  88. package/dist/holmes/review/run-provenance.js +3 -2
  89. package/dist/holmes/review/test-evidence.js +2 -2
  90. package/dist/holmes/review/test-outcomes.js +3 -1
  91. package/dist/holmes/rtm/graph-store.d.ts +5 -0
  92. package/dist/holmes/rtm/graph-store.js +12 -4
  93. package/dist/holmes/rtm/native-driver.d.ts +42 -0
  94. package/dist/holmes/rtm/native-driver.js +147 -0
  95. package/dist/holmes/rtm/rtm-graph.js +11 -2
  96. package/dist/holmes/runtime/dispatch.d.ts +6 -0
  97. package/dist/holmes/runtime/dispatch.js +51 -2
  98. package/dist/holmes/runtime/hook-process.d.ts +6 -0
  99. package/dist/holmes/runtime/hook-process.js +3 -3
  100. package/dist/holmes/update/semver-strict.d.ts +3 -0
  101. package/dist/holmes/update/semver-strict.js +58 -0
  102. package/docs/install-guide.md +8 -1
  103. package/package.json +3 -2
  104. package/playbooks/tdd-slice/PLAYBOOK.md +1 -1
  105. package/release-history.json +181 -0
@@ -0,0 +1,42 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.receiptDigest = exports.RECEIPT_FILE = void 0;
4
+ exports.lastReceiptRow = lastReceiptRow;
5
+ // @implements A-SPEC-794.132, A-SPEC-794.133
6
+ /**
7
+ * The runtime binding receipt's one format, shared by its writer and readers (cli/runtime-binding.ts writes and reads it;
8
+ * governance/wiring-receipt.ts reads it for principle 7). Dependency-free beyond node:crypto, so governance can use it
9
+ * without importing the cli layer.
10
+ */
11
+ const node_crypto_1 = require("node:crypto");
12
+ /** The receipt's file name, beside the runtime registry (`<home>/.holmes/runtime/` by default). */
13
+ exports.RECEIPT_FILE = 'installation.json';
14
+ /** The digest a receipt row records for a file's content. */
15
+ const receiptDigest = (content) => (0, node_crypto_1.createHash)('sha256').update(content).digest('hex');
16
+ exports.receiptDigest = receiptDigest;
17
+ /**
18
+ * The last well-formed row whose path is one of `paths`, null when no row names the path. `'malformed'` when `files` is
19
+ * not an array.
20
+ *
21
+ * Two policies, on purpose (A-SPEC-794.133):
22
+ * - strict (the default, principle 7): any row that is not `{path: string, digest: string}` spoils the receipt. Its answer
23
+ * only excuses, so it fails closed.
24
+ * - tolerant (the cli ownership reader): a malformed row is skipped. Disowning on an unrelated bad row would let init
25
+ * rewrite a reviewed wiring file (A-SPEC-752.8).
26
+ */
27
+ function lastReceiptRow(files, paths, opts = {}) {
28
+ if (!Array.isArray(files))
29
+ return 'malformed';
30
+ let last = null;
31
+ for (const row of files) {
32
+ const r = (row !== null && typeof row === 'object' ? row : {});
33
+ if (typeof r.path !== 'string' || typeof r.digest !== 'string') {
34
+ if (opts.tolerant === true)
35
+ continue;
36
+ return 'malformed';
37
+ }
38
+ if (paths.includes(r.path))
39
+ last = { path: r.path, digest: r.digest };
40
+ }
41
+ return last;
42
+ }
@@ -29,4 +29,13 @@ export declare function inspectWorkspacePreflight(input: {
29
29
  loaded: InstallIdentity;
30
30
  stale: StaleFact | null;
31
31
  };
32
+ /** @implements A-SPEC-580.3 — injected in tests; the real probe opens an in-memory database */
33
+ nativeProbe?: () => {
34
+ ok: true;
35
+ } | {
36
+ ok: false;
37
+ error: Error;
38
+ };
39
+ /** A-SPEC-580.9 added it; A-SPEC-580.10 no longer reads it (no `--prefix` here) — accepted for older callers. */
40
+ packageRoot?: string;
32
41
  }): WorkspacePreflight;
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.inspectWorkspacePreflight = inspectWorkspacePreflight;
37
- // @implements A-SPEC-703, A-SPEC-772.1, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-251.4
37
+ // @implements A-SPEC-772.14, A-SPEC-580.10, A-SPEC-580.9, A-SPEC-580.7, A-SPEC-580.5, A-SPEC-580.4, A-SPEC-580.3, A-SPEC-703, A-SPEC-772.1, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-251.4
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const root_1 = require("./root");
@@ -147,6 +147,45 @@ function inspectWorkspacePreflight(input) {
147
147
  const m = mcpBuildCheck(out.boundRoot, input.server, input.harness, input.now ?? Date.now());
148
148
  check('mcp-build', m.status, m.detail, m.actions);
149
149
  }
150
+ // @implements A-SPEC-772.14 — whether a failed Holmes PreToolUse hook blocks or lets every tool through (preflight
151
+ // has no warn status: an open gate on failure is unknown, with the reason)
152
+ {
153
+ const hf = require('../cli/hook-failure-posture');
154
+ const s = hf.hookFailureSentence(hf.hookFailurePosture(out.boundRoot));
155
+ // @implements A-SPEC-772.18 — preflight has no warn status: an open posture says so in its first word
156
+ if (s !== null)
157
+ check('hook-failure', s.open ? 'unknown' : 'pass', s.open ? `open: ${s.detail}` : s.detail, s.fix !== undefined ? [s.fix] : []);
158
+ }
159
+ // @implements A-SPEC-580.3 — every graph tool needs the native driver: say so here, before one of them fails
160
+ {
161
+ const probe = input.nativeProbe ?? require('../rtm/native-driver').probeNativeDriver;
162
+ const p = probe();
163
+ if (p.ok)
164
+ check('native-driver', 'pass', 'The native SQLite driver (better-sqlite3) loads in this Node.');
165
+ else {
166
+ // @implements A-SPEC-580.4 — the commands from the one source, joined for this platform's shell (no && on win32)
167
+ const { nativeRecovery, joinCommands } = require('./native-recovery');
168
+ // @implements A-SPEC-580.7 — pinned to the installed driver version, as the named error and doctor pin it
169
+ let packageVersion = '';
170
+ try {
171
+ packageVersion = String(require('better-sqlite3/package.json').version ?? '');
172
+ }
173
+ catch { /* unknown → unpinned */ }
174
+ // @implements A-SPEC-580.10 — no `--prefix` (only doctor knows npm's default prefix); the sentence sends a
175
+ // prefix install to doctor
176
+ const r = nativeRecovery({ platform: process.platform, packageName: 'better-sqlite3', packageVersion });
177
+ const named = p.error.code === 'native-driver-unavailable';
178
+ const actions = named ? [
179
+ `global install: ${joinCommands(r.global, process.platform)} (or ${r.globalAlternatives.join(', or ')})`,
180
+ `project install: ${joinCommands(r.project, process.platform)}`,
181
+ 'then restart the MCP server; holmes-kit doctor names the cause.',
182
+ require('./native-recovery').DOCTOR_PREFIX_SENTENCE,
183
+ // @implements A-SPEC-580.5 — no setting named: the gate's mode is the owner's (A-SPEC-476.8)
184
+ `Without rights over the global prefix: a privileged shell, or a project install of holmes-kit. ${require('../rtm/native-driver').ASK_THE_OWNER}`,
185
+ ] : ['Run holmes-kit doctor: it names why the native SQLite driver does not load and the command that repairs it.'];
186
+ check('native-driver', 'blocked', `${String(p.error.message).split('. ')[0]} — every graph tool (maintenance_analyze, rtm_impact, test_run scoping) will fail.`, actions);
187
+ }
188
+ }
150
189
  return out;
151
190
  }
152
191
  catch (e) {
@@ -0,0 +1,53 @@
1
+ export type Label = 'new-requirement' | 'existing-requirement-change';
2
+ export interface Activity {
3
+ kind: string;
4
+ id: string;
5
+ }
6
+ export interface LabelResult {
7
+ label: Label | null;
8
+ rule: 1 | 2 | 3 | 4;
9
+ }
10
+ export interface ConfusionRow {
11
+ label: Label | null;
12
+ predicted: string;
13
+ }
14
+ export interface Confusion {
15
+ labelled: number;
16
+ unlabelled: number;
17
+ matrix: Record<string, Record<string, number>>;
18
+ ambiguousRate: number | null;
19
+ offAmbiguous: {
20
+ n: number;
21
+ correct: number;
22
+ accuracy: number | null;
23
+ wilsonLower: number | null;
24
+ };
25
+ mode: 'confusion' | 'classification-rate-only';
26
+ }
27
+ export interface Emission {
28
+ candidates: ReadonlyArray<{
29
+ file: string;
30
+ }>;
31
+ rerankPool: ReadonlyArray<{
32
+ file: string;
33
+ }>;
34
+ impacts: {
35
+ files: readonly string[];
36
+ };
37
+ }
38
+ /** The registration's label rules, in order; reads nothing the analysis produced. */
39
+ export declare function labelOf(activity: readonly Activity[], changedSources: readonly string[], anchored: (file: string) => boolean): LabelResult;
40
+ /** What the product itself disclosed: the unsupported-languages line naming .sh, not judged outside the change. */
41
+ export declare function shellRelevant(unknowns: readonly string[]): boolean;
42
+ /** The 95% (z = 1.96) Wilson score lower bound of k successes in n; null with no trials. */
43
+ export declare function wilsonLower(k: number, n: number, z?: number): number | null;
44
+ /** The matrix over labelled rows; the registration's fallback when the labels cannot carry a confusion matrix. */
45
+ export declare function confusion(rows: readonly ConfusionRow[]): Confusion;
46
+ /** sha256 over `digest\tlabel\trule` lines in digest order — the label table's fingerprint. */
47
+ export declare function labelDigest(rows: ReadonlyArray<{
48
+ digest: string;
49
+ label: string | null;
50
+ rule: number;
51
+ }>): string;
52
+ /** N1: the emitted candidates (rank order), the rerank pool and the impact files are byte-identical. */
53
+ export declare function sameEmission(a: Emission, b: Emission): boolean;
@@ -0,0 +1,78 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.labelOf = labelOf;
4
+ exports.shellRelevant = shellRelevant;
5
+ exports.wilsonLower = wilsonLower;
6
+ exports.confusion = confusion;
7
+ exports.labelDigest = labelDigest;
8
+ exports.sameEmission = sameEmission;
9
+ // @implements A-SPEC-741.2
10
+ /**
11
+ * The pure half of the classification replay — the stick docs/goals/PREREG-0.41.2-B-C-2026-11-14.md (registered at
12
+ * 6cf1655b) names for 0.41.2 B (false `ambiguous` removal) and C (confidence).
13
+ *
14
+ * The label of a request comes from what happened after it, never from the analysis: a new REQ (rule 1), activity on
15
+ * an existing lineage (rule 2), a changed source that already carries an anchor (rule 3), or nothing to go on (rule 4,
16
+ * unlabelled). A classifier that can see its own label measures itself, so `labelOf` takes only those three inputs.
17
+ */
18
+ const node_crypto_1 = require("node:crypto");
19
+ const SPEC_ID = /^(REQ|H-SPEC|A-SPEC|T-SPEC|C-SPEC)-\d/;
20
+ const LINEAGE_ACTS = new Set(['spec-created', 'spec-approved', 'spec-unsealed']);
21
+ /** The registration's label rules, in order; reads nothing the analysis produced. */
22
+ function labelOf(activity, changedSources, anchored) {
23
+ if (activity.some((a) => a.kind === 'spec-created' && /^REQ-\d/.test(a.id)))
24
+ return { label: 'new-requirement', rule: 1 };
25
+ if (activity.some((a) => LINEAGE_ACTS.has(a.kind) && SPEC_ID.test(a.id)))
26
+ return { label: 'existing-requirement-change', rule: 2 };
27
+ if (changedSources.some((f) => anchored(f)))
28
+ return { label: 'existing-requirement-change', rule: 3 };
29
+ return { label: null, rule: 4 };
30
+ }
31
+ /** What the product itself disclosed: the unsupported-languages line naming .sh, not judged outside the change. */
32
+ function shellRelevant(unknowns) {
33
+ return unknowns.some((l) => /^Unsupported languages\b[^\n]*\.sh\b/.test(l) && !/\.sh judged outside this change/.test(l));
34
+ }
35
+ /** The 95% (z = 1.96) Wilson score lower bound of k successes in n; null with no trials. */
36
+ function wilsonLower(k, n, z = 1.96) {
37
+ if (n <= 0)
38
+ return null;
39
+ const p = k / n;
40
+ const v = (p + (z * z) / (2 * n) - z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / (1 + (z * z) / n);
41
+ return Math.max(0, v);
42
+ }
43
+ /** The matrix over labelled rows; the registration's fallback when the labels cannot carry a confusion matrix. */
44
+ function confusion(rows) {
45
+ const labelled = rows.filter((r) => r.label !== null);
46
+ const matrix = {};
47
+ const byLabel = {};
48
+ let ambiguous = 0, correct = 0;
49
+ for (const r of labelled) {
50
+ const l = r.label;
51
+ (matrix[l] ??= {})[r.predicted] = (matrix[l][r.predicted] ?? 0) + 1;
52
+ byLabel[l] = (byLabel[l] ?? 0) + 1;
53
+ if (r.predicted === 'ambiguous')
54
+ ambiguous++;
55
+ else if (r.predicted === r.label)
56
+ correct++;
57
+ }
58
+ const n = labelled.length - ambiguous;
59
+ const dominant = labelled.length === 0 ? 1 : Math.max(...Object.values(byLabel)) / labelled.length;
60
+ return {
61
+ labelled: labelled.length,
62
+ unlabelled: rows.length - labelled.length,
63
+ matrix,
64
+ ambiguousRate: labelled.length === 0 ? null : ambiguous / labelled.length,
65
+ offAmbiguous: { n, correct, accuracy: n === 0 ? null : correct / n, wilsonLower: wilsonLower(correct, n) },
66
+ mode: labelled.length < 30 || dominant >= 0.95 ? 'classification-rate-only' : 'confusion',
67
+ };
68
+ }
69
+ /** sha256 over `digest\tlabel\trule` lines in digest order — the label table's fingerprint. */
70
+ function labelDigest(rows) {
71
+ const lines = [...rows].sort((a, b) => a.digest.localeCompare(b.digest)).map((r) => `${r.digest}\t${r.label ?? ''}\t${r.rule}`);
72
+ return `sha256:${(0, node_crypto_1.createHash)('sha256').update(lines.join('\n')).digest('hex')}`;
73
+ }
74
+ /** N1: the emitted candidates (rank order), the rerank pool and the impact files are byte-identical. */
75
+ function sameEmission(a, b) {
76
+ const key = (e) => JSON.stringify([e.candidates.map((c) => c.file), e.rerankPool.map((c) => c.file), [...e.impacts.files]]);
77
+ return key(a) === key(b);
78
+ }
@@ -173,7 +173,8 @@ function workTreeLink(rootReal, nmReal, label, bound = exports.LINK_WALK) {
173
173
  }
174
174
  for (const k of kids) {
175
175
  if (++seen > bound.entries || Date.now() - t0 > bound.seconds * 1000) {
176
- return `${label} is too large to check within ${bound.entries} entries or ${bound.seconds} s — raise ax.config.json testRun.linkWalk ({ "entries": …, "seconds": … }) to let HEAD's run prove it loads no work-tree code`;
176
+ // A-SPEC-794.136 (B-M4) — the bound is the owner's setting: the text sends the agent to the owner, not to the key
177
+ return `${label} is too large to check within ${bound.entries} entries or ${bound.seconds} s — the walk bound is the owner's setting; ask the owner to raise it so HEAD's run can prove it loads no work-tree code`;
177
178
  }
178
179
  const abs = path.join(d, k.name);
179
180
  if (k.isSymbolicLink()) {
@@ -317,12 +318,12 @@ function openHeadWorktree(root, head, opts) {
317
318
  }
318
319
  catch (e) {
319
320
  close();
320
- return { ok: false, reason: `testRun.prepare could not be read: ${firstLine(e instanceof Error ? e.message : String(e))}` };
321
+ return { ok: false, reason: `the declared prepare command could not be read: ${firstLine(e instanceof Error ? e.message : String(e))}` };
321
322
  }
322
323
  if (prepare && prepare.length > 0) {
323
324
  if (installPrepare(prepare)) {
324
325
  close();
325
- return { ok: false, reason: `testRun.prepare installs packages (${prepare.join(' ')}) — node_modules is the work tree's, linked; an install would change it. Declare a build, not an install` };
326
+ return { ok: false, reason: `the declared prepare command installs packages (${prepare.join(' ')}) — node_modules is the work tree's, linked; an install would change it. Declare a build, not an install` };
326
327
  }
327
328
  try {
328
329
  opts.run(prepare[0], prepare.slice(1), dir, opts.prepareBudgetMs);
@@ -330,7 +331,7 @@ function openHeadWorktree(root, head, opts) {
330
331
  catch (e) {
331
332
  const err = e;
332
333
  close();
333
- return { ok: false, reason: `testRun.prepare failed (${prepare.join(' ')}): ${firstLine(err.stderr || err.stdout || err.message || String(e))}` };
334
+ return { ok: false, reason: `the declared prepare command failed (${prepare.join(' ')}): ${firstLine(err.stderr || err.stdout || err.message || String(e))}` };
334
335
  }
335
336
  }
336
337
  return { ok: true, wt: { dir, createMs, prepareMs: Date.now() - t1, close } };
@@ -39,7 +39,7 @@ exports.pythonEnvironmentResolves = pythonEnvironmentResolves;
39
39
  exports.loadedFromWorkTree = loadedFromWorkTree;
40
40
  exports.pytestRunProvenance = pytestRunProvenance;
41
41
  exports.nodeNamesResolveToWorkTree = nodeNamesResolveToWorkTree;
42
- // @implements A-SPEC-128.14, A-SPEC-128.15, A-SPEC-128.16, A-SPEC-128.17
42
+ // @implements A-SPEC-476.9, A-SPEC-128.14, A-SPEC-128.15, A-SPEC-128.16, A-SPEC-128.17
43
43
  /**
44
44
  * HEAD's run must import HEAD's code. A full pytest unit in HEAD's worktree runs the work tree's interpreter (a `.venv`
45
45
  * is not in HEAD), and an editable install, a `.pth` finder or a path entry there can load the work tree's source — so
@@ -243,7 +243,8 @@ function pytestRunProvenance(tmpDir, run, unitCwd, python, env, exec) {
243
243
  fs.writeFileSync(path.join(tmpDir, `${exports.PLUGIN}.py`), SOURCE);
244
244
  return {
245
245
  refused: named.over
246
- ? `HEAD has more python module names than ${cap} — raise ax.config.json testRun.pythonNames to let the run prove where each resolves`
246
+ // A-SPEC-476.9 — the bound is the owner's setting: the text sends the agent to the owner instead of naming the key
247
+ ? `HEAD has more python module names than ${cap} — the bound is the owner's setting; ask the owner to raise it so the run can prove where each resolves`
247
248
  : pythonEnvironmentResolves(python, unitCwd, named.names, run.sourceRoot, run.root, env, exec),
248
249
  args: ['-c', ini, '-p', exports.PLUGIN],
249
250
  confcutdir: inifile ? real(path.dirname(inifile)) : real(unitCwd),
@@ -55,7 +55,7 @@ exports.writeScopedEvidence = writeScopedEvidence;
55
55
  exports.readScopedEvidence = readScopedEvidence;
56
56
  exports.testEvidenceState = testEvidenceState;
57
57
  exports.scopedEvidenceState = scopedEvidenceState;
58
- // @implements A-SPEC-102.1, A-SPEC-734, A-SPEC-466.2, A-SPEC-466.3, A-SPEC-466.6, A-SPEC-128.2, A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.6, A-SPEC-128.7, A-SPEC-128.8, A-SPEC-128.9, A-SPEC-128.10, A-SPEC-128.12, A-SPEC-128.13
58
+ // @implements A-SPEC-476.9, A-SPEC-102.1, A-SPEC-734, A-SPEC-466.2, A-SPEC-466.3, A-SPEC-466.6, A-SPEC-128.2, A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.6, A-SPEC-128.7, A-SPEC-128.8, A-SPEC-128.9, A-SPEC-128.10, A-SPEC-128.12, A-SPEC-128.13
59
59
  const fs = __importStar(require("node:fs"));
60
60
  const path = __importStar(require("node:path"));
61
61
  const bounded_io_1 = require("../project/bounded-io");
@@ -68,7 +68,7 @@ function coverageVerdict(r) {
68
68
  const missing = isStringArray(r.notExecuted) ? r.notExecuted : [];
69
69
  if (missing.length > 0) {
70
70
  const shown = missing.slice(0, 5).join(', ') + (missing.length > 5 ? ` (+${missing.length - 5})` : '');
71
- return { problem: `these test files did not run: ${shown} — make the runner collect them (its configuration), or, if they are not the project's, exclude them with .gitignore or ax.config.json testRun.excludeDirs`, act: 'collect' };
71
+ return { problem: `these test files did not run: ${shown} — make the runner collect them (its configuration), or, if they are not the project's, exclude them with .gitignore or ask the owner to exclude them (the test-run exclusions are the owner's setting)`, act: 'collect' }; // A-SPEC-476.9
72
72
  }
73
73
  const untested = Array.isArray(r.untestedCode) ? r.untestedCode.filter((g) => g && typeof g === 'object') : [];
74
74
  if (untested.length > 0) {
@@ -45,7 +45,7 @@ exports.appendOutcomes = appendOutcomes;
45
45
  exports.readOutcomes = readOutcomes;
46
46
  exports.buildOutcomeRecords = buildOutcomeRecords;
47
47
  exports.groupOutcomesByAspec = groupOutcomesByAspec;
48
- // @implements A-SPEC-724.1, A-SPEC-714, A-SPEC-734, A-SPEC-748, A-SPEC-794.58
48
+ // @implements A-SPEC-580.6, A-SPEC-724.1, A-SPEC-714, A-SPEC-734, A-SPEC-748, A-SPEC-794.58
49
49
  // @implements A-SPEC-534.3, A-SPEC-625
50
50
  // @implements A-SPEC-645
51
51
  const node_crypto_1 = require("node:crypto");
@@ -111,6 +111,8 @@ exports.REQUIRED_DOCS_TESTS = [
111
111
  'src/holmes/project/dependency-overrides.test.ts',
112
112
  // A-SPEC-794.58 — a docs-only change can carry a name into README; the publish path checks the pack too
113
113
  'src/holmes/governance/private-names.test.ts',
114
+ // A-SPEC-580.6 — pins the README's native-driver recovery commands to nativeRecovery (580.4, 580.5)
115
+ 'src/holmes/rtm/native-driver-surfaces.test.ts',
114
116
  ];
115
117
  /**
116
118
  * @implements A-SPEC-748 — every path of every change (both sides of a rename or copy) must be `README.md` or under
@@ -74,6 +74,11 @@ export type PublishedGraph = {
74
74
  status: 'absent' | 'unreadable' | 'empty';
75
75
  graph: null;
76
76
  graphAsOf?: string;
77
+ } | {
78
+ status: 'driver-unavailable';
79
+ graph: null;
80
+ graphAsOf?: string;
81
+ reason: string;
77
82
  } | {
78
83
  status: 'current' | 'stale' | 'unverified';
79
84
  graph: RtmGraph;
@@ -40,8 +40,8 @@ exports.openReusableGraph = openReusableGraph;
40
40
  exports.publishGraph = publishGraph;
41
41
  exports.openPublishedGraph = openPublishedGraph;
42
42
  exports.headCommitOf = headCommitOf;
43
- // @implements A-SPEC-282, A-SPEC-734
44
- // @implements A-SPEC-631
43
+ // @implements A-SPEC-282, A-SPEC-734, A-SPEC-580.4
44
+ // @implements A-SPEC-631, A-SPEC-580.2
45
45
  const fs = __importStar(require("node:fs"));
46
46
  const path = __importStar(require("node:path"));
47
47
  const node_crypto_1 = require("node:crypto");
@@ -104,7 +104,13 @@ function openReusableGraph(dbPath, expected, opts = {}) {
104
104
  try {
105
105
  graph = new rtm_graph_1.RtmGraph(dbPath);
106
106
  }
107
- catch {
107
+ catch (e) {
108
+ // @implements A-SPEC-580.2, A-SPEC-580.4 — the file is replaced only when SQLite itself says it is not a database or
109
+ // is corrupt. A driver that did not load, or any error that is not known corruption, says nothing about the file:
110
+ // it is rethrown and the file stays (the W1 review found driver texts the old pattern list missed deleting a graph).
111
+ const code = e?.code;
112
+ if (code !== 'SQLITE_NOTADB' && code !== 'SQLITE_CORRUPT')
113
+ throw e;
108
114
  // Corrupt beyond opening: replace the file outright and carry on with an empty graph.
109
115
  try {
110
116
  fs.rmSync(dbPath, { force: true });
@@ -274,7 +280,9 @@ function openPublishedGraph(livePath, head) {
274
280
  try {
275
281
  graph = new rtm_graph_1.RtmGraph(livePath);
276
282
  }
277
- catch {
283
+ catch (e) {
284
+ if (e?.code === 'native-driver-unavailable')
285
+ return { status: 'driver-unavailable', graph: null, graphAsOf, reason: e.message };
278
286
  return { status: 'unreadable', graph: null, graphAsOf };
279
287
  }
280
288
  let meta, nodes;
@@ -0,0 +1,42 @@
1
+ /**
2
+ * @implements A-SPEC-580.5 — what an agent that cannot rebuild is told. It names no setting and no file: the edit gate's
3
+ * mode is the owner's to change (A-SPEC-476.8), and naming the key told a blocked agent how to switch its own gate off.
4
+ * The driver error, the edit gate's no-analysis cause and workspace_preflight all use this sentence.
5
+ */
6
+ export declare const ASK_THE_OWNER = "If you cannot rebuild, ask the owner: the edit gate's mode is the owner's setting, not the agent's.";
7
+ export type DriverFailureKind = 'scripts-blocked' | 'abi-mismatch' | 'platform-mismatch' | 'missing-module';
8
+ /** The class of a driver load failure, or null when `e` is not one (a SqliteError, an unrelated error). */
9
+ export declare function classifyDriverFailure(e: unknown): DriverFailureKind | null;
10
+ export declare function isDriverLoadFailure(e: unknown): boolean;
11
+ export declare class NativeDriverUnavailable extends Error {
12
+ readonly kind: DriverFailureKind;
13
+ readonly observed: string;
14
+ readonly nodeVersion: string;
15
+ readonly recovery: {
16
+ global: string[];
17
+ project: string[];
18
+ };
19
+ readonly code = "native-driver-unavailable";
20
+ constructor(message: string, kind: DriverFailureKind, observed: string, nodeVersion: string, recovery: {
21
+ global: string[];
22
+ project: string[];
23
+ });
24
+ }
25
+ /**
26
+ * @implements A-SPEC-580.3 — whether the driver loads in this process: an in-memory database opened and closed. A failure
27
+ * that is a driver load failure comes back as the named error; any other failure is reported as it is.
28
+ */
29
+ export declare function probeNativeDriver(): {
30
+ ok: true;
31
+ } | {
32
+ ok: false;
33
+ error: Error;
34
+ };
35
+ /**
36
+ * @implements A-SPEC-580.7, A-SPEC-580.8 — the first line of a driver error as a person reads it. Only bindings'
37
+ * "Tried:" line is completed: with the first path tried and the count of the other paths (stack lines are not paths);
38
+ * with no path, "(no path listed)". Any other first line is kept as it is. Exported for the MCP launcher.
39
+ */
40
+ export declare function observedLine(message: unknown): string;
41
+ /** The named error for a driver load failure `e`. */
42
+ export declare function driverUnavailable(e: unknown): NativeDriverUnavailable;
@@ -0,0 +1,147 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.NativeDriverUnavailable = exports.ASK_THE_OWNER = void 0;
4
+ exports.classifyDriverFailure = classifyDriverFailure;
5
+ exports.isDriverLoadFailure = isDriverLoadFailure;
6
+ exports.probeNativeDriver = probeNativeDriver;
7
+ exports.observedLine = observedLine;
8
+ exports.driverUnavailable = driverUnavailable;
9
+ // @implements A-SPEC-580.2, A-SPEC-580.3, A-SPEC-580.4, A-SPEC-580.5, A-SPEC-580.7, A-SPEC-580.8, A-SPEC-580.9, A-SPEC-580.10
10
+ /**
11
+ * A native SQLite driver that did not load is its own failure, not a corrupt graph. Field case (Windows 11, Node
12
+ * 24.19.0, npm 12.1.0, global install of 0.41.2, 2026-11-15): npm 12 skipped better-sqlite3's install script because the
13
+ * package's allowScripts reaches only the root project, so `better_sqlite3.node` was never built and every graph tool
14
+ * answered "Could not locate the bindings file" with no cause and no way out.
15
+ *
16
+ * A-SPEC-580.4 (the W1 review) — the class is judged by `err.code` first: Node puts `ERR_DLOPEN_FAILED` on every dlopen
17
+ * failure (measured on macOS and Windows) and `MODULE_NOT_FOUND` on a missing module. Message patterns are the fallback,
18
+ * one list per class. The recovery commands come from the one source in the project layer.
19
+ */
20
+ const native_recovery_1 = require("../project/native-recovery");
21
+ /**
22
+ * @implements A-SPEC-580.5 — what an agent that cannot rebuild is told. It names no setting and no file: the edit gate's
23
+ * mode is the owner's to change (A-SPEC-476.8), and naming the key told a blocked agent how to switch its own gate off.
24
+ * The driver error, the edit gate's no-analysis cause and workspace_preflight all use this sentence.
25
+ */
26
+ exports.ASK_THE_OWNER = 'If you cannot rebuild, ask the owner: the edit gate\'s mode is the owner\'s setting, not the agent\'s.';
27
+ /** The fallback texts, one list per class: the first list that matches decides. */
28
+ const PATTERNS = [
29
+ ['scripts-blocked', [/Could not locate the bindings file/]],
30
+ ['abi-mismatch', [/NODE_MODULE_VERSION/, /compiled against a different Node\.js version/, /did not self-register/]],
31
+ ['platform-mismatch', [/GLIBC_/, /invalid ELF header/, /not a valid Win32 application/, /DLL\) initialization routine failed/,
32
+ /The specified module could not be found/, /wrong ELF class/, /incompatible architecture/, /\bdlopen\(/]],
33
+ ['missing-module', [/Cannot find module ['"]better-sqlite3['"]/, /Cannot find module ['"]bindings['"]/]],
34
+ ];
35
+ const ABI = PATTERNS.find(([k]) => k === 'abi-mismatch')?.[1] ?? [];
36
+ const messageOf = (e) => (e instanceof Error ? e.message : typeof e === 'string' ? e : '');
37
+ /** The class of a driver load failure, or null when `e` is not one (a SqliteError, an unrelated error). */
38
+ function classifyDriverFailure(e) {
39
+ const code = e?.code;
40
+ if (typeof code === 'string' && code.startsWith('SQLITE_'))
41
+ return null;
42
+ const message = messageOf(e);
43
+ if (code === 'ERR_DLOPEN_FAILED')
44
+ return ABI.some((re) => re.test(message)) ? 'abi-mismatch' : 'platform-mismatch';
45
+ // A-SPEC-580.5 — the first line only: the require stack below it names whoever required, not what is missing
46
+ if (code === 'MODULE_NOT_FOUND' && /better-sqlite3|['"]bindings['"]|\.node\b/.test(message.split(/\r?\n/)[0]))
47
+ return 'missing-module';
48
+ for (const [kind, res] of PATTERNS)
49
+ if (res.some((re) => re.test(message)))
50
+ return kind;
51
+ return null;
52
+ }
53
+ function isDriverLoadFailure(e) {
54
+ return classifyDriverFailure(e) !== null;
55
+ }
56
+ class NativeDriverUnavailable extends Error {
57
+ kind;
58
+ observed;
59
+ nodeVersion;
60
+ recovery;
61
+ code = 'native-driver-unavailable';
62
+ constructor(message, kind, observed, nodeVersion, recovery) {
63
+ super(message);
64
+ this.kind = kind;
65
+ this.observed = observed;
66
+ this.nodeVersion = nodeVersion;
67
+ this.recovery = recovery;
68
+ this.name = 'NativeDriverUnavailable';
69
+ }
70
+ }
71
+ exports.NativeDriverUnavailable = NativeDriverUnavailable;
72
+ /**
73
+ * @implements A-SPEC-580.3 — whether the driver loads in this process: an in-memory database opened and closed. A failure
74
+ * that is a driver load failure comes back as the named error; any other failure is reported as it is.
75
+ */
76
+ function probeNativeDriver() {
77
+ try {
78
+ const Database = require('better-sqlite3');
79
+ new Database(':memory:').close();
80
+ return { ok: true };
81
+ }
82
+ catch (e) {
83
+ return { ok: false, error: isDriverLoadFailure(e) ? driverUnavailable(e) : (e instanceof Error ? e : new Error(String(e))) };
84
+ }
85
+ }
86
+ /** The cause sentence for each class (A-SPEC-580.4 Behavior 4): an ABI mismatch is a Node change, not npm 12. */
87
+ const CAUSE = {
88
+ 'scripts-blocked': 'The driver binary was never built: npm 12 skips dependency install scripts that allowScripts does not cover, and a global install has no project package.json to carry that approval.',
89
+ 'abi-mismatch': 'The driver was built for another Node version: Node was upgraded or switched after the install; rebuild it for this Node.',
90
+ 'platform-mismatch': 'The driver binary does not fit this machine (OS, CPU or C library): it was installed or copied for another platform; rebuild it here.',
91
+ 'missing-module': 'The driver package is not installed: reinstall holmes-kit, then rebuild.',
92
+ };
93
+ /** The first line of the error as a person reads it: split on CRLF or LF, without Windows' `\\?\` long-path prefix. */
94
+ function observedOf(e) {
95
+ return observedLine(String(e instanceof Error ? e.message : e));
96
+ }
97
+ /**
98
+ * @implements A-SPEC-580.7, A-SPEC-580.8 — the first line of a driver error as a person reads it. Only bindings'
99
+ * "Tried:" line is completed: with the first path tried and the count of the other paths (stack lines are not paths);
100
+ * with no path, "(no path listed)". Any other first line is kept as it is. Exported for the MCP launcher.
101
+ */
102
+ function observedLine(message) {
103
+ // A-SPEC-580.9: any value (undefined included); `\\?\UNC\server\…` reads as `\\server\…`, `\\?\C:\…` as `C:\…`
104
+ // A-SPEC-580.10: UNC in any case; a value String() cannot convert (a null prototype) reads as empty
105
+ const unprefix = (l) => l.replace(/^\\\\\?\\UNC\\/i, '\\\\').replace(/^\\\\\?\\/, '');
106
+ let text = '';
107
+ try {
108
+ text = String(message ?? '');
109
+ }
110
+ catch { /* no toString */ }
111
+ const lines = text.split(/\r?\n/).map((l) => unprefix(l).trim());
112
+ if (!/\bTried:$/.test(lines[0]))
113
+ return lines[0];
114
+ const paths = lines.slice(1).map((l) => unprefix(l.replace(/^(?:→|->|-)\s*/, '')))
115
+ .filter((l) => /^(?:\/|[A-Za-z]:[\\/]|\\\\|\.{1,2}[\\/])/.test(l));
116
+ if (paths.length === 0)
117
+ return `${lines[0]} (no path listed)`;
118
+ return `${lines[0]} ${paths[0]}${paths.length > 1 ? ` (and ${paths.length - 1} more)` : ''}`;
119
+ }
120
+ /** The named error for a driver load failure `e`. */
121
+ function driverUnavailable(e) {
122
+ const kind = classifyDriverFailure(e) ?? 'scripts-blocked';
123
+ const observed = observedOf(e);
124
+ const nodeVersion = process.version;
125
+ let version = '';
126
+ try {
127
+ version = String(require('better-sqlite3/package.json').version ?? '');
128
+ }
129
+ catch { /* unknown → unpinned form */ }
130
+ // @implements A-SPEC-580.10 — no `--prefix` here: only doctor knows npm's default prefix (580.9 put the default
131
+ // Windows prefix in every command); the sentence sends a prefix install to doctor
132
+ const r = (0, native_recovery_1.nativeRecovery)({ platform: process.platform, packageName: 'better-sqlite3', packageVersion: version });
133
+ const recovery = { global: r.global, project: r.project };
134
+ const message = [
135
+ `the native SQLite driver (better-sqlite3) did not load in this Node (${nodeVersion}, ABI ${process.versions.modules}): ${observed}.`,
136
+ CAUSE[kind],
137
+ 'Recover with the one that matches how holmes-kit is installed —',
138
+ `global install: ${(0, native_recovery_1.joinCommands)(r.global, process.platform)} (or ${r.globalAlternatives.join(', or ')});`,
139
+ `project install: ${(0, native_recovery_1.joinCommands)(r.project, process.platform)};`,
140
+ 'then restart the MCP server. `holmes-kit doctor` names the cause.',
141
+ native_recovery_1.DOCTOR_PREFIX_SENTENCE,
142
+ 'Without rights over the global prefix (EPERM): run the global rebuild from an administrator or privileged shell;',
143
+ 'or install holmes-kit in the project and point the MCP server at it (`holmes-kit init` in the project);',
144
+ exports.ASK_THE_OWNER, // A-SPEC-580.5 — no setting named: the gate's mode is the owner's (A-SPEC-476.8)
145
+ ].join(' ');
146
+ return new NativeDriverUnavailable(message, kind, observed, nodeVersion, recovery);
147
+ }
@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.RtmGraph = void 0;
7
- // @implements A-SPEC-588
7
+ // @implements A-SPEC-588, A-SPEC-580.2
8
8
  // @implements A-SPEC-293
9
9
  // @implements A-SPEC-644
10
10
  // @implements A-SPEC-289
@@ -67,7 +67,16 @@ class RtmGraph {
67
67
  // adds reference-counting) — otherwise it will silently diverge from a
68
68
  // full rebuild.
69
69
  constructor(dbPath = ':memory:') {
70
- this.db = new better_sqlite3_1.default(dbPath);
70
+ // @implements A-SPEC-580.2 — a driver that did not load is named, with both labelled recovery commands
71
+ try {
72
+ this.db = new better_sqlite3_1.default(dbPath);
73
+ }
74
+ catch (e) {
75
+ const nd = require('./native-driver');
76
+ if (nd.isDriverLoadFailure(e))
77
+ throw nd.driverUnavailable(e);
78
+ throw e;
79
+ }
71
80
  try {
72
81
  // @implements A-SPEC-283
73
82
  // Only a FILE-backed store can be contended. Several MCP servers can be live at once, and the
@@ -16,4 +16,10 @@ export interface DispatchOptions {
16
16
  hookBudgetMs?: number;
17
17
  cleanupBudgetMs?: number;
18
18
  }
19
+ /**
20
+ * @implements A-SPEC-772.22 — why a PreToolUse answer is not one, or null. claude/codex: the gate's own contract
21
+ * (validHookAnswer, A-SPEC-728.4 — restated here because this module imports nothing of the gate; a test holds the two
22
+ * equal); antigravity: its adapter's `{decision: allow|deny|ask}` with exit 0.
23
+ */
24
+ export declare function preToolUseAnswerProblem(harness: string, stdout: string, code: number): string | null;
19
25
  export declare function runDispatch(opts: DispatchOptions): Promise<void>;