@holmes-lab/holmes-kit 0.35.20 → 0.35.22

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.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
  <!-- @implements A-SPEC-209 -->
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.35.22] - 2026-10-16
11
+
12
+ Upgrading: run `holmes-kit runtime-binding setup` again so the hooks run this build, then `holmes-kit doctor`. A `codex
13
+ stop gate` WARN means Codex sessions in that workspace end without the Holmes Stop gate; its fix line names the
14
+ `--activate-hooks codex` setup and the one-time `/hooks` trust.
15
+
16
+ ### Fixed
17
+
18
+ - **`runtime-binding remove` no longer rewrites harness wiring** (A-SPEC-752.11). Removing a workspace with no Codex
19
+ project files planned setup's whole wiring and chose to rewrite the shared user-level Codex Stop entry; where Codex
20
+ had switched that entry off, removal was refused ("re-run with --activate-hooks codex", a flag remove does not take)
21
+ and the binding stayed. Remove now changes only the registry, the router programs and the receipt, and the receipt
22
+ forgets the removed workspace's rows and identity — except rows of a workspace nested inside it that stays bound
23
+ (A-SPEC-752.12, 752.13).
24
+ - **doctor names a Codex workspace with no Stop gate** (A-SPEC-769.19). New row `codex stop gate`: WARN when Codex runs
25
+ the Holmes PreToolUse gate for the workspace but no Holmes Stop gate, naming each switched-off Holmes Stop entry and
26
+ warning when its timeout is below 75 s (switched on as it stands, Codex would kill the Stop before its deadline). Only
27
+ Codex routers with a trust record in the Codex user config count, and an entry wired but not yet trusted is named
28
+ (A-SPEC-769.20, 769.21). The `stop hook timeout` row still counts only the Stop hooks that run.
29
+
30
+ ## [0.35.21] - 2026-10-16
31
+
32
+ Upgrading: restart every session and MCP server (the MCP freshness bridge keeps its slow-git memory per process), and
33
+ run `holmes-kit runtime-binding setup` again so the hooks run this build. Then run `holmes-kit doctor`: a `stop hook
34
+ timeout` WARN naming a Codex plugin snapshot means that snapshot still carries a 30 s Stop.
35
+
36
+ ### Fixed
37
+
38
+ - **The background refresh survives a slow git, a failed spawn and a stepped clock** (A-SPEC-719.4, review rounds 1
39
+ 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
40
+ (which superseded the live worker and could never complete current): such a request joins the live lease, and
41
+ only with no live lease does it lease a null head as before (A-SPEC-719.6 — a git that refuses for good still
42
+ refreshes). A worker now ends from its 15-second watch only when its workspace is gone or a readable receipt names a newer
43
+ generation or a finished state — a momentarily unreadable receipt is read again. The detached spawn listens for
44
+ `'error'` (ENOENT after a Node upgrade under a long-running MCP server, EAGAIN at the process limit): such a failure
45
+ used to end the MCP server or the Stop hook with an unhandled error and leave a pid-less `refreshing` lease; it now
46
+ closes the lease as failed. The worker's own deadline is 28 minutes, inside the 30-minute lease cap, so a lease never
47
+ expires while its worker may still run; a lease stamped more than two minutes in the future whose recorded worker is
48
+ gone is replaced; the spawn passes `windowsHide`.
49
+ - **doctor names a Stop hook the harness would kill early** (A-SPEC-769.12, 769.13; review rounds 2–3 of
50
+ 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,
51
+ naming each file and the repair. It reads Claude's user and project settings, the Codex user and project hooks
52
+ files (an entry Codex switched off in `hooks.state` is not counted; the key is matched by realpath, as Codex writes
53
+ it) and the Antigravity user and project hooks files (a `holmes-kit` block with `enabled: false` is not counted).
54
+ Only Holmes's own routes count, and a hook without `timeout` runs under the harness default (600 s) and is not
55
+ short. Claude's `init` now writes the Stop hook with `timeout: 75`. A scan-cache save never creates a `.ax`.
56
+ - **One HEAD probe for the lease, the worker and triage** (A-SPEC-719.5, review round 3). The probe runs `rev-parse
57
+ --verify -q HEAD` through the bounded, scrubbed git: an unborn HEAD answers "no head", while a git that refuses
58
+ inside a repository (dubious ownership under another HOME, a broken gitdir) is "not answered" — it no longer leased
59
+ a null head in one harness against the real one in another. The worker and REQ intake/triage read HEAD the same way
60
+ (an exported `GIT_DIR` made every completion `stale` and kept triage `ambiguous`); the worker's final read is not
61
+ skipped by the per-process git-timeout memory its own scan may have set (A-SPEC-719.6), and a final read that still
62
+ does not answer publishes `retry-at` against the lease's own head instead of throwing the refresh away — only when
63
+ 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
64
+ a workspace whose git refuses for good (an unknown repository extension, dubious ownership) is intake-usable after
65
+ one refresh instead of retrying every 30 s. Intake and triage read HEAD past the per-process git-timeout memory, as
66
+ 0.35.20 did. A lease more than 30 minutes old or 30 minutes in the future is expired whatever its pid.
67
+ - **A slow git no longer re-spawns the refresh on every request** (A-SPEC-719.8, review round 6; present in 0.35.20
68
+ 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
69
+ network drive, an antivirus scan) leased no head, the worker completed against the commit as `stale`, and every
70
+ request spawned a new refresh. The lease now waits 5 s too. The semantic-coverage HEAD reads with 0.35.20's bound.
71
+ 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
72
+ 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
73
+ 10–16 s slower on such a git); for that minute a long-running MCP server leases the head the slow read answered
74
+ rather than none (A-SPEC-719.10), so its next request coalesces onto the current refresh. That remembered head is
75
+ keyed by the real path, as the timeout memory is, and when a worker reports that HEAD moved past it, HEAD is read
76
+ again instead of re-leasing the old commit for the rest of the minute (A-SPEC-719.11). A refresh that completes
77
+ while a request waits on its HEAD read no longer looks "completed in the future" to that request and makes it spawn
78
+ 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
79
+ longer re-spawns the refresh on every request for the rest of the minute after a commit (A-SPEC-719.13; present in
80
+ 0.35.20 too).
81
+ - **doctor reads the installed Codex plugin's Stop hook** (A-SPEC-769.14). A Holmes plugin snapshot under the Codex
82
+ 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
83
+ `stop hook timeout` row WARN instead of PASS; a plugin the Codex config switches off is not counted, nor is a plugin
84
+ Stop hook switched off on its own in `hooks.state`, and a symlinked snapshot is followed (A-SPEC-769.15). A
85
+ snapshot directory or `hooks.json` doctor cannot read is named as unknown instead of passing as clean, and plugin
86
+ switches match case-insensitively on Windows (A-SPEC-769.16) — only where a Holmes plugin keeps its hooks file,
87
+ and never for a plugin switched off (A-SPEC-769.17), including the version's `hooks/` folder (A-SPEC-769.18).
88
+
10
89
  ## [0.35.20] - 2026-10-15
11
90
 
12
91
  Upgrading: restart every session and MCP server, run `holmes-kit runtime-binding setup` again (the hook dispatcher runs
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 `80944935ee8a` (specs `sha256:2e7481e061f1`) — reproduce with `holmes-kit attest`.
12
+ **440/442** source files (99.5%) trace to an approved spec · **803/866** approved A-SPECs (92.7%) are anchored from code.
13
+ Measured at `bc705710c89e` (specs `sha256:9ddf0c3d9cee`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- c8cb7cb6-mv91ezzh
1
+ 8dd234f5-mvb0beqr
@@ -216,6 +216,41 @@ 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
+ /** A-SPEC-769.19: filled by the same reading for `codexStopGateCheck`; no verdict of this row depends on it. */
231
+ codexGate?: CodexGateReading;
232
+ }): Check | null;
233
+ /** A-SPEC-769.19 — what the stop-hook reading saw of the Holmes Codex gates for one workspace. */
234
+ export type CodexGateReading = {
235
+ codexPre: boolean;
236
+ codexStop: boolean;
237
+ dormant: {
238
+ file: string;
239
+ timeout: number | null;
240
+ }[];
241
+ untrusted: string[];
242
+ };
243
+ /**
244
+ * Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate: Codex sessions end without the constitution
245
+ * check. Measured 2026-10-16 in the dev root (user Stop switched off at timeout 30, project `Stop: []`). No row when no
246
+ * Holmes Codex PreToolUse gate runs — that is a workspace Codex does not govern, not a half-wired one.
247
+ */
248
+ export declare function codexStopGateCheck(target: string, opts?: {
249
+ home?: string;
250
+ codexConfigPath?: string;
251
+ claudeUserSettings?: string | null;
252
+ agyUserHooks?: string;
253
+ }): Check | null;
219
254
  export declare function ciMatrixCheck(target: string): Check | null;
220
255
  /**
221
256
  * @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,8 @@ exports.wiringSpawnShared = wiringSpawnShared;
52
52
  exports.wiringSpawnCheck = wiringSpawnCheck;
53
53
  exports.mcpProbeEnv = mcpProbeEnv;
54
54
  exports.pushGateCheck = pushGateCheck;
55
+ exports.stopHookTimeoutCheck = stopHookTimeoutCheck;
56
+ exports.codexStopGateCheck = codexStopGateCheck;
55
57
  exports.ciMatrixCheck = ciMatrixCheck;
56
58
  exports.checksJson = checksJson;
57
59
  exports.formatChecks = formatChecks;
@@ -68,7 +70,7 @@ exports.semanticCoverageCheck = semanticCoverageCheck;
68
70
  exports.semanticTierVerdict = semanticTierVerdict;
69
71
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
70
72
  // @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
73
+ // @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, A-SPEC-769.19, A-SPEC-769.20, A-SPEC-769.21
72
74
  const doctor_guidance_1 = require("./doctor-guidance");
73
75
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
74
76
  // @implements A-SPEC-594
@@ -2355,6 +2357,12 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
2355
2357
  const ci = ciMatrixCheck(target ?? process.cwd()); // @implements A-SPEC-664
2356
2358
  if (ci)
2357
2359
  checks.push(ci);
2360
+ const st = stopHookTimeoutCheck(target ?? process.cwd(), { ...(opts?.codexConfigPath ? { codexConfigPath: opts.codexConfigPath } : {}) }); // @implements A-SPEC-769.12, A-SPEC-769.13
2361
+ if (st)
2362
+ checks.push(st);
2363
+ const cg = codexStopGateCheck(target ?? process.cwd(), { ...(opts?.codexConfigPath ? { codexConfigPath: opts.codexConfigPath } : {}) }); // @implements A-SPEC-769.19
2364
+ if (cg)
2365
+ checks.push(cg);
2358
2366
  }
2359
2367
  checks.push(...(0, worktree_readiness_1.worktreeReadinessChecks)(packageRoot, target ?? process.cwd(), { agent: opts?.agent, codexConfigPath: opts?.codexConfigPath }));
2360
2368
  if (extraChecks) {
@@ -2683,6 +2691,275 @@ function pushGateCheck(target) {
2683
2691
  return null;
2684
2692
  } // diagnosis must never crash doctor
2685
2693
  }
2694
+ // @implements A-SPEC-769.12, A-SPEC-769.13
2695
+ /**
2696
+ * Holmes Stop hooks whose harness timeout is below the Stop deadline (A-SPEC-769.10: 60 s budget, timeout 75). An
2697
+ * install wired before 0.35.20 keeps timeout 30, and the harness then kills a 30–60 s Stop before the dispatcher's own
2698
+ * deadline answers. Every file that can route a Holmes Stop for this workspace is read; a Codex entry Codex has
2699
+ * switched off in `hooks.state` does not run and is not counted.
2700
+ */
2701
+ function stopHookTimeoutCheck(target, opts = {}) {
2702
+ try {
2703
+ if (!fs.existsSync(path.join(target, '.ax')))
2704
+ return null;
2705
+ const gateReading = opts.codexGate;
2706
+ // @implements A-SPEC-769.20 — only a Codex router or the kernel is a Codex gate.
2707
+ const isCodexPre = (cmd) => typeof cmd === 'string'
2708
+ && /dist[/\\]holmes[/\\]hooks[/\\]pre-tool-use\.js|[/\\]\.holmes[/\\]runtime[/\\]codex-pre-tool-use\.js/.test(cmd);
2709
+ const isCodexStop = (cmd) => typeof cmd === 'string'
2710
+ && /dist[/\\]holmes[/\\]hooks[/\\]stop\.js|[/\\]\.holmes[/\\]runtime[/\\]codex-stop\.js/.test(cmd);
2711
+ const { STOP_HOOK_TIMEOUT_SECONDS } = require('../runtime/hook-process');
2712
+ // @implements A-SPEC-769.13 — only Holmes's own Stop routes count: the kernel, the Antigravity bin, or a runtime
2713
+ // router under `.holmes/runtime`. A user's own `stop.js` is not ours (and setup refuses to rewrite it).
2714
+ const isHolmesStop = (cmd) => typeof cmd === 'string'
2715
+ && /dist[/\\]holmes[/\\]hooks[/\\]stop\.js|holmes-stop-antigravity\.js|[/\\]\.holmes[/\\]runtime[/\\](?:claude|codex|antigravity)-stop\.js/.test(cmd);
2716
+ const json = (file) => { try {
2717
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
2718
+ }
2719
+ catch {
2720
+ return null;
2721
+ } };
2722
+ // @implements A-SPEC-769.13 — no timeout is the harness default (600 s on Claude and Codex), not a short one.
2723
+ const short = (t) => typeof t === 'number' && t < STOP_HOOK_TIMEOUT_SECONDS;
2724
+ const stale = [];
2725
+ // Claude: user settings (CLAUDE_CONFIG_DIR or ~/.claude) and the project files.
2726
+ const claudeUser = opts.claudeUserSettings !== undefined ? opts.claudeUserSettings : (0, claude_switches_1.claudeUserSettingsPath)((0, claude_switches_1.claudeSwitchEnv)());
2727
+ for (const file of [claudeUser, path.join(target, '.claude', 'settings.json'), path.join(target, '.claude', 'settings.local.json')]) {
2728
+ if (file === null)
2729
+ continue;
2730
+ const groups = json(file)?.hooks?.Stop;
2731
+ if (Array.isArray(groups) && groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => isHolmesStop(h?.command) && short(h?.timeout))))
2732
+ stale.push({ file, harness: 'claude' });
2733
+ }
2734
+ // Codex: switched-off entries are keyed by the path Codex resolved — compare the path as given, its realpath and
2735
+ // native realpath, lowercased on Windows (as runtime-binding and codex-oracle do).
2736
+ const codexConfig = opts.codexConfigPath ?? (opts.home !== undefined ? path.join(opts.home, '.codex', 'config.toml') : (0, codex_toml_1.defaultCodexConfigPath)());
2737
+ const norm = (s) => process.platform === 'win32' ? s.toLowerCase() : s;
2738
+ const off = new Set();
2739
+ const trusted = new Set();
2740
+ for (const config of [codexConfig, path.join(target, '.codex', 'config.toml')]) {
2741
+ let raw;
2742
+ try {
2743
+ raw = fs.readFileSync(config, 'utf8');
2744
+ }
2745
+ catch {
2746
+ continue;
2747
+ }
2748
+ const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
2749
+ if (!parsed.ok)
2750
+ continue;
2751
+ const state = (parsed.doc.hooks?.state ?? {});
2752
+ for (const [key, value] of Object.entries(state))
2753
+ if (value && value.enabled === false)
2754
+ off.add(norm(key));
2755
+ // @implements A-SPEC-769.20 — Codex runs a hook only with a trust record for its key.
2756
+ // @implements A-SPEC-769.21 — read from the user config only: a record the repository carries is not the user's trust.
2757
+ if (config === codexConfig)
2758
+ for (const [key, value] of Object.entries(state))
2759
+ if (value && typeof value.trusted_hash === 'string')
2760
+ trusted.add(norm(key));
2761
+ }
2762
+ const aliases = (file) => {
2763
+ const out = new Set([file]);
2764
+ try {
2765
+ out.add(fs.realpathSync(file));
2766
+ out.add(fs.realpathSync.native(file));
2767
+ }
2768
+ catch { /* not there */ }
2769
+ return [...out];
2770
+ };
2771
+ for (const file of [path.join(path.dirname(codexConfig), 'hooks.json'), path.join(target, '.codex', 'hooks.json')]) {
2772
+ const doc = json(file);
2773
+ const groups = doc?.hooks?.Stop;
2774
+ const names = aliases(file);
2775
+ // @implements A-SPEC-769.19 — which Holmes Codex gates run here, and which Holmes Stop entries are switched off.
2776
+ if (gateReading) {
2777
+ const isOff = (event, i, j) => names.some((n) => off.has(norm(`${n}:${event}:${i}:${j}`)));
2778
+ const isTrusted = (event, i, j) => names.some((n) => trusted.has(norm(`${n}:${event}:${i}:${j}`)));
2779
+ const pre = doc?.hooks?.PreToolUse;
2780
+ if (Array.isArray(pre) && pre.some((g, i) => Array.isArray(g?.hooks)
2781
+ && g.hooks.some((h, j) => isCodexPre(h?.command) && !isOff('pre_tool_use', i, j) && isTrusted('pre_tool_use', i, j))))
2782
+ gateReading.codexPre = true;
2783
+ if (Array.isArray(groups))
2784
+ groups.forEach((g, i) => (Array.isArray(g?.hooks) ? g.hooks : []).forEach((h, j) => {
2785
+ if (!isCodexStop(h?.command))
2786
+ return;
2787
+ if (isOff('stop', i, j))
2788
+ gateReading.dormant.push({ file, timeout: typeof h?.timeout === 'number' ? h.timeout : null });
2789
+ else if (!isTrusted('stop', i, j))
2790
+ gateReading.untrusted.push(file);
2791
+ else
2792
+ gateReading.codexStop = true;
2793
+ }));
2794
+ }
2795
+ if (!Array.isArray(groups))
2796
+ continue;
2797
+ 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}`)))));
2798
+ if (runs)
2799
+ stale.push({ file, harness: 'codex' });
2800
+ }
2801
+ // @implements A-SPEC-769.14 — Codex runs the plugin snapshot it installed, not the workspace copy: read each
2802
+ // `hooks.json` within three levels of a holmes vendor in the plugins cache (the walk runtime-binding makes). Init
2803
+ // before 0.35.20 wrote the plugin's Stop as a flat list of handlers, so both shapes count. A plugin the Codex
2804
+ // config switches off (`[plugins."<name>@<vendor>"] enabled = false`) does not run.
2805
+ const pluginsOff = new Set();
2806
+ for (const config of [codexConfig, path.join(target, '.codex', 'config.toml')]) {
2807
+ let raw;
2808
+ try {
2809
+ raw = fs.readFileSync(config, 'utf8');
2810
+ }
2811
+ catch {
2812
+ continue;
2813
+ }
2814
+ const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
2815
+ if (!parsed.ok)
2816
+ continue;
2817
+ for (const [key, value] of Object.entries((parsed.doc.plugins ?? {})))
2818
+ if (value && value.enabled === false)
2819
+ pluginsOff.add(norm(key));
2820
+ }
2821
+ const cache = path.join(path.dirname(codexConfig), 'plugins', 'cache');
2822
+ const handlers = (entry) => Array.isArray(entry?.hooks) ? entry.hooks : [entry];
2823
+ // @implements A-SPEC-769.15 — entries are typed by stat (a symlinked snapshot is followed; the depth bound ends a
2824
+ // link loop), and a Stop handler switched off per hook in hooks.state — keyed by Codex as
2825
+ // `<plugin>@<vendor>:<file in the plugin version>:stop:<i>:<j>` — does not run.
2826
+ const isDir = (f) => { try {
2827
+ return fs.statSync(f).isDirectory();
2828
+ }
2829
+ catch {
2830
+ return false;
2831
+ } };
2832
+ const isFile = (f) => { try {
2833
+ return fs.statSync(f).isFile();
2834
+ }
2835
+ catch {
2836
+ return false;
2837
+ } };
2838
+ // @implements A-SPEC-769.16 — a Holmes snapshot doctor cannot list or parse is named, not passed as clean; plugin
2839
+ // switch keys fold case on Windows as the per-hook keys do.
2840
+ // @implements A-SPEC-769.17 — only where a Holmes plugin keeps its hooks file: the vendor, plugin and version
2841
+ // levels, and `hooks.json` / `hooks/hooks.json` of the version; a plugin switched off is not walked at all.
2842
+ const unreadable = [];
2843
+ const holmesPlugin = (plugin) => plugin === null || /holmes/i.test(plugin);
2844
+ const visit = (at, depth, vendor, plugin, base) => {
2845
+ let names;
2846
+ // @implements A-SPEC-769.18 — the version's `hooks/` folder holds `hooks/hooks.json`, so it counts as well.
2847
+ const hooksFolder = depth === 3 && base !== null && path.relative(base, at) === 'hooks';
2848
+ try {
2849
+ names = fs.readdirSync(at);
2850
+ }
2851
+ catch {
2852
+ if ((depth <= 2 || hooksFolder) && holmesPlugin(plugin))
2853
+ unreadable.push(at);
2854
+ return;
2855
+ }
2856
+ for (const name of names) {
2857
+ const f = path.join(at, name);
2858
+ if (plugin === null && pluginsOff.has(norm(`${name}@${vendor}`)))
2859
+ continue;
2860
+ if (depth < 3 && isDir(f))
2861
+ visit(f, depth + 1, vendor, plugin ?? name, plugin === null ? null : base ?? f);
2862
+ else if (name === 'hooks.json' && plugin !== null && isFile(f)) {
2863
+ const doc = json(f);
2864
+ if (doc === null) {
2865
+ const rel = path.relative(base ?? at, f).split(path.sep).join('/');
2866
+ if (holmesPlugin(plugin) && (rel === 'hooks.json' || rel === 'hooks/hooks.json'))
2867
+ unreadable.push(f);
2868
+ continue;
2869
+ }
2870
+ const stops = doc?.hooks?.Stop;
2871
+ // @implements A-SPEC-769.19 — an enabled Holmes plugin snapshot's gates count as running ones.
2872
+ if (gateReading) {
2873
+ const keyOf = (event) => `${plugin}@${vendor}:${path.relative(base ?? at, f).split(path.sep).join('/')}:${event}:`;
2874
+ const runsAny = (list, event, isOurs) => Array.isArray(list)
2875
+ && list.some((g, i) => handlers(g).some((h, j) => isOurs(h?.command)
2876
+ && !off.has(norm(`${keyOf(event)}${i}:${j}`)) && !(Array.isArray(g?.hooks) ? false : off.has(norm(`${keyOf(event)}${i}`)))
2877
+ && (trusted.has(norm(`${keyOf(event)}${i}:${j}`)) || (!Array.isArray(g?.hooks) && trusted.has(norm(`${keyOf(event)}${i}`))))));
2878
+ if (runsAny(doc?.hooks?.PreToolUse, 'pre_tool_use', isCodexPre))
2879
+ gateReading.codexPre = true;
2880
+ if (runsAny(stops, 'stop', isCodexStop))
2881
+ gateReading.codexStop = true;
2882
+ }
2883
+ if (!Array.isArray(stops))
2884
+ continue;
2885
+ const prefix = `${plugin}@${vendor}:${path.relative(base ?? at, f).split(path.sep).join('/')}:stop:`;
2886
+ const runs = stops.some((g, i) => handlers(g).some((h, j) => isHolmesStop(h?.command) && short(h?.timeout)
2887
+ && !off.has(norm(`${prefix}${i}:${j}`)) && !(Array.isArray(g?.hooks) ? false : off.has(norm(`${prefix}${i}`)))));
2888
+ if (runs)
2889
+ stale.push({ file: f, harness: 'codex-plugin' });
2890
+ }
2891
+ }
2892
+ };
2893
+ let vendors = [];
2894
+ try {
2895
+ vendors = fs.readdirSync(cache).filter((name) => /holmes/i.test(name) && isDir(path.join(cache, name)));
2896
+ }
2897
+ catch { /* no cache */ }
2898
+ for (const vendor of vendors)
2899
+ visit(path.join(cache, vendor), 0, vendor, null, null);
2900
+ // Antigravity: the user hooks file and the project file; a holmes-kit block switched off does not run.
2901
+ for (const file of [opts.agyUserHooks ?? (0, agents_1.agyUserHooksPath)(), path.join(target, '.agents', 'hooks.json')]) {
2902
+ const block = json(file)?.['holmes-kit'];
2903
+ if (!block || block.enabled === false || !Array.isArray(block.Stop))
2904
+ continue;
2905
+ if (block.Stop.some((h) => isHolmesStop(h?.command) && short(h?.timeout)))
2906
+ stale.push({ file, harness: 'antigravity' });
2907
+ }
2908
+ const unread = unreadable.length === 0 ? ''
2909
+ : `Codex plugin snapshot could not be read, so its Stop timeout is unknown: ${unreadable.join(', ')}`;
2910
+ if (stale.length === 0 && unread === '')
2911
+ return { name: 'stop hook timeout', level: 'PASS', detail: `Every Holmes Stop hook that runs allows at least ${STOP_HOOK_TIMEOUT_SECONDS} s` };
2912
+ if (stale.length === 0)
2913
+ return {
2914
+ name: 'stop hook timeout', level: 'WARN', detail: unread,
2915
+ fix: 'Make the snapshot readable by this user, or uninstall that Holmes plugin in Codex and reinstall it from the current workspace',
2916
+ };
2917
+ return {
2918
+ name: 'stop hook timeout', level: 'WARN',
2919
+ 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}`}`,
2920
+ fix: 'Run holmes-kit runtime-binding setup again (operator), or holmes-kit init for a workspace init wired'
2921
+ + (stale.some((s) => s.harness === 'codex') ? '; then trust the rewritten Codex Stop hook once with /hooks' : '')
2922
+ + (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' : ''),
2923
+ };
2924
+ }
2925
+ catch {
2926
+ return null;
2927
+ } // diagnosis must never crash doctor
2928
+ }
2929
+ // @implements A-SPEC-769.19
2930
+ /**
2931
+ * Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate: Codex sessions end without the constitution
2932
+ * check. Measured 2026-10-16 in the dev root (user Stop switched off at timeout 30, project `Stop: []`). No row when no
2933
+ * Holmes Codex PreToolUse gate runs — that is a workspace Codex does not govern, not a half-wired one.
2934
+ */
2935
+ function codexStopGateCheck(target, opts = {}) {
2936
+ try {
2937
+ const reading = { codexPre: false, codexStop: false, dormant: [], untrusted: [] };
2938
+ if (stopHookTimeoutCheck(target, { ...opts, codexGate: reading }) === null)
2939
+ return null;
2940
+ if (!reading.codexPre)
2941
+ return null;
2942
+ // @implements A-SPEC-769.20 — a trust record is required; whether it still matches the entry is Codex's to judge.
2943
+ if (reading.codexStop)
2944
+ return { name: 'codex stop gate', level: 'PASS', detail: 'Codex has trusted Holmes PreToolUse and Stop gates for this workspace (an entry changed since it was trusted needs /hooks trust again)' };
2945
+ const { STOP_HOOK_TIMEOUT_SECONDS } = require('../runtime/hook-process');
2946
+ const short = reading.dormant.filter((d) => d.timeout !== null && d.timeout < STOP_HOOK_TIMEOUT_SECONDS);
2947
+ const named = reading.dormant.map((d) => `${d.file}${d.timeout === null ? '' : ` (timeout ${d.timeout} s)`}`);
2948
+ return {
2949
+ name: 'codex stop gate', level: 'WARN',
2950
+ detail: 'Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate — Codex sessions end without the Stop check'
2951
+ + (reading.untrusted.length ? `; wired but not yet trusted in Codex (/hooks): ${[...new Set(reading.untrusted)].join(', ')}` : '')
2952
+ + (named.length ? `; switched off in Codex: ${named.join(', ')}` : '')
2953
+ + (short.length ? `; switched on as it stands, a timeout below ${STOP_HOOK_TIMEOUT_SECONDS} s lets Codex kill the Stop before its 60 s deadline answers` : ''),
2954
+ fix: `Operator: holmes-kit runtime-binding setup --workspace ${target} --package <checkout> --release-package <install> --activate-hooks codex`
2955
+ + ` (or the runtime_binding tool with activate_hooks: ['codex']) writes a project Stop at ${STOP_HOOK_TIMEOUT_SECONDS} s; then trust it once with /hooks in Codex`
2956
+ + (short.length ? `. Before switching a listed entry back on instead, raise its timeout to ${STOP_HOOK_TIMEOUT_SECONDS}` : ''),
2957
+ };
2958
+ }
2959
+ catch {
2960
+ return null;
2961
+ } // diagnosis must never crash doctor
2962
+ }
2686
2963
  // @implements A-SPEC-664
2687
2964
  // The CI matrix as doctor sees it: PASS only for a green row at HEAD; everything else is a WARN that
2688
2965
  // says exactly what the ledger says — "not run" when there is no row, the failed suites when red,