@holmes-lab/holmes-kit 0.35.19 → 0.35.21

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 (35) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/README.md +2 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents.js +13 -7
  5. package/dist/holmes/cli/codex-hooks.js +3 -1
  6. package/dist/holmes/cli/doctor.d.ts +12 -0
  7. package/dist/holmes/cli/doctor.js +194 -1
  8. package/dist/holmes/cli/init.js +2 -1
  9. package/dist/holmes/cli/runtime-binding.js +4 -3
  10. package/dist/holmes/cli/settings-merge.d.ts +1 -0
  11. package/dist/holmes/cli/settings-merge.js +6 -2
  12. package/dist/holmes/cpg/scan-cache.d.ts +12 -1
  13. package/dist/holmes/cpg/scan-cache.js +83 -2
  14. package/dist/holmes/hooks/adapters/antigravity.d.ts +2 -0
  15. package/dist/holmes/hooks/adapters/antigravity.js +8 -1
  16. package/dist/holmes/hooks/rtm-refresh-child.d.ts +43 -0
  17. package/dist/holmes/hooks/rtm-refresh-child.js +110 -10
  18. package/dist/holmes/hooks/rtm-refresh.d.ts +23 -0
  19. package/dist/holmes/hooks/rtm-refresh.js +124 -12
  20. package/dist/holmes/hooks/stop.d.ts +8 -0
  21. package/dist/holmes/hooks/stop.js +20 -5
  22. package/dist/holmes/mcp/handlers/graph-operations.js +7 -4
  23. package/dist/holmes/mcp/handlers/requirement-triage.js +6 -2
  24. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +7 -0
  25. package/dist/holmes/mcp/requirement-triage-evidence.js +18 -7
  26. package/dist/holmes/project/bounded-io.d.ts +1 -0
  27. package/dist/holmes/project/bounded-io.js +3 -1
  28. package/dist/holmes/refresh/freshness-coordinator.d.ts +28 -0
  29. package/dist/holmes/refresh/freshness-coordinator.js +85 -2
  30. package/dist/holmes/runtime/dispatch.js +5 -3
  31. package/dist/holmes/runtime/hook-process.d.ts +8 -0
  32. package/dist/holmes/runtime/hook-process.js +13 -1
  33. package/dist/holmes/semantic/embedder.d.ts +6 -0
  34. package/dist/holmes/semantic/embedder.js +10 -0
  35. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,109 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [Unreleased]
9
+
10
+ ## [0.35.21] - 2026-10-16
11
+
12
+ Upgrading: restart every session and MCP server (the MCP freshness bridge keeps its slow-git memory per process), and
13
+ run `holmes-kit runtime-binding setup` again so the hooks run this build. Then run `holmes-kit doctor`: a `stop hook
14
+ timeout` WARN naming a Codex plugin snapshot means that snapshot still carries a 30 s Stop.
15
+
16
+ ### Fixed
17
+
18
+ - **The background refresh survives a slow git, a failed spawn and a stepped clock** (A-SPEC-719.4, review rounds 1
19
+ and 2 of 719.1–719.3). A `git rev-parse` that did not answer within its bound no longer leases a null-HEAD generation
20
+ (which superseded the live worker and could never complete current): such a request joins the live lease, and
21
+ only with no live lease does it lease a null head as before (A-SPEC-719.6 — a git that refuses for good still
22
+ refreshes). A worker now ends from its 15-second watch only when its workspace is gone or a readable receipt names a newer
23
+ generation or a finished state — a momentarily unreadable receipt is read again. The detached spawn listens for
24
+ `'error'` (ENOENT after a Node upgrade under a long-running MCP server, EAGAIN at the process limit): such a failure
25
+ used to end the MCP server or the Stop hook with an unhandled error and leave a pid-less `refreshing` lease; it now
26
+ closes the lease as failed. The worker's own deadline is 28 minutes, inside the 30-minute lease cap, so a lease never
27
+ expires while its worker may still run; a lease stamped more than two minutes in the future whose recorded worker is
28
+ gone is replaced; the spawn passes `windowsHide`.
29
+ - **doctor names a Stop hook the harness would kill early** (A-SPEC-769.12, 769.13; review rounds 2–3 of
30
+ 769.9–769.11). A new `stop hook timeout` row is WARN when a Holmes Stop route that runs has a timeout below 75 s,
31
+ naming each file and the repair. It reads Claude's user and project settings, the Codex user and project hooks
32
+ files (an entry Codex switched off in `hooks.state` is not counted; the key is matched by realpath, as Codex writes
33
+ it) and the Antigravity user and project hooks files (a `holmes-kit` block with `enabled: false` is not counted).
34
+ Only Holmes's own routes count, and a hook without `timeout` runs under the harness default (600 s) and is not
35
+ short. Claude's `init` now writes the Stop hook with `timeout: 75`. A scan-cache save never creates a `.ax`.
36
+ - **One HEAD probe for the lease, the worker and triage** (A-SPEC-719.5, review round 3). The probe runs `rev-parse
37
+ --verify -q HEAD` through the bounded, scrubbed git: an unborn HEAD answers "no head", while a git that refuses
38
+ inside a repository (dubious ownership under another HOME, a broken gitdir) is "not answered" — it no longer leased
39
+ a null head in one harness against the real one in another. The worker and REQ intake/triage read HEAD the same way
40
+ (an exported `GIT_DIR` made every completion `stale` and kept triage `ambiguous`); the worker's final read is not
41
+ skipped by the per-process git-timeout memory its own scan may have set (A-SPEC-719.6), and a final read that still
42
+ does not answer publishes `retry-at` against the lease's own head instead of throwing the refresh away — only when
43
+ the lease named a commit (A-SPEC-719.7): a lease taken while git refused completes under no head, as in 0.35.20, so
44
+ a workspace whose git refuses for good (an unknown repository extension, dubious ownership) is intake-usable after
45
+ one refresh instead of retrying every 30 s. Intake and triage read HEAD past the per-process git-timeout memory, as
46
+ 0.35.20 did. A lease more than 30 minutes old or 30 minutes in the future is expired whatever its pid.
47
+ - **A slow git no longer re-spawns the refresh on every request** (A-SPEC-719.8, review round 6; present in 0.35.20
48
+ too). The lease read HEAD with a 2 s bound while the worker and intake waited 5 s: a git answering in 2–5 s (a
49
+ network drive, an antivirus scan) leased no head, the worker completed against the commit as `stale`, and every
50
+ request spawned a new refresh. The lease now waits 5 s too. The semantic-coverage HEAD reads with 0.35.20's bound.
51
+ A lease read that answers only after 2 s is remembered as 0.35.20's 2 s timeout was (A-SPEC-719.9, review round
52
+ 7), so the Stop hook's later git reads skip instead of each waiting for the slow git (waiting 5 s had made the Stop
53
+ 10–16 s slower on such a git); for that minute a long-running MCP server leases the head the slow read answered
54
+ rather than none (A-SPEC-719.10), so its next request coalesces onto the current refresh. That remembered head is
55
+ keyed by the real path, as the timeout memory is, and when a worker reports that HEAD moved past it, HEAD is read
56
+ again instead of re-leasing the old commit for the rest of the minute (A-SPEC-719.11). A refresh that completes
57
+ while a request waits on its HEAD read no longer looks "completed in the future" to that request and makes it spawn
58
+ another (A-SPEC-719.12; present in 0.35.20 too). A git that is slow once and fast afterwards (a cold first read) no
59
+ longer re-spawns the refresh on every request for the rest of the minute after a commit (A-SPEC-719.13; present in
60
+ 0.35.20 too).
61
+ - **doctor reads the installed Codex plugin's Stop hook** (A-SPEC-769.14). A Holmes plugin snapshot under the Codex
62
+ plugins cache whose Stop allows less than 75 s — init before 0.35.20 wrote it at 30 s, as a flat list — makes the
63
+ `stop hook timeout` row WARN instead of PASS; a plugin the Codex config switches off is not counted, nor is a plugin
64
+ Stop hook switched off on its own in `hooks.state`, and a symlinked snapshot is followed (A-SPEC-769.15). A
65
+ snapshot directory or `hooks.json` doctor cannot read is named as unknown instead of passing as clean, and plugin
66
+ switches match case-insensitively on Windows (A-SPEC-769.16) — only where a Holmes plugin keeps its hooks file,
67
+ and never for a plugin switched off (A-SPEC-769.17), including the version's `hooks/` folder (A-SPEC-769.18).
68
+
69
+ ## [0.35.20] - 2026-10-15
70
+
71
+ Upgrading: restart every session and MCP server, run `holmes-kit runtime-binding setup` again (the hook dispatcher runs
72
+ from the copy it installs), and trust the rewritten Codex Stop hook once with `/hooks`.
73
+
74
+ ### Fixed
75
+
76
+ - **One workspace runs one detached refresh at a time** (A-SPEC-719.1). Measured 2026-10-15 on a 3,083-document
77
+ workspace: the freshness lease expired two minutes after `startedAt`, so a refresh that needed longer lost its lease
78
+ while still running, every later Stop hook or `requirement_triage` spawned another `rtm-refresh-child`, and 13–16
79
+ ran at once (receipt `attempt: 13`, load average 300–520, Stop hooks of unrelated sessions over their 18 s budget).
80
+ The receipt now names its worker's `pid`; a lease whose worker is alive is not expired (up to 30 minutes, then it
81
+ is), a crashed worker still frees it after two minutes, and the worker ends itself at 30 minutes leaving `retry-at`
82
+ with `failure.stage: 'child'`. Receipts without `pid` keep the former rule.
83
+ - **A superseded refresh worker ends within 15 seconds, at background priority** (A-SPEC-719.2). The worker asked
84
+ whether it still held its lease only between phases, so nine superseded workers kept embedding for 2–4 hours after a
85
+ newer generation had already completed; each also ran at default priority with 16 ONNX threads. The child now lowers
86
+ itself to the lowest scheduling priority (nice 19; `PRIORITY_LOW` on Windows) and checks its lease every
87
+ `REFRESH_SUPERSEDE_POLL_MS` (15 s), exiting at the first answer that it no longer holds it. It still never writes a
88
+ receipt for a generation it does not own.
89
+ - **The Stop hook no longer re-parses the whole workspace every turn** (A-SPEC-769.9). Measured 2026-10-15 at load
90
+ ~300: the Stop hook's shared scan parsed all 463 files with no cache in 23.0 s, against an 18 s budget, so every Stop
91
+ of every session was refused with `Selected hook runtime deadline exceeded`. It now reads the content-hash scan cache
92
+ the background refresh already keeps (`scanCacheDirFor(root)`): 0.48 s once warm. The cache file is now replaced
93
+ atomically, since two processes share it.
94
+ - **The Stop scan cache lives in the workspace and skips the compiler pass** (A-SPEC-769.11, review round 1 of
95
+ 769.9/769.10). In a governed workspace the cache is `<root>/.ax/cpg_cache` — the directory the MCP server already
96
+ uses — instead of a computable name in the shared temp directory, where another local user on Linux could plant
97
+ entries the Stop gate then believed. The temporary file is created exclusively under a random name (a planted file or
98
+ link there is never written through), and leftovers older than ten minutes are swept. The Stop scan no longer runs the
99
+ whole-program TypeScript pass, which neither Stop judgement reads. The Stop stage-timing line prints from 9 s, and
100
+ `init`'s Codex trust-change refusal names the changed Stop timeout among its causes.
101
+ - **The Stop hook's deadline is 60 seconds** (A-SPEC-769.10). PreToolUse keeps 18 s. The runtime dispatcher gives the
102
+ Stop entry `STOP_HOOK_BUDGET_MS` (60 s), and Holmes Stop entries are written with `timeout: 75` on Claude, Codex and
103
+ Antigravity (budget, 8 s cleanup and a margin). The dispatcher runs from the copy `runtime-binding setup` installs
104
+ under `~/.holmes/runtime`, and harness wiring keeps its old `timeout: 30` until it is rewritten: after upgrading, run
105
+ `holmes-kit runtime-binding setup` (operator) or `holmes-kit init` again. Codex hashes a hook's timeout into its trust
106
+ identity, so the rewritten Codex Stop hook must be trusted again once with `/hooks`.
107
+ - **The local embedder keeps its progress** (A-SPEC-719.3). The local (BGE-M3) `warm()` flushed the vector cache once,
108
+ after its last text, so a refresh worker ended before then landed nothing and the next one started from zero. It
109
+ now publishes a segment after every 25 new vectors (`LOCAL_WARM_CHECKPOINT`), as the cloud warm does per batch.
110
+
8
111
  ## [0.35.19] - 2026-10-13
9
112
 
10
113
  ### Added
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **440/442** source files (99.5%) trace to an approved spec · **774/837** approved A-SPECs (92.4%) are anchored from code.
13
- Measured at `11a1b841c813` (specs `sha256:2e7481e061f1`) — reproduce with `holmes-kit attest`.
12
+ **440/442** source files (99.5%) trace to an approved spec · **797/860** approved A-SPECs (92.6%) are anchored from code.
13
+ Measured at `6d468ae1591a` (specs `sha256:a0c4f70f8d10`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- fdff132e-mv6ac9v3
1
+ e064e7aa-mvafty6m
@@ -54,6 +54,7 @@ exports.agyCanonicalFile = agyCanonicalFile;
54
54
  // @implements A-SPEC-708, A-SPEC-707, A-SPEC-202, A-SPEC-250, A-SPEC-341
55
55
  // @implements A-SPEC-442
56
56
  // @implements A-SPEC-193
57
+ // @implements A-SPEC-769.10
57
58
  const agents_guidance_plan_1 = require("./agents-guidance-plan");
58
59
  const agents_guidance_1 = require("./agents-guidance");
59
60
  const fs = __importStar(require("node:fs"));
@@ -61,6 +62,7 @@ const os = __importStar(require("node:os"));
61
62
  const path = __importStar(require("node:path"));
62
63
  const node_child_process_1 = require("node:child_process");
63
64
  const mcp_launcher_1 = require("./mcp-launcher");
65
+ const hook_process_1 = require("../runtime/hook-process");
64
66
  /**
65
67
  * 하네스별 배선물.
66
68
  *
@@ -190,11 +192,14 @@ function antigravityHookWarnings(packageRoot) {
190
192
  }
191
193
  return out;
192
194
  }
193
- const antigravityHookEntry = (packageRoot, script) => ({
195
+ // @implements A-SPEC-769.10 — the Stop handler carries the Stop deadline; PreToolUse keeps 30 s.
196
+ const antigravityHookEntry = (packageRoot, script, timeout = 30) => ({
194
197
  type: 'command',
195
198
  command: antigravityHookCommand(shortPathIfSpaced(path.join(packageRoot, 'bin', script))),
196
- timeout: 30,
199
+ timeout,
197
200
  });
201
+ /** Stop handler timeouts a canonical file may carry: the current one and the one init wrote before A-SPEC-769.10. */
202
+ const AGY_STOP_TIMEOUTS = [hook_process_1.STOP_HOOK_TIMEOUT_SECONDS, 30];
198
203
  /**
199
204
  * @implements A-SPEC-442
200
205
  * Codex 훅이 부를 것: **Claude 와 같은 정책 커널**.
@@ -212,7 +217,7 @@ const hooksJson = (packageRoot) => `${JSON.stringify({
212
217
  matcher: '*',
213
218
  hooks: [antigravityHookEntry(packageRoot, 'holmes-hook-antigravity.js')],
214
219
  }],
215
- Stop: [antigravityHookEntry(packageRoot, 'holmes-stop-antigravity.js')],
220
+ Stop: [antigravityHookEntry(packageRoot, 'holmes-stop-antigravity.js', hook_process_1.STOP_HOOK_TIMEOUT_SECONDS)],
216
221
  },
217
222
  }, null, 2)}\n`;
218
223
  const AGENTS_MD = (_enforced) => (0, agents_guidance_1.renderCommonGuidance)();
@@ -609,7 +614,7 @@ function agentFiles(agent, opts) {
609
614
  Stop: [{
610
615
  type: 'command',
611
616
  command: kernelCommand(packageRoot, 'stop.js'),
612
- timeout: 30,
617
+ timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS, // A-SPEC-769.10
613
618
  }],
614
619
  },
615
620
  }, null, 2)}\n`,
@@ -774,8 +779,9 @@ function agyCanonicalFile(parsed, raw) {
774
779
  return false;
775
780
  const keysAre = (o, keys) => plainObject(o) && Object.keys(o).length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(o, k));
776
781
  const template = antigravityHookEntry('/x', 'x.js');
777
- const handler = (h) => keysAre(h, Object.keys(template))
778
- && Object.entries(template).every(([k, v]) => (k === 'command' ? typeof h[k] === 'string' && /^node \S+$/.test(h[k]) : h[k] === v));
782
+ const handler = (h, timeouts = [template.timeout]) => keysAre(h, Object.keys(template))
783
+ && Object.entries(template).every(([k, v]) => (k === 'command' ? typeof h[k] === 'string' && /^node \S+$/.test(h[k])
784
+ : k === 'timeout' ? timeouts.includes(h[k]) : h[k] === v));
779
785
  if (!keysAre(parsed, [HOLMES]))
780
786
  return false;
781
787
  const spec = parsed[HOLMES];
@@ -789,5 +795,5 @@ function agyCanonicalFile(parsed, raw) {
789
795
  if (!keysAre(group, ['matcher', 'hooks']) || group.matcher !== '*')
790
796
  return false;
791
797
  const hooks = group.hooks;
792
- return Array.isArray(hooks) && hooks.length === 1 && handler(hooks[0]) && handler(stop[0]);
798
+ return Array.isArray(hooks) && hooks.length === 1 && handler(hooks[0]) && handler(stop[0], AGY_STOP_TIMEOUTS);
793
799
  }
@@ -45,12 +45,14 @@ exports.hasHolmesCodexHooks = hasHolmesCodexHooks;
45
45
  exports.inspectCodexUserHooks = inspectCodexUserHooks;
46
46
  exports.codexKernelScripts = codexKernelScripts;
47
47
  // @implements A-SPEC-727
48
+ // @implements A-SPEC-769.10
48
49
  // codex-cli 0.155 removed plugin hooks (`plugin_hooks: removed`, measured 2026-09-23), so the Holmes
49
50
  // gate reaches Codex only through a hooks file Codex loads for every workspace: the user-level
50
51
  // `$CODEX_HOME/hooks.json`. Codex runs a non-managed hook only after the user trusts its exact
51
52
  // definition (`/hooks`); Holmes never writes that trust — it wires the file and says so.
52
53
  const os = __importStar(require("node:os"));
53
54
  const path = __importStar(require("node:path"));
55
+ const hook_process_1 = require("../runtime/hook-process");
54
56
  /** `$CODEX_HOME/hooks.json`, else `<home>/.codex/hooks.json`. Injectable for deterministic tests. */
55
57
  function defaultCodexHooksPath(env = process.env, home = os.homedir()) {
56
58
  return path.join(env.CODEX_HOME || path.join(home, '.codex'), 'hooks.json');
@@ -636,7 +638,7 @@ function withoutHolmes(hooks) {
636
638
  const render = (doc) => `${JSON.stringify(doc, null, 2)}\n`;
637
639
  const shippedGroup = (event, packageRoot) => event === 'PreToolUse'
638
640
  ? { matcher: '.*', hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'pre-tool-use.js'), timeout: 30 }] }
639
- : { hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'stop.js'), timeout: 30 }] };
641
+ : { hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'stop.js'), timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }] }; // A-SPEC-769.10
640
642
  /**
641
643
  * One Holmes PreToolUse and one Holmes Stop group, IN PLACE. Codex keys trust by (file, event, group
642
644
  * index, hook index) plus a hash of the definition, so the first Holmes-only group of an event is
@@ -216,6 +216,18 @@ export declare function mcpProbeEnv(env: NodeJS.ProcessEnv, target: string, plat
216
216
  * the same honest-diagnosis lineage as the codex-wiring WARN (never a gate).
217
217
  */
218
218
  export declare function pushGateCheck(target: string): Check | null;
219
+ /**
220
+ * Holmes Stop hooks whose harness timeout is below the Stop deadline (A-SPEC-769.10: 60 s budget, timeout 75). An
221
+ * install wired before 0.35.20 keeps timeout 30, and the harness then kills a 30–60 s Stop before the dispatcher's own
222
+ * deadline answers. Every file that can route a Holmes Stop for this workspace is read; a Codex entry Codex has
223
+ * switched off in `hooks.state` does not run and is not counted.
224
+ */
225
+ export declare function stopHookTimeoutCheck(target: string, opts?: {
226
+ home?: string;
227
+ codexConfigPath?: string;
228
+ claudeUserSettings?: string | null;
229
+ agyUserHooks?: string;
230
+ }): Check | null;
219
231
  export declare function ciMatrixCheck(target: string): Check | null;
220
232
  /**
221
233
  * @implements A-SPEC-251.2 (round 43) — no control character from a file reaches the terminal (an `env` key holding ESC and BEL
@@ -52,6 +52,7 @@ exports.wiringSpawnShared = wiringSpawnShared;
52
52
  exports.wiringSpawnCheck = wiringSpawnCheck;
53
53
  exports.mcpProbeEnv = mcpProbeEnv;
54
54
  exports.pushGateCheck = pushGateCheck;
55
+ exports.stopHookTimeoutCheck = stopHookTimeoutCheck;
55
56
  exports.ciMatrixCheck = ciMatrixCheck;
56
57
  exports.checksJson = checksJson;
57
58
  exports.formatChecks = formatChecks;
@@ -68,7 +69,7 @@ exports.semanticCoverageCheck = semanticCoverageCheck;
68
69
  exports.semanticTierVerdict = semanticTierVerdict;
69
70
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
70
71
  // @implements A-SPEC-751.4, A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2
71
- // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712
72
+ // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18
72
73
  const doctor_guidance_1 = require("./doctor-guidance");
73
74
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
74
75
  // @implements A-SPEC-594
@@ -2355,6 +2356,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
2355
2356
  const ci = ciMatrixCheck(target ?? process.cwd()); // @implements A-SPEC-664
2356
2357
  if (ci)
2357
2358
  checks.push(ci);
2359
+ const st = stopHookTimeoutCheck(target ?? process.cwd(), { ...(opts?.codexConfigPath ? { codexConfigPath: opts.codexConfigPath } : {}) }); // @implements A-SPEC-769.12, A-SPEC-769.13
2360
+ if (st)
2361
+ checks.push(st);
2358
2362
  }
2359
2363
  checks.push(...(0, worktree_readiness_1.worktreeReadinessChecks)(packageRoot, target ?? process.cwd(), { agent: opts?.agent, codexConfigPath: opts?.codexConfigPath }));
2360
2364
  if (extraChecks) {
@@ -2683,6 +2687,195 @@ function pushGateCheck(target) {
2683
2687
  return null;
2684
2688
  } // diagnosis must never crash doctor
2685
2689
  }
2690
+ // @implements A-SPEC-769.12, A-SPEC-769.13
2691
+ /**
2692
+ * Holmes Stop hooks whose harness timeout is below the Stop deadline (A-SPEC-769.10: 60 s budget, timeout 75). An
2693
+ * install wired before 0.35.20 keeps timeout 30, and the harness then kills a 30–60 s Stop before the dispatcher's own
2694
+ * deadline answers. Every file that can route a Holmes Stop for this workspace is read; a Codex entry Codex has
2695
+ * switched off in `hooks.state` does not run and is not counted.
2696
+ */
2697
+ function stopHookTimeoutCheck(target, opts = {}) {
2698
+ try {
2699
+ if (!fs.existsSync(path.join(target, '.ax')))
2700
+ return null;
2701
+ const { STOP_HOOK_TIMEOUT_SECONDS } = require('../runtime/hook-process');
2702
+ // @implements A-SPEC-769.13 — only Holmes's own Stop routes count: the kernel, the Antigravity bin, or a runtime
2703
+ // router under `.holmes/runtime`. A user's own `stop.js` is not ours (and setup refuses to rewrite it).
2704
+ const isHolmesStop = (cmd) => typeof cmd === 'string'
2705
+ && /dist[/\\]holmes[/\\]hooks[/\\]stop\.js|holmes-stop-antigravity\.js|[/\\]\.holmes[/\\]runtime[/\\](?:claude|codex|antigravity)-stop\.js/.test(cmd);
2706
+ const json = (file) => { try {
2707
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
2708
+ }
2709
+ catch {
2710
+ return null;
2711
+ } };
2712
+ // @implements A-SPEC-769.13 — no timeout is the harness default (600 s on Claude and Codex), not a short one.
2713
+ const short = (t) => typeof t === 'number' && t < STOP_HOOK_TIMEOUT_SECONDS;
2714
+ const stale = [];
2715
+ // Claude: user settings (CLAUDE_CONFIG_DIR or ~/.claude) and the project files.
2716
+ const claudeUser = opts.claudeUserSettings !== undefined ? opts.claudeUserSettings : (0, claude_switches_1.claudeUserSettingsPath)((0, claude_switches_1.claudeSwitchEnv)());
2717
+ for (const file of [claudeUser, path.join(target, '.claude', 'settings.json'), path.join(target, '.claude', 'settings.local.json')]) {
2718
+ if (file === null)
2719
+ continue;
2720
+ const groups = json(file)?.hooks?.Stop;
2721
+ if (Array.isArray(groups) && groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => isHolmesStop(h?.command) && short(h?.timeout))))
2722
+ stale.push({ file, harness: 'claude' });
2723
+ }
2724
+ // Codex: switched-off entries are keyed by the path Codex resolved — compare the path as given, its realpath and
2725
+ // native realpath, lowercased on Windows (as runtime-binding and codex-oracle do).
2726
+ const codexConfig = opts.codexConfigPath ?? (opts.home !== undefined ? path.join(opts.home, '.codex', 'config.toml') : (0, codex_toml_1.defaultCodexConfigPath)());
2727
+ const norm = (s) => process.platform === 'win32' ? s.toLowerCase() : s;
2728
+ const off = new Set();
2729
+ for (const config of [codexConfig, path.join(target, '.codex', 'config.toml')]) {
2730
+ let raw;
2731
+ try {
2732
+ raw = fs.readFileSync(config, 'utf8');
2733
+ }
2734
+ catch {
2735
+ continue;
2736
+ }
2737
+ const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
2738
+ if (!parsed.ok)
2739
+ continue;
2740
+ const state = (parsed.doc.hooks?.state ?? {});
2741
+ for (const [key, value] of Object.entries(state))
2742
+ if (value && value.enabled === false)
2743
+ off.add(norm(key));
2744
+ }
2745
+ const aliases = (file) => {
2746
+ const out = new Set([file]);
2747
+ try {
2748
+ out.add(fs.realpathSync(file));
2749
+ out.add(fs.realpathSync.native(file));
2750
+ }
2751
+ catch { /* not there */ }
2752
+ return [...out];
2753
+ };
2754
+ for (const file of [path.join(path.dirname(codexConfig), 'hooks.json'), path.join(target, '.codex', 'hooks.json')]) {
2755
+ const groups = json(file)?.hooks?.Stop;
2756
+ if (!Array.isArray(groups))
2757
+ continue;
2758
+ const names = aliases(file);
2759
+ const runs = groups.some((g, i) => Array.isArray(g?.hooks) && g.hooks.some((h, j) => isHolmesStop(h?.command) && short(h?.timeout) && !names.some((n) => off.has(norm(`${n}:stop:${i}:${j}`)))));
2760
+ if (runs)
2761
+ stale.push({ file, harness: 'codex' });
2762
+ }
2763
+ // @implements A-SPEC-769.14 — Codex runs the plugin snapshot it installed, not the workspace copy: read each
2764
+ // `hooks.json` within three levels of a holmes vendor in the plugins cache (the walk runtime-binding makes). Init
2765
+ // before 0.35.20 wrote the plugin's Stop as a flat list of handlers, so both shapes count. A plugin the Codex
2766
+ // config switches off (`[plugins."<name>@<vendor>"] enabled = false`) does not run.
2767
+ const pluginsOff = new Set();
2768
+ for (const config of [codexConfig, path.join(target, '.codex', 'config.toml')]) {
2769
+ let raw;
2770
+ try {
2771
+ raw = fs.readFileSync(config, 'utf8');
2772
+ }
2773
+ catch {
2774
+ continue;
2775
+ }
2776
+ const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
2777
+ if (!parsed.ok)
2778
+ continue;
2779
+ for (const [key, value] of Object.entries((parsed.doc.plugins ?? {})))
2780
+ if (value && value.enabled === false)
2781
+ pluginsOff.add(norm(key));
2782
+ }
2783
+ const cache = path.join(path.dirname(codexConfig), 'plugins', 'cache');
2784
+ const handlers = (entry) => Array.isArray(entry?.hooks) ? entry.hooks : [entry];
2785
+ // @implements A-SPEC-769.15 — entries are typed by stat (a symlinked snapshot is followed; the depth bound ends a
2786
+ // link loop), and a Stop handler switched off per hook in hooks.state — keyed by Codex as
2787
+ // `<plugin>@<vendor>:<file in the plugin version>:stop:<i>:<j>` — does not run.
2788
+ const isDir = (f) => { try {
2789
+ return fs.statSync(f).isDirectory();
2790
+ }
2791
+ catch {
2792
+ return false;
2793
+ } };
2794
+ const isFile = (f) => { try {
2795
+ return fs.statSync(f).isFile();
2796
+ }
2797
+ catch {
2798
+ return false;
2799
+ } };
2800
+ // @implements A-SPEC-769.16 — a Holmes snapshot doctor cannot list or parse is named, not passed as clean; plugin
2801
+ // switch keys fold case on Windows as the per-hook keys do.
2802
+ // @implements A-SPEC-769.17 — only where a Holmes plugin keeps its hooks file: the vendor, plugin and version
2803
+ // levels, and `hooks.json` / `hooks/hooks.json` of the version; a plugin switched off is not walked at all.
2804
+ const unreadable = [];
2805
+ const holmesPlugin = (plugin) => plugin === null || /holmes/i.test(plugin);
2806
+ const visit = (at, depth, vendor, plugin, base) => {
2807
+ let names;
2808
+ // @implements A-SPEC-769.18 — the version's `hooks/` folder holds `hooks/hooks.json`, so it counts as well.
2809
+ const hooksFolder = depth === 3 && base !== null && path.relative(base, at) === 'hooks';
2810
+ try {
2811
+ names = fs.readdirSync(at);
2812
+ }
2813
+ catch {
2814
+ if ((depth <= 2 || hooksFolder) && holmesPlugin(plugin))
2815
+ unreadable.push(at);
2816
+ return;
2817
+ }
2818
+ for (const name of names) {
2819
+ const f = path.join(at, name);
2820
+ if (plugin === null && pluginsOff.has(norm(`${name}@${vendor}`)))
2821
+ continue;
2822
+ if (depth < 3 && isDir(f))
2823
+ visit(f, depth + 1, vendor, plugin ?? name, plugin === null ? null : base ?? f);
2824
+ else if (name === 'hooks.json' && plugin !== null && isFile(f)) {
2825
+ const doc = json(f);
2826
+ if (doc === null) {
2827
+ const rel = path.relative(base ?? at, f).split(path.sep).join('/');
2828
+ if (holmesPlugin(plugin) && (rel === 'hooks.json' || rel === 'hooks/hooks.json'))
2829
+ unreadable.push(f);
2830
+ continue;
2831
+ }
2832
+ const stops = doc?.hooks?.Stop;
2833
+ if (!Array.isArray(stops))
2834
+ continue;
2835
+ const prefix = `${plugin}@${vendor}:${path.relative(base ?? at, f).split(path.sep).join('/')}:stop:`;
2836
+ const runs = stops.some((g, i) => handlers(g).some((h, j) => isHolmesStop(h?.command) && short(h?.timeout)
2837
+ && !off.has(norm(`${prefix}${i}:${j}`)) && !(Array.isArray(g?.hooks) ? false : off.has(norm(`${prefix}${i}`)))));
2838
+ if (runs)
2839
+ stale.push({ file: f, harness: 'codex-plugin' });
2840
+ }
2841
+ }
2842
+ };
2843
+ let vendors = [];
2844
+ try {
2845
+ vendors = fs.readdirSync(cache).filter((name) => /holmes/i.test(name) && isDir(path.join(cache, name)));
2846
+ }
2847
+ catch { /* no cache */ }
2848
+ for (const vendor of vendors)
2849
+ visit(path.join(cache, vendor), 0, vendor, null, null);
2850
+ // Antigravity: the user hooks file and the project file; a holmes-kit block switched off does not run.
2851
+ for (const file of [opts.agyUserHooks ?? (0, agents_1.agyUserHooksPath)(), path.join(target, '.agents', 'hooks.json')]) {
2852
+ const block = json(file)?.['holmes-kit'];
2853
+ if (!block || block.enabled === false || !Array.isArray(block.Stop))
2854
+ continue;
2855
+ if (block.Stop.some((h) => isHolmesStop(h?.command) && short(h?.timeout)))
2856
+ stale.push({ file, harness: 'antigravity' });
2857
+ }
2858
+ const unread = unreadable.length === 0 ? ''
2859
+ : `Codex plugin snapshot could not be read, so its Stop timeout is unknown: ${unreadable.join(', ')}`;
2860
+ if (stale.length === 0 && unread === '')
2861
+ return { name: 'stop hook timeout', level: 'PASS', detail: `Every Holmes Stop hook that runs allows at least ${STOP_HOOK_TIMEOUT_SECONDS} s` };
2862
+ if (stale.length === 0)
2863
+ return {
2864
+ name: 'stop hook timeout', level: 'WARN', detail: unread,
2865
+ fix: 'Make the snapshot readable by this user, or uninstall that Holmes plugin in Codex and reinstall it from the current workspace',
2866
+ };
2867
+ return {
2868
+ name: 'stop hook timeout', level: 'WARN',
2869
+ detail: `Holmes Stop hook with a timeout below ${STOP_HOOK_TIMEOUT_SECONDS} s (the harness kills a Stop before its 60 s deadline answers): ${stale.map((s) => s.file).join(', ')}${unread === '' ? '' : `; ${unread}`}`,
2870
+ fix: 'Run holmes-kit runtime-binding setup again (operator), or holmes-kit init for a workspace init wired'
2871
+ + (stale.some((s) => s.harness === 'codex') ? '; then trust the rewritten Codex Stop hook once with /hooks' : '')
2872
+ + (stale.some((s) => s.harness === 'codex-plugin') ? '; an installed Codex plugin snapshot is not rewritten by setup — uninstall that Holmes plugin in Codex, or reinstall it from the current workspace' : ''),
2873
+ };
2874
+ }
2875
+ catch {
2876
+ return null;
2877
+ } // diagnosis must never crash doctor
2878
+ }
2686
2879
  // @implements A-SPEC-664
2687
2880
  // The CI matrix as doctor sees it: PASS only for a green row at HEAD; everything else is a WARN that
2688
2881
  // says exactly what the ledger says — "not run" when there is no row, the failed suites when red,
@@ -38,6 +38,7 @@ exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
39
  // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8
40
40
  // @implements A-SPEC-709
41
+ // @implements A-SPEC-769.11
41
42
  // @implements A-SPEC-340
42
43
  // @implements A-SPEC-100.2
43
44
  const fs = __importStar(require("node:fs"));
@@ -557,7 +558,7 @@ function runInitUnguarded(opts) {
557
558
  opts.remove
558
559
  ? 'Stripping governance wiring is also changing the wiring — an out-of-band approval is required (self-disarm prevention).'
559
560
  : codexHooksRepoint && !opts.force
560
- ? `Re-wiring the Codex user hooks would change hooks Codex already trusts (another holmes-kit install, a changed matcher, or a moved group); Codex would treat them as new, untrusted hooks — off in every workspace until trusted again with /hooks — so an out-of-band approval is required.`
561
+ ? `Re-wiring the Codex user hooks would change hooks Codex already trusts (another holmes-kit install, a changed matcher, a changed Stop timeout (75 s since A-SPEC-769.10), or a moved group); Codex would treat them as new, untrusted hooks — off in every workspace until trusted again with /hooks — so an out-of-band approval is required.`
561
562
  : '--force changes existing governance wiring and requires an out-of-band approval that covers it.',
562
563
  `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "governance-wiring") and re-run.`,
563
564
  ] };
@@ -42,7 +42,7 @@ exports.codexDuplicateRoutes = codexDuplicateRoutes;
42
42
  exports.runtimeBindingStatus = runtimeBindingStatus;
43
43
  exports.runRuntimeBinding = runRuntimeBinding;
44
44
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
45
- // @implements A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8
45
+ // @implements A-SPEC-769.10, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8
46
46
  const fs = __importStar(require("node:fs"));
47
47
  const os = __importStar(require("node:os"));
48
48
  const path = __importStar(require("node:path"));
@@ -50,6 +50,7 @@ const node_crypto_1 = require("node:crypto");
50
50
  const bounded_io_1 = require("../project/bounded-io");
51
51
  const smol_toml_1 = require("smol-toml");
52
52
  const binding_1 = require("../runtime/binding");
53
+ const hook_process_1 = require("../runtime/hook-process");
53
54
  const runtime_binding_approval_1 = require("./runtime-binding-approval");
54
55
  const codex_toml_1 = require("./codex-toml");
55
56
  const codex_hooks_1 = require("./codex-hooks");
@@ -451,7 +452,7 @@ function runRuntimeBinding(opts) {
451
452
  }
452
453
  const explicitlyEmpty = Array.isArray(hooks[event]) && hooks[event].length === 0;
453
454
  if ((!explicitlyEmpty || activate.has(harness)) && (typeof primary === 'boolean' ? primary : primary.has(event)))
454
- groups.push({ ...(event === 'PreToolUse' ? { matcher: '.*' } : {}), hooks: [{ type: 'command', command: command(harness, event === 'PreToolUse' ? 'pre-tool-use' : 'stop'), timeout: 30 }] });
455
+ groups.push({ ...(event === 'PreToolUse' ? { matcher: '.*' } : {}), hooks: [{ type: 'command', command: command(harness, event === 'PreToolUse' ? 'pre-tool-use' : 'stop'), timeout: event === 'Stop' ? hook_process_1.STOP_HOOK_TIMEOUT_SECONDS : 30 }] }); // A-SPEC-769.10
455
456
  if (groups.length || hooks[event] !== undefined)
456
457
  hooks[event] = groups;
457
458
  }
@@ -551,7 +552,7 @@ function runRuntimeBinding(opts) {
551
552
  else if (!(Array.isArray(old?.PreToolUse) && old.PreToolUse.length === 0))
552
553
  delete ours.PreToolUse;
553
554
  if (primary.has('Stop'))
554
- ours.Stop = !activate.has('antigravity') && Array.isArray(old?.Stop) && old.Stop.length === 0 ? [] : [{ command: command('antigravity', 'stop') }];
555
+ ours.Stop = !activate.has('antigravity') && Array.isArray(old?.Stop) && old.Stop.length === 0 ? [] : [{ command: command('antigravity', 'stop'), timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }]; // A-SPEC-769.10
555
556
  else if (!(Array.isArray(old?.Stop) && old.Stop.length === 0))
556
557
  delete ours.Stop;
557
558
  add(file, json({ ...doc, 'holmes-kit': ours }));
@@ -13,6 +13,7 @@
13
13
  export interface HookEntry {
14
14
  type: 'command';
15
15
  command: string;
16
+ timeout?: number;
16
17
  }
17
18
  export interface HookGroup {
18
19
  matcher?: string;
@@ -1,5 +1,4 @@
1
1
  "use strict";
2
- // @implements A-SPEC-100.2
3
2
  Object.defineProperty(exports, "__esModule", { value: true });
4
3
  exports.AUTONOMY_MCP_ENV = exports.HOLMES_OWNED_MCP_ENV = void 0;
5
4
  exports.isHolmesCommand = isHolmesCommand;
@@ -10,6 +9,9 @@ exports.enableMcpServer = enableMcpServer;
10
9
  exports.disableMcpServer = disableMcpServer;
11
10
  exports.mergeMcpServers = mergeMcpServers;
12
11
  exports.removeMcpServer = removeMcpServer;
12
+ // @implements A-SPEC-100.2
13
+ // @implements A-SPEC-769.12
14
+ const hook_process_1 = require("../runtime/hook-process");
13
15
  /** A hook entry belongs to holmes-kit iff its command references our hook scripts. */
14
16
  function isHolmesCommand(command) {
15
17
  return /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop|session-start)\.js/.test(command) || /\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(command);
@@ -42,7 +44,9 @@ function mergeHooks(existing, plan) {
42
44
  hooks[event] = groups;
43
45
  };
44
46
  upsert('PreToolUse', { matcher: plan.preToolUseMatcher, hooks: [{ type: 'command', command: plan.preToolUseCommand }] });
45
- upsert('Stop', { hooks: [{ type: 'command', command: plan.stopCommand }] }); // Stop takes NO matcher
47
+ // Stop takes NO matcher. @implements A-SPEC-769.12 — and carries the Stop timeout: without one Claude applied its own
48
+ // default, unrelated to the dispatcher's 60 s Stop budget.
49
+ upsert('Stop', { hooks: [{ type: 'command', command: plan.stopCommand, timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }] });
46
50
  // @implements A-SPEC-531.2 — the banner hook, wired like Stop (no matcher). Guarded so an older
47
51
  // caller that builds a plan without it is unchanged (no empty SessionStart group appears).
48
52
  if (plan.sessionStartCommand) {
@@ -1,14 +1,23 @@
1
1
  import type { ScannedFile } from './scanned-file';
2
2
  export declare const SCAN_CACHE_VERSION = 4;
3
+ /**
4
+ * @implements A-SPEC-769.9 — the one cache directory per workspace root, shared by the refresh child and the Stop
5
+ * hook. Measured 2026-10-15: the Stop hook's uncached scan took 23.0 s of its budget; served from here, 0.48 s.
6
+ */
7
+ export declare function scanCacheDirFor(root: string, tmp?: string): string;
3
8
  export declare class ScanFileCache {
4
9
  private readonly dir;
5
10
  private readonly file;
11
+ private readonly tempSuffix;
12
+ private readonly axDir;
6
13
  private entries;
7
14
  private seen;
8
15
  private dirty;
9
16
  hits: number;
10
17
  misses: number;
11
- constructor(dir: string);
18
+ constructor(dir: string, opts?: {
19
+ tempSuffix?: () => string;
20
+ });
12
21
  static hashOf(content: string): string;
13
22
  /** Cached scan result iff the stored hash matches this content. Marks the path as seen. */
14
23
  get(sourcePath: string, contentHash: string): Omit<ScannedFile, 'path'> | undefined;
@@ -18,4 +27,6 @@ export declare class ScanFileCache {
18
27
  * deleted/renamed files — pruned so the cache cannot grow unboundedly. No-op when nothing changed.
19
28
  */
20
29
  save(scannedScopeDir?: string): void;
30
+ /** @implements A-SPEC-769.11 — removes temporary files of this cache's shape older than ten minutes. */
31
+ private sweepTemporaries;
21
32
  }