@holmes-lab/holmes-kit 0.35.22 → 0.35.24

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,76 @@ 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.24] - 2026-10-17
11
+
12
+ Upgrading: run `holmes-kit runtime-binding setup` again with this build, so the deployed dispatcher passes the routing
13
+ mode to the hooks. Until you do, doctor says "the deployed dispatcher does not report its routing mode". After setup,
14
+ trust the rewritten Codex hooks once with `/hooks`. A Codex Stop hook under 75 s is now a doctor FAIL.
15
+
16
+ ### Added
17
+
18
+ - **Each harness's hooks leave evidence that they ran** (REQ-772, A-SPEC-772.1). The PreToolUse and Stop kernels write
19
+ a small per-harness record under `.ax/state/hook-heartbeat/`. The record is git-ignored, written at most once a minute,
20
+ and never changes a hook decision. Antigravity is named by its adapter and routed hooks by the dispatcher
21
+ (`HOLMES_HOOK_HARNESS`, which must agree with the input shape). Claude and Codex are otherwise named by their hook
22
+ input. Harness environment markers such as `CLAUDECODE` are never read: a Codex hook received `CLAUDECODE=1`.
23
+ - `workspace_preflight` with `harness` reports `runtime-enforcement` as `pass` only after that harness's PreToolUse
24
+ gate was observed within 24 h and since its wiring last changed. Otherwise it is `unknown`, naming why: never
25
+ observed, stale, only the Stop observed, or wiring changed.
26
+ - doctor shows one `hook observed (<harness>)` row per harness (honouring `--agent`).
27
+ - `runtime-binding status` reports `activation: observed` only for this selection's PreToolUse gate. It names
28
+ other-build, other-mode and Stop-only observations per event (`observedOther`), the latest observation without
29
+ routing evidence (`observedUnrouted`), and an outdated deployed dispatcher (`routerOutdated`).
30
+ - `HOLMES_HEARTBEAT=off` turns recording off, for tests that spawn the real kernel inside a repository. preflight and
31
+ doctor's observation rows say so when their own environment has it.
32
+ - Known limit: a user-level Codex `/hooks` switch-off or plugin disable lives in the machine-shared
33
+ `~/.codex/config.toml` and does not mark an observation stale.
34
+
35
+ Specs: A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10,
36
+ A-SPEC-772.11.
37
+
38
+ ### Fixed
39
+
40
+ - **`runtime_binding` no longer answers "not registered" for a governed workspace** (A-SPEC-772). A workspace with no
41
+ development binding is answered with its routing: the release build and package routed hooks run, `unrouted` without
42
+ a registry, or `unroutable` with the reason. Measured in holmes-lab: a Codex session read "not registered" as "not
43
+ governed".
44
+ - **init states a Codex verdict when the operator registry owns the Codex files** (A-SPEC-772.2, A-SPEC-772.4,
45
+ A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7).
46
+ - The line names the routing and the trust state of the routed gates.
47
+ - It adds an operator line when a Codex Stop hook is under 75 s.
48
+ - It names a workspace Codex marks untrusted.
49
+ - The `~/.codex/config.toml` receipt ignores Codex's own trust, project and notice tables, so it is no longer
50
+ permanent drift.
51
+ - **doctor FAILs a running Holmes Stop hook under 75 s** (A-SPEC-772.3, A-SPEC-772.5, A-SPEC-772.6). This covers Claude entries
52
+ (unless Claude's hooks are switched off), Antigravity entries, and trusted Codex user, project or plugin entries.
53
+ Untrusted or switched-off entries stay WARN.
54
+ - **init re-merges the Codex plugin `hooks.json`** (A-SPEC-772.3, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8). The merge:
55
+ - keeps every group and handler at its index, because Codex keys trust by index;
56
+ - keeps foreign handlers and leaves operator routers in place;
57
+ - recognizes only the command shapes Holmes writes;
58
+ - writes Stop in group shape.
59
+
60
+ ## [0.35.23] - 2026-10-17
61
+
62
+ Upgrading: run `holmes-kit runtime-binding setup` again so the hooks run this build. A binding whose workspace was
63
+ emptied or deleted can now be removed: run `holmes-kit runtime-binding remove --workspace <path>` from a governed
64
+ workspace and grant the request it queues there; with several dead bindings, remove them one at a time.
65
+
66
+ ### Fixed
67
+
68
+ - **`runtime-binding remove` works on a workspace that is no longer a governed project** (A-SPEC-752.14). Removing a
69
+ workspace whose `.ax` was deleted failed with "Cannot queue governance-wiring approval: no-project", and a workspace
70
+ whose directory was gone could not be named at all — a dead binding could only be deleted from the operator registry
71
+ by hand. For a workspace without `.ax` the approval is now queued, granted and consumed in the governed workspace the
72
+ operator runs `remove` from (the request still names the removed workspace); with none, remove is refused and nothing
73
+ is written — no `.ax` is planted in the removed workspace any more (A-SPEC-752.15).
74
+ - **One vanished binding no longer blocks the removal of another** (A-SPEC-752.15, 752.16, 752.17). Remove sets aside
75
+ every binding whose workspace directory is gone, validates the rest as before, and writes the set-aside ones back
76
+ unchanged, so each dead binding can be removed in turn; their receipt rows stay with them. A vanished binding is
77
+ matched by resolved path, duplicate spellings of one root are refused, and a remove that matches nothing of its own
78
+ says "Nothing registered".
79
+
10
80
  ## [0.35.22] - 2026-10-16
11
81
 
12
82
  Upgrading: run `holmes-kit runtime-binding setup` again so the hooks run this build, then `holmes-kit doctor`. A `codex
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 · **803/866** approved A-SPECs (92.7%) are anchored from code.
13
- Measured at `bc705710c89e` (specs `sha256:9ddf0c3d9cee`) — reproduce with `holmes-kit attest`.
12
+ **442/444** source files (99.5%) trace to an approved spec · **819/882** approved A-SPECs (92.8%) are anchored from code.
13
+ Measured at `20e40719f1f2` (specs `sha256:0263ca8394c8`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,7 @@ Measured at `bc705710c89e` (specs `sha256:9ddf0c3d9cee`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **You can tell whether a harness's gate actually ran here** *(new in 0.35.24)*: the PreToolUse and Stop hooks of Claude Code, Codex and Antigravity leave a git-ignored per-harness record (`.ax/state/hook-heartbeat/`, at most one write a minute, never part of a decision). `workspace_preflight` with `harness` passes `runtime-enforcement` only after that harness's PreToolUse gate was observed within 24 h and since its wiring last changed; doctor shows one `hook observed (<harness>)` row each; `runtime-binding status` reports `activation` for this selection's gate and names every other observation and an outdated deployed dispatcher. `runtime_binding` answers an unbound workspace with its routing instead of "not registered", init states a Codex verdict for registry-owned Codex files, and doctor FAILs a running Stop hook under 75 s. Measured need: a Codex session in a release-routed workspace concluded it was ungoverned.
26
27
  - **A benchmark run the operator pre-approved finishes with zero human waits — the run delegation** *(new in 0.35.19)*: `holmes-kit autonomy delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]` (same human proof as `autonomy on`) writes a run-scoped, workspace-bound (realpath), expiring delegation that covers a closed set of autonomy-grader rules — root-only or gate-file Files to Touch, an undirected gate-behavior grade, an upstream without A-SPEC; never architecture documents, un-admitted requirements, undeclared or unknown grades. A hitl spec whose only reason is a covered rule seals on its own with `source: 'delegated'` and a ledger row naming the run and the rule; an uncovered case refuses with the named limit (`does not cover`, `expired`, `for <workspace>, not this root`, `invalid document`). `autonomy status`, `approve --status` and the session-start banner show it; `revoke-delegation` or `off` ends it. The host's own approval layer is named as not covered. Measured need: X1 (2026-10-12) stopped a pre-approved fixture on `files-to-touch-root-only`. Every operator hint now also names the workspace (`--target <root>`), a context-only Codex patch is refused as a no-op by name, and `runtime-binding status`/`doctor` report a Codex lifecycle routed to Holmes from both the user-level and the workspace hooks file.
27
28
  - **A refusal you cannot see in the inbox is still answerable from its own hint** *(new in 0.35.18)*: six repairs measured in a Codex X1 runtime session and a field report. Every refusal line written to the refusal log ends with `run: holmes-kit approve --grant <id> --target <root>` carrying the actual id, the inbox (`approve --list` / `--watch`) prints a footer counting requests outside the inbox, and the `--refusals` closing line spells the same command (the positional `approve <id>` the first repair wrote is refused by the CLI, so it was measured and rewritten). An autonomy refusal on a parent spec names the child rule that forces the human decision (`upstream-has-human-aspec: <id> — <rule>`). A runtime deadline refusal ends with the per-phase millisecond split, and the Stop hook prints how much of its 18 s budget it used once it passes half. `runtime-binding status` separates `drift` (operator-config / stale-workspace) from `conflicts` and reports whether the router is intact. The `--autonomy` usage, the `init` refusal and the interactive prompt now say the same thing.
28
29
  - **An agent is told what to do after an approval, and a patch is judged the way the tool applies it** *(new in 0.35.17)*: five repairs measured on a Codex worker in a SWE-bench comparison. `approval_status` now carries `request { id, state, question?, reason?, ts? }` (pending / held / granted / consumed / denied / revoked, read from the approval queue, with the operator's LATEST hold question) and one `nextAction` sentence — a sealed spec says "stop polling", a held request relays the question; the pending-approval hint ends with an `Agent:` line beside the unchanged operator lines. `test_run` reports `anchorDiagnostics` for an `@implements` list joined by `;`, `|`, `&`, `/` or `and` (the comma grammar does not read them; attribution is unchanged, the omission is named). A Codex `apply_patch` update is applied chunk by chunk from the previous chunk's position, as the tool does, so a context line that recurs earlier in the file no longer makes it "unreadable", and a patch that does not apply is refused by a sentence naming the file and the chunk. A quoted or escaped glob (`rg ".*"`) is no longer read as a spelling of the `.ax` store (an unquoted `.*` still is). The background refresh child records `failure { stage, reason }` on its freshness receipt instead of failing silently.
@@ -308,7 +309,7 @@ flowchart LR
308
309
  | `holmes-kit init --autonomy` | Opt the project into autonomous spec approval (low-risk only; governance-critical still HITL) |
309
310
  | `holmes-kit init --dry-run` | Preview files and configuration changes without writing |
310
311
  | `holmes-kit runtime-binding setup --workspace <root> --package <built-package> --release-package <release-install> --dry-run` | Preview explicit development/release routing; omit `--dry-run` only after reviewing the plan and satisfying its approval request |
311
- | `holmes-kit runtime-binding status --workspace <root>` | Inspect selected package, build, spec store and wiring conflicts; not proof of active hooks |
312
+ | `holmes-kit runtime-binding status --workspace <root>` | Inspect selected package, build, spec store and wiring conflicts, and whether this selection's PreToolUse gate was observed running (`activation`); an observation is evidence the hook ran, not a guarantee every call is judged |
312
313
  | `holmes-kit doctor --target <root> --registry <bindings.json>` | Diagnose the same operator registry used by custom routing installations |
313
314
  | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
314
315
  | `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 8dd234f5-mvb0beqr
1
+ ba30504b-mvc1xwsd
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The harness registry, with no imports: hook processes read it on every call (the heartbeat), and pulling it from
3
+ * `cli/agents.ts` loaded seven modules (guidance, launcher, …) into every PreToolUse — measured +8 ms (2026-10-17).
4
+ * `cli/agents.ts` re-exports these, so every existing import keeps working and ADR-018's single registry stays one list.
5
+ */
6
+ export declare const AGENTS: readonly ["claude", "antigravity", "codex"];
7
+ export type Agent = (typeof AGENTS)[number];
@@ -0,0 +1,10 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AGENTS = void 0;
4
+ // @implements A-SPEC-772.6
5
+ /**
6
+ * The harness registry, with no imports: hook processes read it on every call (the heartbeat), and pulling it from
7
+ * `cli/agents.ts` loaded seven modules (guidance, launcher, …) into every PreToolUse — measured +8 ms (2026-10-17).
8
+ * `cli/agents.ts` re-exports these, so every existing import keeps working and ADR-018's single registry stays one list.
9
+ */
10
+ exports.AGENTS = ['claude', 'antigravity', 'codex'];
@@ -7,8 +7,8 @@ import { LauncherMode } from './mcp-launcher';
7
7
  * 없다면 **집행한다고 말하지 않는 것**이 이 파일의 일이다. 도구는 주되 규율은 못 세우면서
8
8
  * 세운다고 적으면, 그 문장을 믿은 사용자가 지켜지지 않는 게이트 위에서 일한다.
9
9
  */
10
- export declare const AGENTS: readonly ["claude", "antigravity", "codex"];
11
- export type Agent = (typeof AGENTS)[number];
10
+ import { AGENTS, type Agent } from './agent-registry';
11
+ export { AGENTS, type Agent };
12
12
  /**
13
13
  * 그 하네스에서 게이트가 **집행되는가**.
14
14
  *
@@ -51,7 +51,7 @@ exports.agentLinks = agentLinks;
51
51
  exports.agyOtherHooksFiles = agyOtherHooksFiles;
52
52
  exports.agySwitches = agySwitches;
53
53
  exports.agyCanonicalFile = agyCanonicalFile;
54
- // @implements A-SPEC-708, A-SPEC-707, A-SPEC-202, A-SPEC-250, A-SPEC-341
54
+ // @implements A-SPEC-708, A-SPEC-707, A-SPEC-202, A-SPEC-250, A-SPEC-341, A-SPEC-772.3, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8
55
55
  // @implements A-SPEC-442
56
56
  // @implements A-SPEC-193
57
57
  // @implements A-SPEC-769.10
@@ -71,7 +71,9 @@ const hook_process_1 = require("../runtime/hook-process");
71
71
  * 없다면 **집행한다고 말하지 않는 것**이 이 파일의 일이다. 도구는 주되 규율은 못 세우면서
72
72
  * 세운다고 적으면, 그 문장을 믿은 사용자가 지켜지지 않는 게이트 위에서 일한다.
73
73
  */
74
- exports.AGENTS = ['claude', 'antigravity', 'codex'];
74
+ // @implements A-SPEC-772.6 — defined in the import-free registry module; re-exported here for every existing caller.
75
+ const agent_registry_1 = require("./agent-registry");
76
+ Object.defineProperty(exports, "AGENTS", { enumerable: true, get: function () { return agent_registry_1.AGENTS; } });
75
77
  /**
76
78
  * 그 하네스에서 게이트가 **집행되는가**.
77
79
  *
@@ -490,12 +492,197 @@ function agyUserSwitch(file = agyUserHooksPath()) {
490
492
  return { off: false, unconfirmed: `the holmes-kit entry in ${file} has "enabled" that is not true or false` };
491
493
  return { off: false, unconfirmed: null };
492
494
  }
495
+ /**
496
+ * @implements A-SPEC-772.3 — the Codex shape (`{ hooks: { <Event>: [group] } }`): per event, the groups that hold a
497
+ * Holmes kernel command — as a group's handler or as a flat handler (the shape init wrote before) — are replaced by ours;
498
+ * every other group and top-level key is kept. Measured 2026-10-17: the namespace merge below kept the whole previous
499
+ * file and named our own `hooks` key as foreign, so the plugin file was never updated after its first write.
500
+ */
501
+ /**
502
+ * @implements A-SPEC-772.6 — what a handler runs, judged by its script token (the first token, or the second after a
503
+ * `node` executable): a Holmes kernel, a Holmes Codex router, or neither. A wrapper that merely mentions a kernel path
504
+ * later in its arguments is a foreign command (round 2 measured it deleted as "ours").
505
+ */
506
+ function holmesScriptKind(h) {
507
+ if (h === null || typeof h !== 'object' || typeof h.command !== 'string')
508
+ return null;
509
+ // @implements A-SPEC-772.7 — only the shapes Holmes writes: `<node> <absolute script>` or the script alone, as shell
510
+ // words (single quotes with '\'' escapes, double quotes). Any operator, flag or further word makes it foreign — a
511
+ // looser match deleted `node …/stop.js && curl …` as ours and missed `nodejs` routers (round 3).
512
+ const words = [];
513
+ let cur = '';
514
+ let inWord = false;
515
+ let quote = null;
516
+ let escaped = false;
517
+ const text = h.command.trim();
518
+ for (let i = 0; i < text.length; i++) {
519
+ const ch = text[i];
520
+ // @implements A-SPEC-772.8 — outside quotes `\` is accepted only as the `'\''` apostrophe escape a router writes.
521
+ if (escaped) {
522
+ if (ch !== "'")
523
+ return null;
524
+ cur += ch;
525
+ escaped = false;
526
+ inWord = true;
527
+ continue;
528
+ }
529
+ // @implements A-SPEC-772.8 — the shell expands `$` and backticks inside double quotes, and `\` escapes there before
530
+ // `$`, a backtick, `"` or `\`: none is a shape Holmes writes. A `\` before anything else is literal (Windows paths).
531
+ if (quote === '"' && (ch === '$' || ch === '`' || (ch === '\\' && /[$`"\\]/.test(text[i + 1] ?? ''))))
532
+ return null;
533
+ if (quote) {
534
+ if (ch === quote)
535
+ quote = null;
536
+ else
537
+ cur += ch;
538
+ continue;
539
+ }
540
+ if (ch === '\\') {
541
+ escaped = true;
542
+ continue;
543
+ }
544
+ if (ch === "'" || ch === '"') {
545
+ quote = ch;
546
+ inWord = true;
547
+ continue;
548
+ }
549
+ if (/\s/.test(ch)) {
550
+ if (inWord) {
551
+ words.push(cur);
552
+ cur = '';
553
+ inWord = false;
554
+ }
555
+ continue;
556
+ }
557
+ if (/[;&|<>`$()*?]/.test(ch))
558
+ return null;
559
+ cur += ch;
560
+ inWord = true;
561
+ }
562
+ if (quote || escaped)
563
+ return null;
564
+ if (inWord)
565
+ words.push(cur);
566
+ const nodeExec = (w) => /^node(?:js)?\d*(?:\.exe)?$/i.test(w.split(/[/\\]/).pop() ?? '');
567
+ const script = words.length === 1 ? words[0] : words.length === 2 && nodeExec(words[0]) ? words[1] : null;
568
+ if (script === null || !(script.startsWith('/') || /^[A-Za-z]:[/\\]/.test(script)))
569
+ return null;
570
+ if (/[/\\]dist[/\\]holmes[/\\]hooks[/\\](?:pre-tool-use|stop)\.js$/.test(script))
571
+ return 'kernel';
572
+ if (/[/\\]\.holmes[/\\]runtime[/\\]codex-(?:pre-tool-use|stop)\.js$/.test(script))
573
+ return 'router';
574
+ // @implements A-SPEC-772.8 — a router written beside a registry given with --registry: its folder holds the dispatcher.
575
+ if (/[/\\]codex-(?:pre-tool-use|stop)\.js$/.test(script)) {
576
+ try {
577
+ if (fs.existsSync(path.join(path.dirname(script), 'dispatch.js')))
578
+ return 'router';
579
+ }
580
+ catch { /* unreadable: not ours */ }
581
+ }
582
+ return null;
583
+ }
584
+ function mergeCodexHooksByEvent(prev, oursObj, before) {
585
+ const handlersOf = (g) => (g !== null && typeof g === 'object' && Array.isArray(g.hooks)) ? g.hooks : [g];
586
+ const unchanged = (why) => ({ content: before ?? `${JSON.stringify(prev, null, 2)}\n`, preserved: [], notes: [`Codex plugin hooks.json not merged: ${why}; it was left as it is`] });
587
+ if (prev.hooks !== undefined && (prev.hooks === null || typeof prev.hooks !== 'object' || Array.isArray(prev.hooks)))
588
+ return unchanged('its "hooks" is not an object');
589
+ const prevHooks = (prev.hooks ?? {});
590
+ const ourHooks = oursObj.hooks;
591
+ for (const event of Object.keys(ourHooks))
592
+ if (prevHooks[event] !== undefined && !Array.isArray(prevHooks[event]))
593
+ return unchanged(`its ${event} is not a list`);
594
+ const merged = { ...prevHooks };
595
+ const preserved = [];
596
+ const notes = [];
597
+ for (const [event, groupsRaw] of Object.entries(ourHooks)) {
598
+ const groups = Array.isArray(groupsRaw) ? groupsRaw : [];
599
+ const old = prevHooks[event];
600
+ if (old === undefined) {
601
+ merged[event] = groups;
602
+ continue;
603
+ }
604
+ // @implements A-SPEC-772.5/772.6 — an event emptied on purpose (setup empties the legacy plugin) stays empty, said.
605
+ if (old.length === 0) {
606
+ merged[event] = [];
607
+ notes.push(`${event} is empty on purpose and was not re-wired (holmes-kit runtime-binding setup manages it when routed)`);
608
+ continue;
609
+ }
610
+ // @implements A-SPEC-772.6 — operator routing is not replaced by a direct kernel command.
611
+ if (old.some((g) => handlersOf(g).some((h) => holmesScriptKind(h) === 'router'))) {
612
+ merged[event] = old;
613
+ old.forEach((g, i) => { if (!handlersOf(g).every((h) => holmesScriptKind(h) !== null))
614
+ preserved.push(`${event} group ${i + 1}`); });
615
+ continue;
616
+ }
617
+ // @implements A-SPEC-772.6 — Codex keys trust and switch-off by index (`<file>:<event>:<i>:<j>`): our group is
618
+ // replaced where it stands, foreign groups keep their positions, and ours is appended only when no group was ours.
619
+ const out = [];
620
+ let placed = false;
621
+ for (const g of old) {
622
+ const hs = handlersOf(g);
623
+ const mine = hs.filter((h) => holmesScriptKind(h) === 'kernel');
624
+ if (mine.length === 0) {
625
+ out.push(g);
626
+ preserved.push(`${event} group ${out.length}`);
627
+ continue;
628
+ }
629
+ if (mine.length === hs.length) {
630
+ if (!placed) {
631
+ out.push(...groups);
632
+ placed = true;
633
+ }
634
+ continue;
635
+ }
636
+ // @implements A-SPEC-772.7 — a mixed group with our matcher keeps our handler at its own index j (Codex keys
637
+ // trust per handler); with another matcher ours cannot live there, so it is stripped and our group appended.
638
+ const ourGroup = groups[0];
639
+ // @implements A-SPEC-772.8 — Codex does not match Stop; for PreToolUse a missing matcher, '', '*' and '.*' all mean every tool.
640
+ const everyTool = (m) => m === undefined || m === null || m === '' || m === '*' || m === '.*';
641
+ const matcherEq = (a, b) => event === 'Stop' || a === b || (everyTool(a) && everyTool(b));
642
+ const sameMatcher = ourGroup !== undefined && matcherEq(g.matcher, ourGroup.matcher) && Array.isArray(ourGroup.hooks);
643
+ if (!placed && sameMatcher) {
644
+ let first = true;
645
+ const hooks = [];
646
+ for (const h of hs) {
647
+ if (holmesScriptKind(h) !== 'kernel') {
648
+ hooks.push(h);
649
+ continue;
650
+ }
651
+ if (first) {
652
+ hooks.push(...ourGroup.hooks);
653
+ first = false;
654
+ }
655
+ }
656
+ out.push({ ...g, hooks });
657
+ placed = true;
658
+ }
659
+ else {
660
+ out.push({ ...g, hooks: hs.filter((h) => holmesScriptKind(h) !== 'kernel') });
661
+ if (!sameMatcher)
662
+ notes.push(`${event} group ${out.length} shares a ${String(g.matcher ?? 'missing')} matcher with a foreign hook; the Holmes handler was moved to its own group`);
663
+ }
664
+ preserved.push(`${event} group ${out.length}`);
665
+ }
666
+ if (!placed)
667
+ out.push(...groups);
668
+ merged[event] = out;
669
+ }
670
+ for (const event of Object.keys(prevHooks))
671
+ if (!(event in ourHooks) && Array.isArray(prevHooks[event]))
672
+ prevHooks[event].forEach((_g, i) => preserved.push(`${event} group ${i + 1}`));
673
+ const result = { ...prev, ...oursObj, hooks: merged };
674
+ // @implements A-SPEC-772.6 — a file that is already current is left byte for byte.
675
+ const content = before !== null && JSON.stringify(result) === JSON.stringify(prev) ? before : `${JSON.stringify(result, null, 2)}\n`;
676
+ return { content, preserved, notes };
677
+ }
493
678
  /** `.agents/hooks.json`. Top-level keys are tool namespaces; only ours is replaced. */
494
679
  function mergeHooksJson(before, ours) {
495
680
  const parsed = parseOr(before, ours, 'hooks.json');
496
681
  if (isMerge(parsed))
497
682
  return parsed;
498
683
  const oursObj = asObject(JSON.parse(ours));
684
+ if (!(HOLMES in oursObj) && oursObj.hooks !== null && typeof oursObj.hooks === 'object')
685
+ return mergeCodexHooksByEvent(parsed.prev, oursObj, before);
499
686
  const out = { ...parsed.prev, [HOLMES]: oursObj[HOLMES] };
500
687
  return {
501
688
  content: `${JSON.stringify(out, null, 2)}\n`,
@@ -611,10 +798,13 @@ function agentFiles(agent, opts) {
611
798
  timeout: 30,
612
799
  }],
613
800
  }],
801
+ // @implements A-SPEC-772.3 — the group shape every other Codex hooks file uses.
614
802
  Stop: [{
615
- type: 'command',
616
- command: kernelCommand(packageRoot, 'stop.js'),
617
- timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS, // A-SPEC-769.10
803
+ hooks: [{
804
+ type: 'command',
805
+ command: kernelCommand(packageRoot, 'stop.js'),
806
+ timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS, // A-SPEC-769.10
807
+ }],
618
808
  }],
619
809
  },
620
810
  }, null, 2)}\n`,
@@ -623,7 +813,7 @@ function agentFiles(agent, opts) {
623
813
  ];
624
814
  default:
625
815
  // 모르는 하네스를 조용히 건너뛰면 "배선했다"는 보고와 실제가 어긋난다.
626
- throw new Error(`알 수 없는 하네스: ${String(agent)} — 아는 것: ${exports.AGENTS.join(', ')}`);
816
+ throw new Error(`알 수 없는 하네스: ${String(agent)} — 아는 것: ${agent_registry_1.AGENTS.join(', ')}`);
627
817
  }
628
818
  }
629
819
  /**
@@ -239,7 +239,23 @@ export type CodexGateReading = {
239
239
  timeout: number | null;
240
240
  }[];
241
241
  untrusted: string[];
242
+ /** @implements A-SPEC-772.5 — Codex Holmes Stops below 75 s that are not switched off, and whether Codex runs them now. */
243
+ shortStops?: {
244
+ file: string;
245
+ runs: boolean;
246
+ }[];
242
247
  };
248
+ /**
249
+ * One row per harness: has this harness's PreToolUse or Stop hook been observed running in the target within 24 h?
250
+ * Measured 2026-10-17: nothing recorded a hook run, so a governed Codex session could not tell it was governed. The
251
+ * row reports an observation, never enforcement; a target without `.ax` is not a governed workspace and gets none.
252
+ */
253
+ /**
254
+ * @implements A-SPEC-772.11 — the runtime binding row's activation words, narrowed by --agent: "observed (claude)"
255
+ * beside a Codex-only report read as Codex's activation.
256
+ */
257
+ export declare function activationText(observed: string[], agent?: string): string;
258
+ export declare function hookObservationChecks(targetIn: string, now?: number, agent?: Agent): Check[];
243
259
  /**
244
260
  * Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate: Codex sessions end without the constitution
245
261
  * check. Measured 2026-10-16 in the dev root (user Stop switched off at timeout 30, project `Stop: []`). No row when no
@@ -53,6 +53,8 @@ exports.wiringSpawnCheck = wiringSpawnCheck;
53
53
  exports.mcpProbeEnv = mcpProbeEnv;
54
54
  exports.pushGateCheck = pushGateCheck;
55
55
  exports.stopHookTimeoutCheck = stopHookTimeoutCheck;
56
+ exports.activationText = activationText;
57
+ exports.hookObservationChecks = hookObservationChecks;
56
58
  exports.codexStopGateCheck = codexStopGateCheck;
57
59
  exports.ciMatrixCheck = ciMatrixCheck;
58
60
  exports.checksJson = checksJson;
@@ -69,7 +71,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
69
71
  exports.semanticCoverageCheck = semanticCoverageCheck;
70
72
  exports.semanticTierVerdict = semanticTierVerdict;
71
73
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
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
74
+ // @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, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
73
75
  // @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
74
76
  const doctor_guidance_1 = require("./doctor-guidance");
75
77
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -750,10 +752,17 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
750
752
  const drift = report.drift ?? [];
751
753
  const changedSinceInstall = drift.filter((d) => d.kind === 'operator-config').map((d) => d.path);
752
754
  const staleRows = drift.filter((d) => d.kind === 'stale-workspace').map((d) => d.path);
753
- add('runtime binding', report.conflicts.length ? 'FAIL' : 'WARN', `${s.mode}: workspace=${s.workspaceRoot}; package=${s.packageRoot}; build=${s.buildId}${own}; specs=${s.specsRoot}; live activation unverified`
755
+ add('runtime binding', report.conflicts.length ? 'FAIL' : 'WARN',
756
+ // @implements A-SPEC-772.10 — the activation status reports, not a fixed "unverified" beside a PASS observation.
757
+ `${s.mode}: workspace=${s.workspaceRoot}; package=${s.packageRoot}; build=${s.buildId}${own}; specs=${s.specsRoot}; ${activationText(Object.keys(report.observed ?? {}), opts?.agent)}`
754
758
  + (report.conflicts.length ? `; ${report.conflicts.join('; ')}` : '')
755
759
  + (changedSinceInstall.length ? `; changed since installation (operator-owned, still routed): ${changedSinceInstall.join(', ')}` : '')
756
- + (staleRows.length ? `; stale receipt rows (workspace gone): ${staleRows.join(', ')}` : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
760
+ + (staleRows.length ? `; stale receipt rows (workspace gone): ${staleRows.join(', ')}` : '')
761
+ // @implements A-SPEC-772.7 — a router deployed by an older setup runs older code than the selected build.
762
+ + ((report.routerOutdated ?? []).length
763
+ // @implements A-SPEC-772.9 — a capability check (772.8), and the advice names a build that can clear it.
764
+ ? `; the deployed dispatcher does not report its routing mode (${(report.routerOutdated ?? []).join(', ')} predates it) — re-run holmes-kit runtime-binding setup with a holmes-kit build that reports it (newer than 0.35.23, or the development checkout)`
765
+ : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
757
766
  // @implements A-SPEC-769.8 — one WARN per Codex lifecycle routed to Holmes from both the user-level and the
758
767
  // workspace hooks file (measured 2026-10-12: the Stop hook ran twice per session end in both X1 fixtures).
759
768
  for (const d of report.duplicateRoutes ?? []) {
@@ -2064,7 +2073,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
2064
2073
  const h = JSON.parse(fs.readFileSync(cdxHooksJson, 'utf8'));
2065
2074
  const manifest = JSON.parse(fs.readFileSync(cdxPluginJson, 'utf8'));
2066
2075
  const preCmd = h.hooks?.PreToolUse?.[0]?.hooks?.[0]?.command ?? '';
2067
- const stopCmd = h.hooks?.Stop?.[0]?.command ?? '';
2076
+ // @implements A-SPEC-772.3 — the group shape init now writes, and the flat shape it wrote before.
2077
+ const stopCmd = h.hooks?.Stop?.[0]?.hooks?.[0]?.command ?? h.hooks?.Stop?.[0]?.command ?? '';
2068
2078
  const stale = [preCmd, stopCmd].filter((c) => {
2069
2079
  const p2 = (0, settings_merge_1.hookScriptPath)(c);
2070
2080
  return !relativeScript(p2) && judge(p2) !== 'this' && judge(p2) !== 'unknown';
@@ -2363,6 +2373,17 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
2363
2373
  const cg = codexStopGateCheck(target ?? process.cwd(), { ...(opts?.codexConfigPath ? { codexConfigPath: opts.codexConfigPath } : {}) }); // @implements A-SPEC-769.19
2364
2374
  if (cg)
2365
2375
  checks.push(cg);
2376
+ checks.push(...hookObservationChecks(target ?? process.cwd(), Date.now(), opts?.agent)); // @implements A-SPEC-772.1, A-SPEC-772.6
2377
+ // @implements A-SPEC-772.6 — Codex does not load the hooks of a project it marks untrusted.
2378
+ {
2379
+ const t = target ?? process.cwd();
2380
+ // @implements A-SPEC-772.7 — honours --agent like the observation rows.
2381
+ const forCodex = opts?.agent === undefined || opts.agent === 'codex';
2382
+ const gr = forCodex ? governedRootOf(t) : null; // @implements A-SPEC-772.11 — the project root, not the target
2383
+ const key = gr !== null ? (0, runtime_binding_1.codexProjectUntrusted)(gr, opts?.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)()) : null;
2384
+ if (key !== null)
2385
+ checks.push({ name: 'codex project trust', level: 'WARN', detail: `Codex marks ${key} untrusted — this workspace's project hooks do not load in Codex`, fix: 'Trust the project in Codex (answer the trust prompt, or set trust_level = "trusted" for it in config.toml).' });
2386
+ }
2366
2387
  }
2367
2388
  checks.push(...(0, worktree_readiness_1.worktreeReadinessChecks)(packageRoot, target ?? process.cwd(), { agent: opts?.agent, codexConfigPath: opts?.codexConfigPath }));
2368
2389
  if (extraChecks) {
@@ -2721,15 +2742,25 @@ function stopHookTimeoutCheck(target, opts = {}) {
2721
2742
  } };
2722
2743
  // @implements A-SPEC-769.13 — no timeout is the harness default (600 s on Claude and Codex), not a short one.
2723
2744
  const short = (t) => typeof t === 'number' && t < STOP_HOOK_TIMEOUT_SECONDS;
2745
+ // @implements A-SPEC-772.3 — `runs`: the harness runs this entry now (Claude and Antigravity always; Codex only with a
2746
+ // trust record and not switched off; a plugin snapshot is not counted as running). A running short Stop is FAIL.
2724
2747
  const stale = [];
2725
2748
  // Claude: user settings (CLAUDE_CONFIG_DIR or ~/.claude) and the project files.
2726
2749
  const claudeUser = opts.claudeUserSettings !== undefined ? opts.claudeUserSettings : (0, claude_switches_1.claudeUserSettingsPath)((0, claude_switches_1.claudeSwitchEnv)());
2750
+ // @implements A-SPEC-772.6 — Claude runs no hook while its switches turn hooks off, read as A-SPEC-251.2 measured them
2751
+ // (`disableAllHooks` true in any source holds; managed allowManagedHooksOnly), not per file (A-SPEC-772.5 #5).
2752
+ let claudeOff = false;
2753
+ try {
2754
+ const env = opts.home !== undefined ? { ...(0, claude_switches_1.claudeSwitchEnv)(), home: opts.home, claudeConfigDir: undefined, rawConfigDir: undefined, managedDirs: [] } : (0, claude_switches_1.claudeSwitchEnv)();
2755
+ claudeOff = (0, claude_switches_1.claudeSwitches)(target, env).hooksOff.length > 0;
2756
+ }
2757
+ catch { /* unreadable switches: counted as running, the stricter reading */ }
2727
2758
  for (const file of [claudeUser, path.join(target, '.claude', 'settings.json'), path.join(target, '.claude', 'settings.local.json')]) {
2728
2759
  if (file === null)
2729
2760
  continue;
2730
2761
  const groups = json(file)?.hooks?.Stop;
2731
2762
  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' });
2763
+ stale.push({ file, harness: 'claude', runs: !claudeOff });
2733
2764
  }
2734
2765
  // Codex: switched-off entries are keyed by the path Codex resolved — compare the path as given, its realpath and
2735
2766
  // native realpath, lowercased on Windows (as runtime-binding and codex-oracle do).
@@ -2794,9 +2825,13 @@ function stopHookTimeoutCheck(target, opts = {}) {
2794
2825
  }
2795
2826
  if (!Array.isArray(groups))
2796
2827
  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' });
2828
+ const shortOn = [];
2829
+ groups.forEach((g, i) => (Array.isArray(g?.hooks) ? g.hooks : []).forEach((h, j) => {
2830
+ if (isHolmesStop(h?.command) && short(h?.timeout) && !names.some((n) => off.has(norm(`${n}:stop:${i}:${j}`))))
2831
+ shortOn.push([i, j]);
2832
+ }));
2833
+ if (shortOn.length)
2834
+ stale.push({ file, harness: 'codex', runs: shortOn.some(([i, j]) => names.some((n) => trusted.has(norm(`${n}:stop:${i}:${j}`)))) });
2800
2835
  }
2801
2836
  // @implements A-SPEC-769.14 — Codex runs the plugin snapshot it installed, not the workspace copy: read each
2802
2837
  // `hooks.json` within three levels of a holmes vendor in the plugins cache (the walk runtime-binding makes). Init
@@ -2885,8 +2920,11 @@ function stopHookTimeoutCheck(target, opts = {}) {
2885
2920
  const prefix = `${plugin}@${vendor}:${path.relative(base ?? at, f).split(path.sep).join('/')}:stop:`;
2886
2921
  const runs = stops.some((g, i) => handlers(g).some((h, j) => isHolmesStop(h?.command) && short(h?.timeout)
2887
2922
  && !off.has(norm(`${prefix}${i}:${j}`)) && !(Array.isArray(g?.hooks) ? false : off.has(norm(`${prefix}${i}`)))));
2923
+ // @implements A-SPEC-772.5 — trusted as A-SPEC-769.19 reads a snapshot's gates: then Codex runs this Stop now.
2924
+ const trustedShort = stops.some((g, i) => handlers(g).some((h, j) => isHolmesStop(h?.command) && short(h?.timeout)
2925
+ && !off.has(norm(`${prefix}${i}:${j}`)) && (trusted.has(norm(`${prefix}${i}:${j}`)) || (!Array.isArray(g?.hooks) && trusted.has(norm(`${prefix}${i}`))))));
2888
2926
  if (runs)
2889
- stale.push({ file: f, harness: 'codex-plugin' });
2927
+ stale.push({ file: f, harness: 'codex-plugin', runs: trustedShort });
2890
2928
  }
2891
2929
  }
2892
2930
  };
@@ -2903,8 +2941,11 @@ function stopHookTimeoutCheck(target, opts = {}) {
2903
2941
  if (!block || block.enabled === false || !Array.isArray(block.Stop))
2904
2942
  continue;
2905
2943
  if (block.Stop.some((h) => isHolmesStop(h?.command) && short(h?.timeout)))
2906
- stale.push({ file, harness: 'antigravity' });
2944
+ stale.push({ file, harness: 'antigravity', runs: true });
2907
2945
  }
2946
+ // @implements A-SPEC-772.5 — init's operator line reads which short Codex Stops exist and whether they run now.
2947
+ if (gateReading)
2948
+ gateReading.shortStops = stale.filter((s) => s.harness === 'codex' || s.harness === 'codex-plugin').map((s) => ({ file: s.file, runs: s.runs === true }));
2908
2949
  const unread = unreadable.length === 0 ? ''
2909
2950
  : `Codex plugin snapshot could not be read, so its Stop timeout is unknown: ${unreadable.join(', ')}`;
2910
2951
  if (stale.length === 0 && unread === '')
@@ -2915,7 +2956,7 @@ function stopHookTimeoutCheck(target, opts = {}) {
2915
2956
  fix: 'Make the snapshot readable by this user, or uninstall that Holmes plugin in Codex and reinstall it from the current workspace',
2916
2957
  };
2917
2958
  return {
2918
- name: 'stop hook timeout', level: 'WARN',
2959
+ name: 'stop hook timeout', level: stale.some((s) => s.runs === true) ? 'FAIL' : 'WARN',
2919
2960
  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
2961
  fix: 'Run holmes-kit runtime-binding setup again (operator), or holmes-kit init for a workspace init wired'
2921
2962
  + (stale.some((s) => s.harness === 'codex') ? '; then trust the rewritten Codex Stop hook once with /hooks' : '')
@@ -2926,6 +2967,63 @@ function stopHookTimeoutCheck(target, opts = {}) {
2926
2967
  return null;
2927
2968
  } // diagnosis must never crash doctor
2928
2969
  }
2970
+ // @implements A-SPEC-772.1
2971
+ /**
2972
+ * One row per harness: has this harness's PreToolUse or Stop hook been observed running in the target within 24 h?
2973
+ * Measured 2026-10-17: nothing recorded a hook run, so a governed Codex session could not tell it was governed. The
2974
+ * row reports an observation, never enforcement; a target without `.ax` is not a governed workspace and gets none.
2975
+ */
2976
+ /**
2977
+ * @implements A-SPEC-772.11 — the runtime binding row's activation words, narrowed by --agent: "observed (claude)"
2978
+ * beside a Codex-only report read as Codex's activation.
2979
+ */
2980
+ function activationText(observed, agent) {
2981
+ if (agent === undefined)
2982
+ return observed.length ? `live activation observed (${observed.join(', ')})` : 'live activation unverified';
2983
+ if (observed.includes(agent))
2984
+ return `live activation observed (${agent})`;
2985
+ return `live activation unverified for ${agent}${observed.length ? ` (observed: ${observed.join(', ')})` : ''}`;
2986
+ }
2987
+ /** @implements A-SPEC-772.11 — the workspace a target belongs to (a subdirectory reads its project's records). */
2988
+ function governedRootOf(target) {
2989
+ try {
2990
+ const { resolveProjectRoot } = require('../project/root');
2991
+ const r = resolveProjectRoot(target);
2992
+ return fs.existsSync(path.join(r.root, '.ax')) ? r.root : null;
2993
+ }
2994
+ catch {
2995
+ return fs.existsSync(path.join(target, '.ax')) ? target : null;
2996
+ }
2997
+ }
2998
+ function hookObservationChecks(targetIn, now = Date.now(), agent) {
2999
+ const target = governedRootOf(targetIn);
3000
+ if (target === null)
3001
+ return [];
3002
+ const { readHookHeartbeats, observationOf, ageText, hookWiringFiles } = require('../hooks/heartbeat');
3003
+ const beats = readHookHeartbeats(target, now);
3004
+ // @implements A-SPEC-772.6 — `--agent` narrows the rows; an observation older than the wiring is stale.
3005
+ return agents_1.AGENTS.filter((a) => agent === undefined || a === agent).map((harness) => {
3006
+ const wiring = hookWiringFiles(target, harness);
3007
+ const name = `hook observed (${harness})`;
3008
+ // @implements A-SPEC-772.8 — PASS means the PreToolUse gate ran here; a Stop alone is reported as such.
3009
+ const gate = observationOf(beats, harness, now, wiring, 'pre-tool-use');
3010
+ if (gate.state === 'observed')
3011
+ return { name, level: 'PASS', detail: `${harness} ${gate.event} hook ran here at ${gate.at} (build ${gate.buildId}, ${gate.mode === 'unknown' ? 'routing unknown' : gate.mode})` };
3012
+ const o = observationOf(beats, harness, now, wiring);
3013
+ // @implements A-SPEC-772.10 — say what was not observed, no more; name an inherited switch-off.
3014
+ const off = process.env.HOLMES_HEARTBEAT === 'off' ? ' (heartbeat recording is off in this environment: HOLMES_HEARTBEAT=off)' : '';
3015
+ const notSeen = gate.state === 'stale' && gate.reason ? 'not observed since its wiring changed' : 'not observed within 24 h';
3016
+ if (o.state === 'observed')
3017
+ return { name, level: 'WARN', detail: `${harness}: only the Stop hook was observed; the PreToolUse gate was ${notSeen} (last Stop at ${o.at})${off}`, fix: `Check that the ${harness} PreToolUse hook is wired and trusted.` };
3018
+ const detail = (o.state === 'stale'
3019
+ ? o.reason
3020
+ // @implements A-SPEC-772.11 — what refreshes it (the hook writes at most once a minute; it may have run again).
3021
+ ? `${harness} hooks were last observed at ${o.at}, before their wiring changed; a newer record is written at the next hook run after the one-per-minute limit`
3022
+ : `${harness} hooks were last observed ${ageText(o.ageMs)} ago (${o.event}, build ${o.buildId}); live activation is unverified for ${harness}`
3023
+ : `${harness} hooks were never observed in this workspace; live activation is unverified for ${harness}`) + off;
3024
+ return { name, level: 'WARN', detail, fix: `Run one ${harness} session in this workspace and re-run doctor; if this stays WARN, check the ${harness} hook wiring above.` };
3025
+ });
3026
+ }
2929
3027
  // @implements A-SPEC-769.19
2930
3028
  /**
2931
3029
  * Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate: Codex sessions end without the constitution