@holmes-lab/holmes-kit 0.38.0 → 0.39.0

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 (41) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +7 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve.d.ts +1 -0
  5. package/dist/holmes/cli/approve.js +12 -1
  6. package/dist/holmes/cli/doctor.js +12 -1
  7. package/dist/holmes/cli/index.js +7 -3
  8. package/dist/holmes/cli/mcp-processes.d.ts +32 -0
  9. package/dist/holmes/cli/mcp-processes.js +132 -0
  10. package/dist/holmes/cli/run-provision.d.ts +6 -0
  11. package/dist/holmes/cli/run-provision.js +114 -0
  12. package/dist/holmes/cli/run.d.ts +5 -0
  13. package/dist/holmes/cli/run.js +38 -6
  14. package/dist/holmes/governance/approval-queue.d.ts +5 -0
  15. package/dist/holmes/governance/approval-queue.js +13 -0
  16. package/dist/holmes/governance/tool-actions.js +2 -0
  17. package/dist/holmes/guardrail/refusal-codes.js +7 -1
  18. package/dist/holmes/guardrail/risk-classifier.js +21 -3
  19. package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
  20. package/dist/holmes/guardrail/run-refusals.js +13 -7
  21. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  22. package/dist/holmes/guardrail/run-stages.js +23 -3
  23. package/dist/holmes/hooks/pre-tool-use.js +33 -1
  24. package/dist/holmes/hooks/session-start.d.ts +5 -0
  25. package/dist/holmes/hooks/session-start.js +29 -1
  26. package/dist/holmes/hooks/stop.js +4 -2
  27. package/dist/holmes/mcp/handlers/approval-ask.d.ts +11 -0
  28. package/dist/holmes/mcp/handlers/approval-ask.js +15 -1
  29. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
  30. package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
  31. package/dist/holmes/mcp/handlers.d.ts +10 -0
  32. package/dist/holmes/mcp/handlers.js +24 -3
  33. package/dist/holmes/mcp/server-staleness.d.ts +43 -0
  34. package/dist/holmes/mcp/server-staleness.js +158 -0
  35. package/dist/holmes/mcp/server.js +26 -2
  36. package/dist/holmes/mcp/tool-schemas.js +13 -0
  37. package/dist/holmes/project/workspace-preflight.d.ts +5 -0
  38. package/dist/holmes/project/workspace-preflight.js +24 -1
  39. package/dist/holmes/review/verdicts.d.ts +5 -0
  40. package/dist/holmes/review/verdicts.js +16 -1
  41. package/package.json +1 -1
@@ -0,0 +1,158 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.MCP_HEARTBEAT_DIR = void 0;
37
+ exports.readInstallIdentity = readInstallIdentity;
38
+ exports.makeStalenessProbe = makeStalenessProbe;
39
+ exports.staleNotice = staleNotice;
40
+ exports.writeMcpHeartbeat = writeMcpHeartbeat;
41
+ exports.readMcpHeartbeats = readMcpHeartbeats;
42
+ // @implements A-SPEC-251.4
43
+ /**
44
+ * Whether the install a running MCP server was loaded from has changed under it, and the server's heartbeat.
45
+ *
46
+ * Measured 2026-10-23 (D1): the jarvis session's holmes-kit MCP served v0.36.0 while the global install its `.mcp.json`
47
+ * names was 0.38.0 — the process had started before the install was upgraded in place — so `approval_ask`,
48
+ * `review_verdict` and `phase_check` were missing and nothing said so. A-SPEC-251.2 compares the WIRING with the CLI
49
+ * (they matched); A-SPEC-156's basis compares the loaded build with the WORKSPACE's dist (a consumer has none).
50
+ *
51
+ * The probe states two facts the process can read and compares them by string inequality only, so a server running
52
+ * old code still computes it correctly (A-SPEC-156's caution about a stale build judging itself). Nothing here
53
+ * restarts, kills or refuses; a heartbeat is information only (A-SPEC-772.5).
54
+ */
55
+ const fs = __importStar(require("node:fs"));
56
+ const path = __importStar(require("node:path"));
57
+ const SCHEMA = 'holmes-mcp-heartbeat/1';
58
+ exports.MCP_HEARTBEAT_DIR = path.join('.ax', 'state', 'mcp-heartbeat');
59
+ const WRITE_EVERY_MS = 60_000;
60
+ const ALIVE_WITHIN_MS = 24 * 3600_000;
61
+ const MAX_RECORD_BYTES = 4096;
62
+ /** The package root's version and build id, or null when the version cannot be read (absence is not staleness). */
63
+ function readInstallIdentity(pkgRoot) {
64
+ try {
65
+ const version = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
66
+ if (typeof version !== 'string' || version === '')
67
+ return null;
68
+ let buildId = 'unknown';
69
+ try {
70
+ buildId = fs.readFileSync(path.join(pkgRoot, 'dist', '.build-id'), 'utf8').trim() || 'unknown';
71
+ }
72
+ catch { /* unstamped */ }
73
+ return { version, buildId: buildId.slice(0, 200) };
74
+ }
75
+ catch {
76
+ return null;
77
+ }
78
+ }
79
+ const label = (i) => `v${i.version} (build ${i.buildId})`;
80
+ /** At most one disk read per `everyMs` (default 30 s); the last answer is kept between reads. */
81
+ function makeStalenessProbe(pkgRoot, loaded, opts = {}) {
82
+ const now = opts.now ?? Date.now;
83
+ const every = opts.everyMs ?? 30_000;
84
+ const pid = opts.pid ?? process.pid;
85
+ const startedAt = opts.startedAt ?? new Date(now()).toISOString();
86
+ let checkedAt = -Infinity;
87
+ let last = null;
88
+ return () => {
89
+ const t = now();
90
+ if (t - checkedAt < every)
91
+ return last;
92
+ checkedAt = t;
93
+ const onDisk = readInstallIdentity(pkgRoot);
94
+ last = onDisk !== null && (onDisk.version !== loaded.version || onDisk.buildId !== loaded.buildId)
95
+ ? { loaded, onDisk, pid, startedAt,
96
+ fix: `this MCP server process (pid ${pid}, started ${startedAt}) loaded v${loaded.version} but its install is now v${onDisk.version}; `
97
+ + `tools added since v${loaded.version} are missing — restart the harness session (or its MCP server) to load v${onDisk.version}` }
98
+ : null;
99
+ return last;
100
+ };
101
+ }
102
+ function staleNotice(f) {
103
+ return { loaded: label(f.loaded), onDisk: label(f.onDisk), fix: f.fix };
104
+ }
105
+ const fileFor = (projectRoot, client) => path.join(projectRoot, exports.MCP_HEARTBEAT_DIR, `${client.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64) || 'unknown'}.json`);
106
+ /** Best effort: at most one write per client a minute; every failure is swallowed. */
107
+ function writeMcpHeartbeat(projectRoot, beat, now) {
108
+ try {
109
+ const file = fileFor(projectRoot, beat.client);
110
+ try {
111
+ const prev = JSON.parse(fs.readFileSync(file, 'utf8'));
112
+ if (prev.pid === beat.pid && typeof prev.at === 'string' && now - Date.parse(prev.at) < WRITE_EVERY_MS)
113
+ return;
114
+ }
115
+ catch { /* none yet, or unreadable: write */ }
116
+ fs.mkdirSync(path.dirname(file), { recursive: true });
117
+ const tmp = `${file}.${process.pid}.tmp`;
118
+ fs.writeFileSync(tmp, JSON.stringify({ schema: SCHEMA, ...beat, at: new Date(now).toISOString() }) + '\n');
119
+ fs.renameSync(tmp, file);
120
+ }
121
+ catch { /* information only */ }
122
+ }
123
+ const alivePid = (pid) => {
124
+ try {
125
+ process.kill(pid, 0);
126
+ return true;
127
+ }
128
+ catch (e) {
129
+ return e.code === 'EPERM';
130
+ }
131
+ };
132
+ /** Valid beats under `.ax/state/mcp-heartbeat`, each with whether its process is alive and the beat under 24 h old. */
133
+ function readMcpHeartbeats(projectRoot, now) {
134
+ const dir = path.join(projectRoot, exports.MCP_HEARTBEAT_DIR);
135
+ let names = [];
136
+ try {
137
+ names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
138
+ }
139
+ catch {
140
+ return [];
141
+ }
142
+ const out = [];
143
+ for (const n of names.slice(0, 32)) {
144
+ try {
145
+ const p = path.join(dir, n);
146
+ if (fs.lstatSync(p).size > MAX_RECORD_BYTES)
147
+ continue;
148
+ const b = JSON.parse(fs.readFileSync(p, 'utf8'));
149
+ if (b.schema !== SCHEMA || typeof b.pid !== 'number' || typeof b.version !== 'string' || typeof b.buildId !== 'string'
150
+ || typeof b.client !== 'string' || typeof b.at !== 'string')
151
+ continue;
152
+ const age = now - Date.parse(b.at);
153
+ out.push({ ...b, alive: Number.isFinite(age) && age >= 0 && age < ALIVE_WITHIN_MS && alivePid(b.pid) });
154
+ }
155
+ catch { /* skip */ }
156
+ }
157
+ return out;
158
+ }
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734, A-SPEC-751.3
4
+ // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734, A-SPEC-751.3, A-SPEC-251.4, A-SPEC-779.7
5
5
  const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
6
6
  const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
7
7
  const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
@@ -67,11 +67,35 @@ const harnessAttestation = () => {
67
67
  }
68
68
  return attested;
69
69
  };
70
+ // @implements A-SPEC-251.4 — whether the install this process loaded changed under it, and the heartbeat that lets the
71
+ // hooks compare builds. Both fail open: a server that cannot read its own package root starts and answers as before.
72
+ const { makeStalenessProbe, readInstallIdentity, writeMcpHeartbeat } = require('./server-staleness');
73
+ const pkgRoot = require('node:path').resolve(__dirname, '..', '..', '..');
74
+ const loadedIdentity = readInstallIdentity(pkgRoot) ?? { version: 'unknown', buildId: 'unknown' };
75
+ const serverStartedAt = new Date().toISOString();
76
+ const serverStaleness = makeStalenessProbe(pkgRoot, loadedIdentity, { startedAt: serverStartedAt });
77
+ // @implements A-SPEC-779.7 — this instance stamps the requests it files, so this session (and only it) withdraws them.
78
+ const serverInstanceId = `${process.pid}:${serverStartedAt}`;
79
+ require('../governance/approval-queue').setRequesterServer(serverInstanceId);
80
+ const beat = (root) => {
81
+ try {
82
+ const client = (() => { try {
83
+ return server.getClientVersion()?.name ?? 'unknown';
84
+ }
85
+ catch {
86
+ return 'unknown';
87
+ } })();
88
+ writeMcpHeartbeat(root, { client, pid: process.pid, version: loadedIdentity.version, buildId: loadedIdentity.buildId, packageRoot: pkgRoot, startedAt: serverStartedAt }, Date.now());
89
+ }
90
+ catch { /* information only */ }
91
+ };
70
92
  const handlers = (0, handlers_1.makeHandlers)(store, {
71
93
  harnessAttestation,
72
94
  elicit,
73
95
  elicitationAvailable: () => (0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()),
74
- observeInvocation: root => stampSession(root),
96
+ observeInvocation: root => { stampSession(root); beat(root); },
97
+ serverStaleness,
98
+ serverInstance: () => serverInstanceId,
75
99
  clientName: () => { try {
76
100
  return server.getClientVersion()?.name ?? 'unknown';
77
101
  }
@@ -235,6 +235,19 @@ exports.TOOL_SCHEMAS = {
235
235
  required: ['id'],
236
236
  },
237
237
  },
238
+ // @implements A-SPEC-779.7
239
+ approval_withdraw: {
240
+ description: "Withdraw ONE pending approval request this session's MCP server filed, when the act it was filed for is no longer wanted (the slice was abandoned, a spec was replaced). Recorded as `withdrawn` — never granted, never denied — and gone from the operator's inbox, so nobody approves a request you gave up. Returns { ok, id, decision: withdrawn } or { ok: false, reason }. Refuses a request another session (or a hook, the CLI, a run) filed; a run withdraws its own with `approve --withdraw`. A reason is required: it is what the operator reads in place of a decision.",
241
+ inputSchema: {
242
+ type: 'object',
243
+ properties: {
244
+ id: str('The request id, e.g. req-0123456789ab.'),
245
+ reason: str('Why the request is no longer wanted.'),
246
+ root: str('Optional when the server is bound to a file store; if supplied it must resolve to the SAME project.'),
247
+ },
248
+ required: ['id', 'reason'],
249
+ },
250
+ },
238
251
  // @implements A-SPEC-102.9
239
252
  review_verdict: {
240
253
  description: "Ask the person for an independent review verdict on base..head in this session's approval form. approve records pass, deny records fail with the person's reason as the finding; the verdict is recorded as the person's (reviewer.person true, channel elicitation:<client>, independent true), so it satisfies the review gate without a separate terminal. Returns { ok, decision: pass|fail|undecided, independent? }. Silence, a question and an automatic decline record nothing. Refuses, recording nothing, inside a run, when the session cannot show a form, and on a client not yet measured to wait for a person (only claude-code today).",
@@ -1,6 +1,7 @@
1
1
  import { Agent } from '../cli/agents';
2
2
  import { WorkspaceIdentityStatus } from './workspace-identity';
3
3
  import { CheckoutInfo } from './workspace-checkout';
4
+ import type { InstallIdentity, StaleFact } from '../mcp/server-staleness';
4
5
  export type { CheckoutInfo } from './workspace-checkout';
5
6
  export type PreflightCheck = {
6
7
  id: string;
@@ -24,4 +25,8 @@ export declare function inspectWorkspacePreflight(input: {
24
25
  storeRoot?: string;
25
26
  harness?: Agent;
26
27
  now?: number;
28
+ server?: {
29
+ loaded: InstallIdentity;
30
+ stale: StaleFact | null;
31
+ };
27
32
  }): 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
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
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const root_1 = require("./root");
@@ -77,6 +77,25 @@ function enforcementCheck(root, harness, now) {
77
77
  return { status: 'unknown', detail: `${harness} hooks were never observed in this workspace; live activation is unverified.${recorderOff()}`,
78
78
  actions: [`Run holmes-kit doctor --target ${root} and check the ${harness} hook wiring.`] };
79
79
  }
80
+ /**
81
+ * @implements A-SPEC-251.4 — the MCP server's loaded build against the install under it and the hook build observed
82
+ * for this harness. A different hook build means the session's tools and its gate come from different releases.
83
+ */
84
+ function mcpBuildCheck(root, server, harness, now) {
85
+ const loaded = `v${server.loaded.version} (build ${server.loaded.buildId})`;
86
+ if (server.stale !== null) {
87
+ return { status: 'blocked', detail: `This MCP server loaded ${loaded}, but its install is now v${server.stale.onDisk.version} (build ${server.stale.onDisk.buildId}).`,
88
+ actions: ['Restart the harness session (or its MCP server) so the server loads the installed build.'] };
89
+ }
90
+ if (harness !== undefined) {
91
+ const o = (0, heartbeat_1.observationOf)((0, heartbeat_1.readHookHeartbeats)(root, now), harness, now, undefined, 'pre-tool-use');
92
+ if (o.state === 'observed' && o.buildId !== server.loaded.buildId) {
93
+ return { status: 'blocked', detail: `This MCP server is ${loaded}, but the ${harness} hooks here ran build ${o.buildId} at ${o.at}.`,
94
+ actions: ['Align the MCP server and the hooks on one build: restart the session after upgrading, or rewire with holmes-kit init.'] };
95
+ }
96
+ }
97
+ return { status: 'pass', detail: `MCP server ${loaded} matches its install${harness !== undefined ? ' and the observed hooks' : ''}.`, actions: [] };
98
+ }
80
99
  function inspectWorkspacePreflight(input) {
81
100
  const out = { schema: 'holmes-workspace-preflight/1', requestedRoot: null,
82
101
  boundRoot: null, boundSpecsRoot: null, binding: 'invalid', identity: null, checkout: null, checks: [], nextActions: [] };
@@ -124,6 +143,10 @@ function inspectWorkspacePreflight(input) {
124
143
  const e = enforcementCheck(out.boundRoot, input.harness, input.now ?? Date.now());
125
144
  check('runtime-enforcement', e.status, e.detail, e.actions);
126
145
  }
146
+ if (input.server !== undefined) {
147
+ const m = mcpBuildCheck(out.boundRoot, input.server, input.harness, input.now ?? Date.now());
148
+ check('mcp-build', m.status, m.detail, m.actions);
149
+ }
127
150
  return out;
128
151
  }
129
152
  catch (e) {
@@ -108,6 +108,11 @@ export declare function gateRange(root: string, base: string, head: string, opts
108
108
  ok: boolean;
109
109
  reasons: string[];
110
110
  };
111
+ /**
112
+ * @implements A-SPEC-102.10 — the run's review rounds that failed: independent `fail` verdicts on the run's base, across
113
+ * every head the remediation moved to. Returned oldest first, so the last carries the findings still unresolved.
114
+ */
115
+ export declare function failingRounds(main: string, base: string): VerdictRecord[];
111
116
  export declare function rangeStatus(root: string, base: string, head: string): {
112
117
  base: string;
113
118
  head: string;
@@ -42,8 +42,9 @@ exports.authorRuns = authorRuns;
42
42
  exports.readVerdicts = readVerdicts;
43
43
  exports.recordVerdict = recordVerdict;
44
44
  exports.gateRange = gateRange;
45
+ exports.failingRounds = failingRounds;
45
46
  exports.rangeStatus = rangeStatus;
46
- // @implements A-SPEC-102.2, A-SPEC-102.7, A-SPEC-102.8, A-SPEC-779.6
47
+ // @implements A-SPEC-102.2, A-SPEC-102.7, A-SPEC-102.8, A-SPEC-779.6, A-SPEC-102.10
47
48
  /**
48
49
  * @implements A-SPEC-102.2 — a review is a verdict that names who reviewed which commits. The ledger lives in the main
49
50
  * checkout (`.ax/reviews/verdicts.jsonl`, append-only), so a review recorded in a worktree outlives the worktree. A
@@ -345,6 +346,20 @@ function gateRange(root, base, head, opts) {
345
346
  reasons.push(`${open.important} open important finding(s)`);
346
347
  return { ok: reasons.length === 0, reasons };
347
348
  }
349
+ /**
350
+ * @implements A-SPEC-102.10 — the run's review rounds that failed: independent `fail` verdicts on the run's base, across
351
+ * every head the remediation moved to. Returned oldest first, so the last carries the findings still unresolved.
352
+ */
353
+ function failingRounds(main, base) {
354
+ let all;
355
+ try {
356
+ all = readVerdicts(main);
357
+ }
358
+ catch {
359
+ return [];
360
+ }
361
+ return all.filter((v) => v.independent && v.verdict === 'fail' && v.base === base);
362
+ }
348
363
  function rangeStatus(root, base, head) {
349
364
  const range = resolveRange(root, base, head);
350
365
  if ('error' in range)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.38.0",
4
+ "version": "0.39.0",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",