@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 +79 -0
- package/README.md +2 -2
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/doctor.d.ts +35 -0
- package/dist/holmes/cli/doctor.js +278 -1
- package/dist/holmes/cli/runtime-binding.js +190 -174
- package/dist/holmes/cli/settings-merge.d.ts +1 -0
- package/dist/holmes/cli/settings-merge.js +6 -2
- package/dist/holmes/cpg/scan-cache.d.ts +1 -0
- package/dist/holmes/cpg/scan-cache.js +11 -0
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +16 -0
- package/dist/holmes/hooks/rtm-refresh-child.js +49 -15
- package/dist/holmes/hooks/rtm-refresh.d.ts +22 -0
- package/dist/holmes/hooks/rtm-refresh.js +117 -13
- package/dist/holmes/mcp/handlers/graph-operations.js +7 -4
- package/dist/holmes/mcp/handlers/requirement-triage.js +6 -2
- package/dist/holmes/mcp/requirement-triage-evidence.d.ts +7 -0
- package/dist/holmes/mcp/requirement-triage-evidence.js +18 -7
- package/dist/holmes/project/bounded-io.d.ts +1 -0
- package/dist/holmes/project/bounded-io.js +3 -1
- package/dist/holmes/refresh/freshness-coordinator.d.ts +15 -0
- package/dist/holmes/refresh/freshness-coordinator.js +46 -3
- package/package.json +1 -1
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
|

|
|
11
11
|
|
|
12
|
-
**440/442** source files (99.5%) trace to an approved spec · **
|
|
13
|
-
Measured at `
|
|
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
|
-
|
|
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,
|