@holmes-lab/holmes-kit 0.37.2 → 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 (59) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +17 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +2 -1
  5. package/dist/holmes/cli/approve.d.ts +1 -0
  6. package/dist/holmes/cli/approve.js +36 -4
  7. package/dist/holmes/cli/autonomy.d.ts +28 -0
  8. package/dist/holmes/cli/autonomy.js +62 -8
  9. package/dist/holmes/cli/doctor.js +12 -1
  10. package/dist/holmes/cli/index.js +64 -5
  11. package/dist/holmes/cli/mcp-processes.d.ts +32 -0
  12. package/dist/holmes/cli/mcp-processes.js +132 -0
  13. package/dist/holmes/cli/run-provision.d.ts +6 -0
  14. package/dist/holmes/cli/run-provision.js +114 -0
  15. package/dist/holmes/cli/run.d.ts +5 -0
  16. package/dist/holmes/cli/run.js +38 -6
  17. package/dist/holmes/cli/runtime-binding-approval.js +2 -3
  18. package/dist/holmes/governance/approval-queue.d.ts +12 -1
  19. package/dist/holmes/governance/approval-queue.js +23 -28
  20. package/dist/holmes/governance/autonomy.d.ts +3 -1
  21. package/dist/holmes/governance/autonomy.js +28 -2
  22. package/dist/holmes/governance/full-autonomy.d.ts +72 -0
  23. package/dist/holmes/governance/full-autonomy.js +308 -0
  24. package/dist/holmes/governance/tool-actions.js +2 -0
  25. package/dist/holmes/guardrail/operator-person.js +3 -2
  26. package/dist/holmes/guardrail/refusal-codes.js +19 -4
  27. package/dist/holmes/guardrail/risk-classifier.js +21 -3
  28. package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
  29. package/dist/holmes/guardrail/run-refusals.js +19 -12
  30. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  31. package/dist/holmes/guardrail/run-stages.js +23 -3
  32. package/dist/holmes/guardrail/write-target.js +4 -1
  33. package/dist/holmes/hooks/pre-tool-use.d.ts +2 -0
  34. package/dist/holmes/hooks/pre-tool-use.js +88 -11
  35. package/dist/holmes/hooks/session-start.d.ts +5 -0
  36. package/dist/holmes/hooks/session-start.js +29 -1
  37. package/dist/holmes/hooks/stop.js +6 -4
  38. package/dist/holmes/mcp/elicit-approval.js +5 -6
  39. package/dist/holmes/mcp/handlers/approval-ask.d.ts +11 -0
  40. package/dist/holmes/mcp/handlers/approval-ask.js +18 -3
  41. package/dist/holmes/mcp/handlers/review-verdict.js +3 -2
  42. package/dist/holmes/mcp/handlers/spec-approval.d.ts +2 -0
  43. package/dist/holmes/mcp/handlers/spec-approval.js +23 -5
  44. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
  45. package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
  46. package/dist/holmes/mcp/handlers.d.ts +12 -0
  47. package/dist/holmes/mcp/handlers.js +25 -3
  48. package/dist/holmes/mcp/operator-recovery.d.ts +7 -2
  49. package/dist/holmes/mcp/operator-recovery.js +15 -58
  50. package/dist/holmes/mcp/server-staleness.d.ts +43 -0
  51. package/dist/holmes/mcp/server-staleness.js +158 -0
  52. package/dist/holmes/mcp/server.js +26 -2
  53. package/dist/holmes/mcp/tool-schemas.js +14 -1
  54. package/dist/holmes/project/workspace-preflight.d.ts +5 -0
  55. package/dist/holmes/project/workspace-preflight.js +24 -1
  56. package/dist/holmes/review/verdicts.d.ts +5 -0
  57. package/dist/holmes/review/verdicts.js +16 -1
  58. package/package.json +1 -1
  59. package/playbooks/promote-slice/PLAYBOOK.md +2 -1
@@ -1,13 +1,21 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.createWorkspacePreflightHandlers = createWorkspacePreflightHandlers;
4
- // @implements A-SPEC-703, A-SPEC-772.1
4
+ // @implements A-SPEC-703, A-SPEC-772.1, A-SPEC-251.4
5
5
  const agents_1 = require("../../cli/agents");
6
6
  const workspace_preflight_1 = require("../../project/workspace-preflight");
7
7
  function createWorkspacePreflightHandlers(context) {
8
8
  return { async workspace_preflight(a) {
9
9
  if (a?.harness !== undefined && !agents_1.AGENTS.includes(a.harness))
10
10
  throw new Error('Unsupported harness.');
11
- return (0, workspace_preflight_1.inspectWorkspacePreflight)({ requestedRoot: a?.root, storeRoot: context.storeRoot, ...(a?.harness !== undefined ? { harness: a.harness } : {}) });
11
+ let server;
12
+ try {
13
+ server = context.server?.();
14
+ }
15
+ catch {
16
+ server = undefined;
17
+ }
18
+ return (0, workspace_preflight_1.inspectWorkspacePreflight)({ requestedRoot: a?.root, storeRoot: context.storeRoot, ...(a?.harness !== undefined ? { harness: a.harness } : {}),
19
+ ...(server !== undefined ? { server } : {}) });
12
20
  } };
13
21
  }
@@ -3,6 +3,7 @@ import { Spec } from '../spec/spec-parser';
3
3
  import { ScannedFile } from '../cpg/cpg-scanner';
4
4
  import { type DecisionRecord, type DecisionCitation } from '../rtm/rtm-builder';
5
5
  import { Basis } from './basis';
6
+ import { StaleFact } from './server-staleness';
6
7
  import { Approval } from '../guardrail/risk-gate';
7
8
  import { Elicitor } from './elicit-approval';
8
9
  import { ApprovalContinuationStore } from './approval-commit';
@@ -61,6 +62,12 @@ export interface ElicitOpts {
61
62
  home?: string;
62
63
  installerPackageRoot?: string;
63
64
  };
65
+ /** @implements A-SPEC-792.4 — the home whose `.holmes/full-autonomy.json` spec_approve reads (default: the user's). */
66
+ fullAutonomyHome?: () => string;
67
+ /** @implements A-SPEC-251.4 — whether the install this process loaded has changed under it (null: unchanged or unread). */
68
+ serverStaleness?: () => StaleFact | null;
69
+ /** @implements A-SPEC-779.7 — this server's instance id (`<pid>:<startedAt>`): the requester key approval_withdraw checks. */
70
+ serverInstance?: () => string | undefined;
64
71
  }
65
72
  /**
66
73
  * @implements A-SPEC-299
@@ -391,6 +398,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
391
398
  root?: string;
392
399
  id: string;
393
400
  }) => Promise<Record<string, unknown>>;
401
+ approval_withdraw: (a: {
402
+ root?: string;
403
+ id: string;
404
+ reason: string;
405
+ }) => Promise<Record<string, unknown>>;
394
406
  review_verdict: (a: {
395
407
  root?: string;
396
408
  base: string;
@@ -39,7 +39,7 @@ exports.isHandlerRefusal = isHandlerRefusal;
39
39
  exports.unreadableAmong = unreadableAmong;
40
40
  exports.makeHandlers = makeHandlers;
41
41
  exports.collectDecisions = collectDecisions;
42
- // @implements A-SPEC-774.25, A-SPEC-770.12, A-SPEC-718.1, A-SPEC-718.2, A-SPEC-723, A-SPEC-723.1, A-SPEC-545.6, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754
42
+ // @implements A-SPEC-251.4, A-SPEC-774.25, A-SPEC-770.12,A-SPEC-718.1, A-SPEC-718.2, A-SPEC-723, A-SPEC-723.1, A-SPEC-545.6, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754, A-SPEC-792.4
43
43
  const operator_recovery_1 = require("./operator-recovery");
44
44
  // @implements A-SPEC-643
45
45
  // @implements A-SPEC-642
@@ -122,6 +122,7 @@ const cachedScanWithReport = (root, repoRoot = root) => {
122
122
  return { scanned, skipped: scanner.scanSkipped() };
123
123
  };
124
124
  const basis_1 = require("./basis");
125
+ const server_staleness_1 = require("./server-staleness");
125
126
  const write_target_1 = require("../guardrail/write-target");
126
127
  const spec_store_1 = require("../spec/spec-store");
127
128
  const risk_gate_1 = require("../guardrail/risk-gate");
@@ -556,6 +557,8 @@ async function deriveChangedContext(store, rootArg, a, toolName) {
556
557
  * information, and mtime would manufacture divergence on a checkout or a copy.
557
558
  */
558
559
  const LOADED_BUILD = (0, basis_1.loadedBuildId)(path.resolve(__dirname, '..', '..', '..'));
560
+ /** @implements A-SPEC-251.4 — the version this process loaded, read once beside the build id. */
561
+ const SERVER_VERSION = (0, server_staleness_1.readInstallIdentity)(path.resolve(__dirname, '..', '..', '..'))?.version ?? 'unknown';
559
562
  /**
560
563
  * @implements A-SPEC-299
561
564
  * Ids that were written but cannot be read back. The store drops documents it cannot parse, so
@@ -583,7 +586,21 @@ function makeHandlers(store, opts) {
583
586
  throw e;
584
587
  }
585
588
  };
586
- wrapped[name] = (0, basis_1.withBasis)(scoped, (a) => basisFor(diagnostic ? undefined : a?.root));
589
+ const based = (0, basis_1.withBasis)(scoped, (a) => basisFor(diagnostic ? undefined : a?.root));
590
+ // @implements A-SPEC-251.4 — a server whose install changed under it says so on every result (objects only, as basis).
591
+ wrapped[name] = opts?.serverStaleness === undefined ? based : async (a) => {
592
+ const out = await based(a);
593
+ if (out === null || typeof out !== 'object' || Array.isArray(out))
594
+ return out;
595
+ let stale = null;
596
+ try {
597
+ stale = opts.serverStaleness();
598
+ }
599
+ catch {
600
+ stale = null;
601
+ }
602
+ return stale === null ? out : { ...out, serverStale: (0, server_staleness_1.staleNotice)(stale) };
603
+ };
587
604
  }
588
605
  wrapped.basis_detail = async (a) => {
589
606
  const b = basisFor(a?.root, true);
@@ -877,6 +894,7 @@ function makeRawHandlers(store, opts) {
877
894
  clientName: () => opts?.clientName?.() ?? 'unknown',
878
895
  attestation,
879
896
  env: () => process.env,
897
+ serverInstance: () => opts?.serverInstance?.(), // @implements A-SPEC-779.7
880
898
  };
881
899
  const approvalAsk = (0, approval_ask_1.createApprovalAskHandlers)(formContext);
882
900
  // @implements A-SPEC-102.9 — the person's review verdict, answered in the same form.
@@ -929,6 +947,7 @@ function makeRawHandlers(store, opts) {
929
947
  resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
930
948
  refusalQueueHint: (root, request) => refusalQueueHint(root, store, request, 'spec_approve'),
931
949
  foreignRootReason: (root) => foreignRootReason(store, root),
950
+ ...(opts?.fullAutonomyHome ? { fullAutonomyHome: opts.fullAutonomyHome } : {}), // @implements A-SPEC-792.4
932
951
  });
933
952
  /**
934
953
  * Where the audit record for a governance act belongs — resolved BEFORE the act writes anything.
@@ -1081,7 +1100,9 @@ function makeRawHandlers(store, opts) {
1081
1100
  // citation_pin+4, phase_check+3, cpg_scan+3, taint_scan..issue_localize, test_run+3, issue_localize+3,
1082
1101
  // rtm_impact+4, rtm_reindex..review_record, review_prepare..risk_check, risk_check±, and the tail).
1083
1102
  ledger_reconcile: operatorInspection.ledger_reconcile,
1084
- ...(0, workspace_preflight_1.createWorkspacePreflightHandlers)({ storeRoot: store instanceof spec_store_1.LocalMarkdownRepository ? store.specsRoot : undefined }),
1103
+ ...(0, workspace_preflight_1.createWorkspacePreflightHandlers)({ storeRoot: store instanceof spec_store_1.LocalMarkdownRepository ? store.specsRoot : undefined,
1104
+ // @implements A-SPEC-251.4 — the server's own loaded identity and staleness, for the mcp-build check.
1105
+ server: () => ({ loaded: { version: SERVER_VERSION, buildId: LOADED_BUILD }, stale: opts?.serverStaleness?.() ?? null }) }),
1085
1106
  // @implements A-SPEC-752.10 — same unpinned slot. Re-applies the registered binding on the owner's answer in the
1086
1107
  // dialog; never autonomous.
1087
1108
  ...(0, runtime_binding_tool_1.createRuntimeBindingToolHandlers)({
@@ -1096,6 +1117,7 @@ function makeRawHandlers(store, opts) {
1096
1117
  // @implements A-SPEC-700.2 — same unpinned slot: `spec_retire..spec_unseal` is a pinned run.
1097
1118
  spec_reconcile: specLifecycle.spec_reconcile,
1098
1119
  approval_ask: approvalAsk.approval_ask, // @implements A-SPEC-718.4 — a slot no pinned key order covers
1120
+ approval_withdraw: approvalAsk.approval_withdraw, // @implements A-SPEC-779.7
1099
1121
  review_verdict: reviewVerdict.review_verdict, // @implements A-SPEC-102.9
1100
1122
  rtm_impact: graphOperations.rtm_impact,
1101
1123
  rtm_reindex: graphOperations.rtm_reindex,
@@ -1,4 +1,10 @@
1
- /** Formatting only: the caller must return pending text only after a successful enqueue. */
1
+ /**
2
+ * Formatting only: the caller must return pending text only after a successful enqueue.
3
+ *
4
+ * @implements A-SPEC-792.1 — the hint names no command to type. The operator lines it used to carry (`approve --grant`,
5
+ * `approve --watch`, A-SPEC-532.3) were relayed by agents and typed by the person in a terminal — the UX REQ-792 removes.
6
+ * `platform`, `executable` and `cli` once built that command; they are accepted and no longer used.
7
+ */
2
8
  export declare function operatorRecovery(root: string, target: string, operation?: string, options?: {
3
9
  platform?: NodeJS.Platform;
4
10
  executable?: string;
@@ -6,6 +12,5 @@ export declare function operatorRecovery(root: string, target: string, operation
6
12
  /** @implements A-SPEC-770.12 — `requestLabel(kind, target, title)`, set inside the bracket after the id. */
7
13
  label?: string;
8
14
  }): {
9
- reviewCommand: string;
10
15
  pendingHint(id: string): string;
11
16
  };
@@ -1,70 +1,27 @@
1
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
- })();
2
+ // @implements A-SPEC-754, A-SPEC-768, A-SPEC-770.12, A-SPEC-792.1
35
3
  Object.defineProperty(exports, "__esModule", { value: true });
36
4
  exports.operatorRecovery = operatorRecovery;
37
- // @implements A-SPEC-754, A-SPEC-532.3, A-SPEC-768, A-SPEC-770.12
38
- const path = __importStar(require("node:path"));
39
- const unsafeDisplay = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
40
- function literal(value, platform) {
41
- return platform === 'win32' ? `'${value.replace(/'/g, "''")}'` : `'${value.replace(/'/g, `'\\''`)}'`;
42
- }
43
- /** Formatting only: the caller must return pending text only after a successful enqueue. */
5
+ /**
6
+ * Formatting only: the caller must return pending text only after a successful enqueue.
7
+ *
8
+ * @implements A-SPEC-792.1 — the hint names no command to type. The operator lines it used to carry (`approve --grant`,
9
+ * `approve --watch`, A-SPEC-532.3) were relayed by agents and typed by the person in a terminal — the UX REQ-792 removes.
10
+ * `platform`, `executable` and `cli` once built that command; they are accepted and no longer used.
11
+ */
44
12
  function operatorRecovery(root, target, operation, options) {
13
+ void root;
45
14
  const label = options?.label ?? '';
46
- const platform = options?.platform ?? process.platform;
47
- const executable = options?.executable ?? process.execPath;
48
- // Both src/holmes/mcp (tests) and dist/holmes/mcp (installed) have the same depth.
49
- const cli = options?.cli ?? path.resolve(__dirname, '../../..', 'bin/holmes-kit.js');
50
- const commandSafe = [root, executable, cli].every(value => value.length > 0 && value.length <= 2048 && !unsafeDisplay.test(value));
51
- const command = commandSafe ? `${platform === 'win32' ? '& ' : ''}${literal(executable, platform)} ${literal(cli, platform)} approve --target ${literal(root, platform)}` : '';
52
- const display = (value) => JSON.stringify(value.slice(0, 300)).replace(/[\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
15
+ const display = (value) => JSON.stringify(value.slice(0, 300)).replace(/[\u007f-\u009f‪-‮⁦-⁩]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
53
16
  return {
54
- reviewCommand: command || 'the installed Holmes-Kit approval UI (path cannot be safely displayed; no command emitted)',
55
17
  pendingHint(id) {
56
18
  if (!/^req-[a-f0-9]{12}$/.test(id))
57
19
  return '';
58
- if (!command)
59
- return `\n[승인 대기 ${id}${label}] The request was recorded. Use the installed approval UI; a path exceeds the safe command display limit. No truncated command is provided.`;
60
- // @implements A-SPEC-532.3 — the resident surface is offered beside the one-off command (owner, 2026-10-04:
61
- // "why am I still pasting commands"): one key per arriving request.
62
- // @implements A-SPEC-768 — the three lines above are the operator's; measured 2026-10-11 (HG arm) the agent read
63
- // "keep the approval surface open" as its own instruction and polled a sealed spec 58 times. One line is the agent's.
64
- return `\n[승인 대기 ${id}${label}] 운영자: ${command} --grant ${literal(id, platform)}`
65
- + `\nOr keep the approval surface open and decide each arriving request with one key: ${command} --watch`
66
- + `\nAfter official approval, retry ${operation ? display(operation) : 'the original MCP operation'} for target ${display(target)} in the same workspace. Do not retry until approval is available.`
67
- // @implements A-SPEC-718.5 — the in-session route first: the person answers the form, nobody types a command.
20
+ // @implements A-SPEC-768 — one line is the agent's; measured 2026-10-11 (HG arm) an agent read an operator line as
21
+ // its own instruction and polled a sealed spec 58 times.
22
+ return `\n[승인 대기 ${id}${label}] The request was recorded.`
23
+ + `\nAfter approval, retry ${operation ? display(operation) : 'the original MCP operation'} for target ${display(target)} in the same workspace. Do not retry until approval is available.`
24
+ // @implements A-SPEC-718.5 — the in-session route: the person answers the form, nobody types a command.
68
25
  + `\nAgent: call approval_ask with id "${id}" — the person decides in this session's approval form; after granted, retry once.`
69
26
  + ' Otherwise check approval_status for the target; sealed:true or request.state granted means retry now — polling a sealed spec is wasted; request.state held carries the operator\'s question.';
70
27
  },
@@ -0,0 +1,43 @@
1
+ export interface InstallIdentity {
2
+ version: string;
3
+ buildId: string;
4
+ }
5
+ export interface StaleFact {
6
+ loaded: InstallIdentity;
7
+ onDisk: InstallIdentity;
8
+ pid: number;
9
+ startedAt: string;
10
+ fix: string;
11
+ }
12
+ export interface StaleNotice {
13
+ loaded: string;
14
+ onDisk: string;
15
+ fix: string;
16
+ }
17
+ export interface McpBeat {
18
+ schema: 'holmes-mcp-heartbeat/1';
19
+ client: string;
20
+ pid: number;
21
+ version: string;
22
+ buildId: string;
23
+ packageRoot: string;
24
+ startedAt: string;
25
+ at: string;
26
+ }
27
+ export declare const MCP_HEARTBEAT_DIR: string;
28
+ /** The package root's version and build id, or null when the version cannot be read (absence is not staleness). */
29
+ export declare function readInstallIdentity(pkgRoot: string): InstallIdentity | null;
30
+ /** At most one disk read per `everyMs` (default 30 s); the last answer is kept between reads. */
31
+ export declare function makeStalenessProbe(pkgRoot: string, loaded: InstallIdentity, opts?: {
32
+ now?: () => number;
33
+ everyMs?: number;
34
+ pid?: number;
35
+ startedAt?: string;
36
+ }): () => StaleFact | null;
37
+ export declare function staleNotice(f: StaleFact): StaleNotice;
38
+ /** Best effort: at most one write per client a minute; every failure is swallowed. */
39
+ export declare function writeMcpHeartbeat(projectRoot: string, beat: Omit<McpBeat, 'schema' | 'at'>, now: number): void;
40
+ /** Valid beats under `.ax/state/mcp-heartbeat`, each with whether its process is alive and the beat under 24 h old. */
41
+ export declare function readMcpHeartbeats(projectRoot: string, now: number): Array<McpBeat & {
42
+ alive: boolean;
43
+ }>;
@@ -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
  }
@@ -225,7 +225,7 @@ exports.TOOL_SCHEMAS = {
225
225
  },
226
226
  // @implements A-SPEC-718.4
227
227
  approval_ask: {
228
- description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as `holmes-kit approve --grant/--deny/--ask` would record it (actor `elicitation:<client>`), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
228
+ description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as the operator's grant, deny or question is recorded (actor `elicitation:<client>`), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
229
229
  inputSchema: {
230
230
  type: 'object',
231
231
  properties: {
@@ -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)