@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
@@ -42,6 +42,8 @@ exports.TOOL_ACTIONS = {
42
42
  approval_status: NONE, rtm_dashboard: NONE,
43
43
  // @implements A-SPEC-718.4 — the person decides in the form; the agent only asks, so no role act is the agent's.
44
44
  approval_ask: NONE,
45
+ // @implements A-SPEC-774 — approval_withdraw (A-SPEC-779.7) withdraws the server's own request and decides nothing.
46
+ approval_withdraw: NONE,
45
47
  // @implements A-SPEC-102.9 — it writes a review verdict, the act a role policy names RECORD_REVIEW.
46
48
  review_verdict: always('RECORD_REVIEW'),
47
49
  // approval_commit changes only the server's in-memory continuation; the act it completes is spec_approve's
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
- // @implements A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4, A-SPEC-792.1, A-SPEC-792.8
2
+ // @implements A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4, A-SPEC-792.1, A-SPEC-792.8, A-SPEC-792.9
3
3
  /**
4
4
  * @implements A-SPEC-777 — a refusal's kind, readable by a program. An orchestrator retries a `retryable` refusal,
5
5
  * pauses for a person on `needs_hitl`, and changes its plan on `permanent`. The prose stays for people; the line
@@ -118,6 +118,12 @@ exports.REFUSAL_CODES = [
118
118
  remediation: ['write a patch that applies to the file as it stands, with at least one + or - line', 'or use the Edit tool'],
119
119
  test: /the patch (?:does not apply|to\b)|patch tool or a patch marker/i,
120
120
  },
121
+ {
122
+ // @implements A-SPEC-792.9 — a spec write whose result the store cannot parse.
123
+ code: 'spec.unreadable', class: 'permanent',
124
+ remediation: ['fix the frontmatter in the same write: a value holding \' or : goes in double quotes, or in a >- block', 'or scaffold the spec again with spec_create'],
125
+ test: /unreadable to the spec store|the write would leave/i,
126
+ },
121
127
  {
122
128
  code: 'shell.code-write', class: 'permanent',
123
129
  remediation: ['write project code through the Edit or Write tool, not the shell'],
@@ -47,7 +47,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
47
47
  exports.classifySecret = classifySecret;
48
48
  exports.classifyBlastRadius = classifyBlastRadius;
49
49
  exports.assessRisk = assessRisk;
50
- // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4
50
+ // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4, A-SPEC-773.5
51
51
  const fs = __importStar(require("node:fs"));
52
52
  const path = __importStar(require("node:path"));
53
53
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -1800,10 +1800,28 @@ function classifyReversibility(action) {
1800
1800
  const raw = action.command ?? '';
1801
1801
  const joined = raw === '' ? raw : (0, write_target_2.joinShellText)(raw);
1802
1802
  if (joined === raw)
1803
- return classifyReversibilityAsWritten(action);
1803
+ return withAxCwdNote(classifyReversibilityAsWritten(action), action);
1804
1804
  const a = classifyReversibilityAsWritten(action);
1805
1805
  const b = classifyReversibilityAsWritten({ ...action, command: joined });
1806
- return (0, risk_types_1.maxLevel)(a.level, b.level) === a.level ? a : b;
1806
+ return withAxCwdNote((0, risk_types_1.maxLevel)(a.level, b.level) === a.level ? a : b, action);
1807
+ }
1808
+ /**
1809
+ * @implements A-SPEC-773.5 — G0 round 5: an agent left in .ax/specs by one `cd … && find` had six later commands refused
1810
+ * over .ax (pytest included) with no cause named. The verdict is unchanged; the first .ax reason names the working
1811
+ * directory and the one command that leaves it. Containment is by path, so `.axolotl` is not inside.
1812
+ */
1813
+ function withAxCwdNote(verdict, action) {
1814
+ if (verdict.level !== 'hard-hitl' || !action.cwd || !action.projectRoot)
1815
+ return verdict;
1816
+ const rel = path.relative(path.join(action.projectRoot, '.ax'), action.cwd);
1817
+ if (rel.startsWith('..') || path.isAbsolute(rel))
1818
+ return verdict;
1819
+ const i = verdict.reasons.findIndex((r) => /protected \.ax governance path/.test(r));
1820
+ if (i < 0)
1821
+ return verdict;
1822
+ const where = path.relative(action.projectRoot, action.cwd);
1823
+ const note = `; this shell's working directory (${where}) is inside .ax, so every command run there is judged over .ax: run \`cd ${action.projectRoot}\` on its own first, then the command`;
1824
+ return { ...verdict, reasons: verdict.reasons.map((r, j) => (j === i ? r + note : r)) };
1807
1825
  }
1808
1826
  function classifyReversibilityAsWritten(action) {
1809
1827
  const axis = 'reversibility';
@@ -4,7 +4,11 @@ type Install = {
4
4
  };
5
5
  export interface RunRefusalEvent {
6
6
  ts: string;
7
- event: 'refusal' | 'awaiting_approval' | 'approval_resolved' | 'approval_expired' | 'install_changed' | 'stage' | 'versions_accepted' | 'stages_interpreted' | 'stop_blocked' | 'stalled';
7
+ event: 'refusal' | 'awaiting_approval' | 'approval_resolved' | 'approval_expired' | 'install_changed' | 'stage' | 'versions_accepted' | 'stages_interpreted' | 'stop_blocked' | 'stalled' | 'review_unresolved';
8
+ /** @implements A-SPEC-102.10 — on `review_unresolved`: the cap, the range, and the last failing round's findings. */
9
+ cap?: number;
10
+ range?: string;
11
+ findings?: string[];
8
12
  /** @implements A-SPEC-778.1 — the constitution articles a blocked Stop named. */
9
13
  articles?: string[];
10
14
  /** @implements A-SPEC-778.1 — on `stalled`: how many Stops in a row were blocked. */
@@ -44,6 +48,7 @@ type Stop = {
44
48
  current: Install;
45
49
  };
46
50
  articles?: string[];
51
+ findings?: string[];
47
52
  };
48
53
  /** The first code refused `limit` times or more, with its count, the expired approval wait, or an install change; else null. */
49
54
  export declare function stoppedBy(events: readonly RunRefusalEvent[], limit: number): Stop | null;
@@ -45,7 +45,7 @@ exports.applyRunRefusalStop = applyRunRefusalStop;
45
45
  exports.recordRunStopBlock = recordRunStopBlock;
46
46
  exports.runState = runState;
47
47
  exports.grantGuard = grantGuard;
48
- // @implements A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781, A-SPEC-780.1, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-770.12, A-SPEC-778.1, A-SPEC-779.2, A-SPEC-792.1
48
+ // @implements A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781, A-SPEC-780.1, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-770.12, A-SPEC-778.1, A-SPEC-779.2, A-SPEC-792.1, A-SPEC-102.10
49
49
  /**
50
50
  * @implements A-SPEC-778 — a refusal loop in a run ends in a stop the orchestrator can read, not in a used-up budget.
51
51
  * Every PreToolUse refusal of a run is appended to `<main>/.ax/state/run-refusals/<run>.jsonl` (a protected path the
@@ -112,6 +112,10 @@ function stoppedBy(events, limit) {
112
112
  const stalled = events.find((e) => e.event === 'stalled');
113
113
  if (stalled)
114
114
  return { code: 'run.stalled', count: stalled.count ?? 0, articles: stalled.articles ?? [] };
115
+ // @implements A-SPEC-102.10 — review rounds reached the run's cap with findings unresolved: the run stops for good.
116
+ const unresolved = events.find((e) => e.event === 'review_unresolved');
117
+ if (unresolved)
118
+ return { code: 'review.unresolved', count: unresolved.count ?? 0, findings: unresolved.findings ?? [] };
115
119
  const expired = events.find((e) => e.event === 'approval_expired');
116
120
  if (expired)
117
121
  return { code: 'approval.expired', count: 1, expired: expired.request ?? '' };
@@ -189,12 +193,14 @@ function appendRunEvent(main, runId, ev) {
189
193
  const stallLine = (count, articles) => `[Holmes-Kit] this run stalled: its Stop was blocked ${count} times in a row (${articles.join(', ') || 'no article named'}) — the turn ends blocked; ${END}`;
190
194
  const stopReason = (stop, limit, waitMinutes) => stop.code === 'run.stalled'
191
195
  ? stallLine(stop.count, stop.articles ?? [])
192
- : stop.install !== undefined
193
- ? `[Holmes-Kit] this run stopped: the Holmes install changed since run start (pinned ${stop.install.pinned.version ?? '?'} build ${stop.install.pinned.build ?? '?'}, `
194
- + `now ${stop.install.current.version ?? 'unreadable'} build ${stop.install.current.build ?? 'unreadable'}) — one build governs a run; ${END}`
195
- : stop.expired !== undefined
196
- ? `[Holmes-Kit] this run stopped: approval ${stop.expired} was not decided within ${waitMinutes} minutes — ${END}`
197
- : `[Holmes-Kit] this run stopped: refusal ${stop.code} repeated ${stop.count} times (limit ${limit}) — ${END}`;
196
+ : stop.code === 'review.unresolved'
197
+ ? `[Holmes-Kit] this run stopped: review.unresolved — ${stop.count} failing independent review round(s) reached the run's cap; unresolved: ${(stop.findings ?? []).slice(0, 3).join(' | ') || 'none named'} — ${END}`
198
+ : stop.install !== undefined
199
+ ? `[Holmes-Kit] this run stopped: the Holmes install changed since run start (pinned ${stop.install.pinned.version ?? '?'} build ${stop.install.pinned.build ?? '?'}, `
200
+ + `now ${stop.install.current.version ?? 'unreadable'} build ${stop.install.current.build ?? 'unreadable'}) — one build governs a run; ${END}`
201
+ : stop.expired !== undefined
202
+ ? `[Holmes-Kit] this run stopped: approval ${stop.expired} was not decided within ${waitMinutes} minutes — ${END}`
203
+ : `[Holmes-Kit] this run stopped: refusal ${stop.code} repeated ${stop.count} times (limit ${limit}) — ${END}`;
198
204
  /** The decision recorded for `request` at or after `since`, read from the queue it was filed in; null when undecided. */
199
205
  function decisionAfter(queueRoot, request, since) {
200
206
  try {
@@ -28,6 +28,11 @@ export declare function applyRoleStage(out: Decision, ctx: {
28
28
  toolInput: Record<string, unknown>;
29
29
  }): Decision;
30
30
  export declare function currentStage(main: string, runId: string, machine: StageMachine): string;
31
+ /** @implements A-SPEC-102.10 — the review policy recorded at run start; anything unreadable is no policy. */
32
+ export declare function reviewPolicyOf(rec: unknown): {
33
+ rounds?: number;
34
+ strict: boolean;
35
+ };
31
36
  export declare function transitionRun(main: string, runId: string, to: string, opts: {
32
37
  key: string;
33
38
  why?: string;
@@ -37,8 +37,9 @@ exports.TRANSITION_CHECKS = void 0;
37
37
  exports.applyStageGate = applyStageGate;
38
38
  exports.applyRoleStage = applyRoleStage;
39
39
  exports.currentStage = currentStage;
40
+ exports.reviewPolicyOf = reviewPolicyOf;
40
41
  exports.transitionRun = transitionRun;
41
- // @implements A-SPEC-781, A-SPEC-781.1, A-SPEC-774.19, A-SPEC-781.2
42
+ // @implements A-SPEC-781, A-SPEC-781.1, A-SPEC-774.19, A-SPEC-781.2, A-SPEC-102.10
42
43
  /**
43
44
  * @implements A-SPEC-781 — a run's SDLC stage is recorded state. Only the holder of the run's stop key (the
44
45
  * orchestrator; the session inside the run never sees it) moves it, along the edges the project's machine declares,
@@ -133,6 +134,12 @@ function currentStage(main, runId, machine) {
133
134
  }
134
135
  return machine.order[0];
135
136
  }
137
+ /** @implements A-SPEC-102.10 — the review policy recorded at run start; anything unreadable is no policy. */
138
+ function reviewPolicyOf(rec) {
139
+ const r = rec?.review;
140
+ const rounds = typeof r?.rounds === 'number' && Number.isInteger(r.rounds) && r.rounds >= 1 && r.rounds <= 20 ? r.rounds : undefined;
141
+ return { ...(rounds !== undefined ? { rounds } : {}), strict: r?.strict === true };
142
+ }
136
143
  function transitionRun(main, runId, to, opts) {
137
144
  const rec = (0, run_records_1.listRuns)(main).find((r) => r.run_id === runId);
138
145
  if (!rec)
@@ -154,9 +161,22 @@ function transitionRun(main, runId, to, opts) {
154
161
  const range = (0, verdicts_1.resolveRange)(rec.worktree, rec.base, 'HEAD');
155
162
  if ('error' in range)
156
163
  return { ok: false, reason: range.error };
157
- const g = (0, verdicts_1.gateRange)(rec.worktree, range.base, range.head, {});
158
- if (!g.ok)
164
+ // @implements A-SPEC-102.10 — the run's recorded policy: strict review, and a cap on failing rounds.
165
+ const policy = reviewPolicyOf(rec);
166
+ const g = (0, verdicts_1.gateRange)(rec.worktree, range.base, range.head, { strict: policy.strict });
167
+ if (!g.ok) {
168
+ const capRounds = policy.rounds ?? null;
169
+ const failed = capRounds !== null ? (0, verdicts_1.failingRounds)(main, rec.base) : [];
170
+ if (capRounds !== null && failed.length >= capRounds) {
171
+ const findings = (failed[failed.length - 1].findings ?? []).slice(0, 50).map((f) => String(f).slice(0, 300));
172
+ (0, run_refusals_1.appendRunEvent)(main, runId, {
173
+ ts: (opts.now ? opts.now() : new Date()).toISOString(), event: 'review_unresolved', count: failed.length, cap: capRounds,
174
+ range: `${range.base}..${range.head}`, findings,
175
+ });
176
+ return { ok: false, reason: `this run stopped: review.unresolved — ${failed.length} failing independent review round(s) reached the cap of ${capRounds}; unresolved: ${findings.slice(0, 3).join(' | ') || 'none named'} — ${to} is refused` };
177
+ }
159
178
  return { ok: false, reason: `${to} needs an independent passing review of ${range.base}..${range.head}: ${g.reasons.join('; ')}` };
179
+ }
160
180
  }
161
181
  // @implements A-SPEC-781.2 — the edge's conditions: a name nobody checks refuses; a slot is recorded as unchecked.
162
182
  const edge = `${from}->${to}`;
@@ -1961,7 +1961,10 @@ function evaluateHook(input, specsDir, opts) {
1961
1961
  // JSON key — was refused as an environment dump. The remaining alternatives
1962
1962
  // (`process.env`, `os.environ`, `ENVIRON`, `getenv`) name real environment access; Perl's
1963
1963
  // `%ENV`/`$ENV{…}` are the loss, and they are rarer than the false positives were.
1964
- tailAfterFirst(command, /\n/, /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php|awk|gawk)\b/i, /process\s*\.\s*env|os\s*\.\s*environ|from\s+os\s+import\s+environ|ENVIRON|getenv/i) ||
1964
+ // @implements A-SPEC-163.9 — `ENVIRON` under /i matched "environ" inside any word: G0 round 5 refused
1965
+ // `pytest … tests/test_environment.py` as a dump. It stands as a whole identifier now (environ, environb,
1966
+ // ENVIRON), which keeps `o.environ` after `import os as o`, `os.environb` and getattr(os, 'environ').
1967
+ tailAfterFirst(command, /\n/, /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php|awk|gawk)\b/i, /process\s*\.\s*env|os\s*\.\s*environ|from\s+os\s+import\s+environ|(?<![A-Za-z0-9_])environb?(?![A-Za-z0-9_])|getenv/i) ||
1965
1968
  // @implements A-SPEC-163
1966
1969
  // Perl's `$ENV{…}` and Ruby's bare `ENV` still have to be caught, but CASE-SENSITIVELY and
1967
1970
  // not after a dot. The old alternative was `\bENV\b` under /i, which also matched `s.env` —
@@ -2890,6 +2893,35 @@ function evaluateHook(input, specsDir, opts) {
2890
2893
  permissionDecisionReason: registry_1.MESSAGES.SEAL_APPROVED_SPEC_MUTATION(path.basename(p, '.md'), undefined, 'A-SPEC-132'),
2891
2894
  };
2892
2895
  }
2896
+ // @implements A-SPEC-792.9 — a write that would leave the spec unreadable is refused with the parse error, whatever
2897
+ // approval is held. G0 HB-r5: a Write broke REQ-100's YAML, the repair Edit was then refused as a new REQ (below),
2898
+ // and the run ended asking a person. A file already unreadable on disk is judged as before.
2899
+ {
2900
+ let disk = null;
2901
+ try {
2902
+ disk = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
2903
+ }
2904
+ catch {
2905
+ disk = null;
2906
+ }
2907
+ const parseError = (text) => {
2908
+ try {
2909
+ (0, spec_parser_1.parseSpec)(text);
2910
+ return null;
2911
+ }
2912
+ catch (e) {
2913
+ return String(e.message ?? e).split('\n')[0];
2914
+ }
2915
+ };
2916
+ const edited = editedResult(disk, input.tool_input);
2917
+ const broken = typeof edited === 'string' ? parseError(edited) : null;
2918
+ if (broken !== null && (disk === null || parseError(disk) === null)) {
2919
+ return {
2920
+ permissionDecision: 'deny',
2921
+ permissionDecisionReason: `[Holmes-Kit] the write would leave ${path.basename(p, '.md')} unreadable to the spec store (${broken}) — nothing was written; fix the frontmatter in this same write (a value holding ' or : goes in double quotes, or in a >- block)`,
2922
+ };
2923
+ }
2924
+ }
2893
2925
  // @implements A-SPEC-729 (round 4) — a NEW REQ enters the store only through spec_create(type=REQ)
2894
2926
  // or spec_slice_init, which spend ledger-issued triage evidence. A hand-written REQ file walked
2895
2927
  // around that intake entirely and could then be sealed (measured on 179b435b).
@@ -30,4 +30,9 @@ export declare function buildSessionStartOutput(input: SessionStartInput): Sessi
30
30
  * `upgrade`/`init --force`. Forward-drift + opt-out judgment is the pure `repinDecision`; every
31
31
  * failure returns '' (fail-open — a banner is never a gate).
32
32
  */
33
+ /**
34
+ * @implements A-SPEC-251.5 — one line when a holmes-kit MCP server running from this workspace's wired node install
35
+ * started before that install was upgraded. Fail-open: '' on any failure, never a gate.
36
+ */
37
+ export declare function staleWiredServerLine(cwd: string): string;
33
38
  export declare function driftNudge(cwd: string, installed: string, env: NodeJS.ProcessEnv): string;
@@ -35,8 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.detectInstallMode = detectInstallMode;
37
37
  exports.buildSessionStartOutput = buildSessionStartOutput;
38
+ exports.staleWiredServerLine = staleWiredServerLine;
38
39
  exports.driftNudge = driftNudge;
39
- // @implements A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1
40
+ // @implements A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1, A-SPEC-251.5
40
41
  // The SessionStart banner hook. It emits the intro (+ optional update notice) as additionalContext,
41
42
  // which Claude Code delivers to BOTH the human transcript and the agent context — the "human and
42
43
  // agent" delivery REQ-531 asks for. The update refresh is a DETACHED, fire-and-forget child so the
@@ -86,6 +87,26 @@ function pkgVersion() {
86
87
  * `upgrade`/`init --force`. Forward-drift + opt-out judgment is the pure `repinDecision`; every
87
88
  * failure returns '' (fail-open — a banner is never a gate).
88
89
  */
90
+ /**
91
+ * @implements A-SPEC-251.5 — one line when a holmes-kit MCP server running from this workspace's wired node install
92
+ * started before that install was upgraded. Fail-open: '' on any failure, never a gate.
93
+ */
94
+ function staleWiredServerLine(cwd) {
95
+ try {
96
+ const mcp = JSON.parse(fs.readFileSync(path.join(cwd, '.mcp.json'), 'utf8'));
97
+ const entry = mcp.mcpServers?.['holmes-kit'];
98
+ const bin = entry?.command === 'node' && typeof entry.args?.[0] === 'string' ? entry.args[0] : null;
99
+ if (bin === null || !/[\\/]bin[\\/]holmes-mcp\.js$/.test(bin))
100
+ return '';
101
+ const wiredRoot = path.dirname(path.dirname(path.resolve(cwd, bin)));
102
+ const { listProcessRows, staleMcpServers, readPackageInstall, mcpProcessBannerLine } = require('../cli/mcp-processes');
103
+ const rows = listProcessRows();
104
+ return rows === null ? '' : mcpProcessBannerLine(staleMcpServers(rows, readPackageInstall), wiredRoot);
105
+ }
106
+ catch {
107
+ return '';
108
+ }
109
+ }
89
110
  function driftNudge(cwd, installed, env) {
90
111
  try {
91
112
  const { mcpLaunchVersion } = require('../cli/mcp-version');
@@ -182,6 +203,13 @@ if (require.main === module) {
182
203
  out.hookSpecificOutput.additionalContext += notice;
183
204
  }
184
205
  catch { /* the banner is never a gate */ }
206
+ // @implements A-SPEC-251.5 — the wiring can match while a server from the wired install still runs older code.
207
+ try {
208
+ const line = staleWiredServerLine(process.cwd());
209
+ if (line)
210
+ out.hookSpecificOutput.additionalContext += '\n' + line;
211
+ }
212
+ catch { /* the banner is never a gate */ }
185
213
  // @implements A-SPEC-554.1 — remind the human of the current autonomy posture (surface only, the
186
214
  // headless hook never decides), and clean up an expired/invalid session marker. Fail-open.
187
215
  try {
@@ -65,7 +65,7 @@ exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
65
65
  exports.stopSharedScan = stopSharedScan;
66
66
  exports.scanCodeCycles = scanCodeCycles;
67
67
  exports.writeGuardCount = writeGuardCount;
68
- // @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1
68
+ // @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1, A-SPEC-102.10
69
69
  // @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
70
70
  const fs = __importStar(require("node:fs"));
71
71
  // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
@@ -468,7 +468,9 @@ function runReviewGate(root, env, cwd, sessionId) {
468
468
  return cannot(`the range ${rec.base}..HEAD does not resolve (${range.error})`, rec.base);
469
469
  if (range.head === range.base)
470
470
  return undefined;
471
- const g = gateRange(rec.worktree, range.base, range.head, {});
471
+ // @implements A-SPEC-102.10 — a strict run is judged strictly at Stop too.
472
+ const { reviewPolicyOf } = require('../guardrail/run-stages');
473
+ const g = gateRange(rec.worktree, range.base, range.head, { strict: reviewPolicyOf(rec).strict });
472
474
  return g.ok ? undefined : { base: range.base, head: range.head, reasons: g.reasons };
473
475
  }
474
476
  catch (e) {
@@ -8,6 +8,8 @@ export interface ApprovalAskContext {
8
8
  reason?: string;
9
9
  };
10
10
  env: () => NodeJS.ProcessEnv;
11
+ /** @implements A-SPEC-779.7 — this server's instance id, the requester key approval_withdraw checks. */
12
+ serverInstance?: () => string | undefined;
11
13
  }
12
14
  /** Clients whose form waits for the person in every mode measured (claude-code: forms expired unanswered, 2026-10-19). */
13
15
  export declare const FORM_WAITS_FOR_PERSON: ReadonlySet<string>;
@@ -16,4 +18,13 @@ export declare function createApprovalAskHandlers(context: ApprovalAskContext):
16
18
  root?: string;
17
19
  id: string;
18
20
  }): Promise<Record<string, unknown>>;
21
+ /**
22
+ * @implements A-SPEC-779.7 — the session withdraws a request its own MCP server filed: recorded as `withdrawn`, gone
23
+ * from the operator's inbox, never granted. Another session's request, and one filed by a hook or the CLI, is refused.
24
+ */
25
+ approval_withdraw(a: {
26
+ root?: string;
27
+ id: string;
28
+ reason: string;
29
+ }): Promise<Record<string, unknown>>;
19
30
  };
@@ -2,7 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.FORM_WAITS_FOR_PERSON = void 0;
4
4
  exports.createApprovalAskHandlers = createApprovalAskHandlers;
5
- // @implements A-SPEC-718.4, A-SPEC-792.1
5
+ // @implements A-SPEC-718.4, A-SPEC-792.1, A-SPEC-779.7
6
6
  /**
7
7
  * approval_ask — the person decides a pending request in the session's approval form, so no approval needs a typed
8
8
  * command (owner audit 2026-10-20). Since A-SPEC-779.4 neither the agent's shell nor the session's `!` can run
@@ -86,5 +86,19 @@ function createApprovalAskHandlers(context) {
86
86
  return { ok: false, id, reason: r.reason };
87
87
  return { ...base, decision: 'denied', reason: why, nextAction: 'Do not retry the act; the person denied it.' };
88
88
  },
89
+ /**
90
+ * @implements A-SPEC-779.7 — the session withdraws a request its own MCP server filed: recorded as `withdrawn`, gone
91
+ * from the operator's inbox, never granted. Another session's request, and one filed by a hook or the CLI, is refused.
92
+ */
93
+ async approval_withdraw(a) {
94
+ const root = context.rootOf(a.root);
95
+ const id = typeof a.id === 'string' ? a.id.trim() : '';
96
+ const reason = typeof a.reason === 'string' ? a.reason : '';
97
+ const server = context.serverInstance?.();
98
+ const r = (0, approve_1.withdrawRequest)(root, id, reason, { env: context.env(), cwd: root, ...(server ? { server } : {}) });
99
+ if (!r.ok)
100
+ return { ok: false, id, reason: r.reason };
101
+ return { ok: true, id, decision: 'withdrawn', nextAction: 'The request is closed; the operator will not see it. Do not retry the act it was filed for.' };
102
+ },
89
103
  };
90
104
  }
@@ -1,6 +1,11 @@
1
1
  import { Agent } from '../../cli/agents';
2
+ import type { InstallIdentity, StaleFact } from '../server-staleness';
2
3
  export declare function createWorkspacePreflightHandlers(context: {
3
4
  storeRoot?: string;
5
+ server?: () => {
6
+ loaded: InstallIdentity;
7
+ stale: StaleFact | null;
8
+ };
4
9
  }): {
5
10
  workspace_preflight(a: {
6
11
  root: string;
@@ -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';
@@ -63,6 +64,10 @@ export interface ElicitOpts {
63
64
  };
64
65
  /** @implements A-SPEC-792.4 — the home whose `.holmes/full-autonomy.json` spec_approve reads (default: the user's). */
65
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;
66
71
  }
67
72
  /**
68
73
  * @implements A-SPEC-299
@@ -393,6 +398,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
393
398
  root?: string;
394
399
  id: string;
395
400
  }) => Promise<Record<string, unknown>>;
401
+ approval_withdraw: (a: {
402
+ root?: string;
403
+ id: string;
404
+ reason: string;
405
+ }) => Promise<Record<string, unknown>>;
396
406
  review_verdict: (a: {
397
407
  root?: string;
398
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, A-SPEC-792.4
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.
@@ -1082,7 +1100,9 @@ function makeRawHandlers(store, opts) {
1082
1100
  // citation_pin+4, phase_check+3, cpg_scan+3, taint_scan..issue_localize, test_run+3, issue_localize+3,
1083
1101
  // rtm_impact+4, rtm_reindex..review_record, review_prepare..risk_check, risk_check±, and the tail).
1084
1102
  ledger_reconcile: operatorInspection.ledger_reconcile,
1085
- ...(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 }) }),
1086
1106
  // @implements A-SPEC-752.10 — same unpinned slot. Re-applies the registered binding on the owner's answer in the
1087
1107
  // dialog; never autonomous.
1088
1108
  ...(0, runtime_binding_tool_1.createRuntimeBindingToolHandlers)({
@@ -1097,6 +1117,7 @@ function makeRawHandlers(store, opts) {
1097
1117
  // @implements A-SPEC-700.2 — same unpinned slot: `spec_retire..spec_unseal` is a pinned run.
1098
1118
  spec_reconcile: specLifecycle.spec_reconcile,
1099
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
1100
1121
  review_verdict: reviewVerdict.review_verdict, // @implements A-SPEC-102.9
1101
1122
  rtm_impact: graphOperations.rtm_impact,
1102
1123
  rtm_reindex: graphOperations.rtm_reindex,
@@ -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
+ }>;