@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.
@@ -37,7 +37,7 @@ exports.isBrokenPipe = void 0;
37
37
  exports.packageRoot = packageRoot;
38
38
  exports.main = main;
39
39
  exports.installPipeGuard = installPipeGuard;
40
- // @implements A-SPEC-704, A-SPEC-709, A-SPEC-734, A-SPEC-751, A-SPEC-752
40
+ // @implements A-SPEC-704, A-SPEC-709, A-SPEC-734, A-SPEC-751, A-SPEC-752, A-SPEC-772.4
41
41
  // @implements A-SPEC-549.2
42
42
  // @implements A-SPEC-591, A-SPEC-626
43
43
  const cli_execution_1 = require("./cli-execution");
@@ -364,7 +364,8 @@ async function main(argv) {
364
364
  registryPath: typeof flags.registry === 'string' ? flags.registry : defaultRuntimeRegistry(),
365
365
  packageRoot: typeof flags.package === 'string' ? flags.package : undefined,
366
366
  releasePackageRoot: typeof flags['release-package'] === 'string' ? flags['release-package'] : undefined, dryRun: flags['dry-run'] === true, approval: readApproval(),
367
- activateHooks: typeof activate === 'string' ? (activate === 'all' ? ['claude', 'codex', 'antigravity'] : activate.split(',')) : undefined });
367
+ activateHooks: typeof activate === 'string' ? (activate === 'all' ? ['claude', 'codex', 'antigravity'] : activate.split(',')) : undefined,
368
+ approvalRoot: process.cwd() }); // A-SPEC-752.14
368
369
  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
369
370
  return 0;
370
371
  }
@@ -1296,6 +1297,12 @@ async function main(argv) {
1296
1297
  remove: flags.remove === true,
1297
1298
  approval: readApproval(),
1298
1299
  mcpLauncher,
1300
+ // @implements A-SPEC-772.4 — doctor's Codex hook reading for init's Codex line (init cannot import doctor).
1301
+ codexHookReading: (target, codexConfigPath) => {
1302
+ const { stopHookTimeoutCheck } = require('./doctor');
1303
+ const reading = { codexPre: false, codexStop: false, dormant: [], untrusted: [] };
1304
+ return { check: stopHookTimeoutCheck(target, { ...(codexConfigPath ? { codexConfigPath } : {}), codexGate: reading }), reading };
1305
+ },
1299
1306
  };
1300
1307
  const res = (0, init_1.runInit)(opts);
1301
1308
  // @implements A-SPEC-251.2 (round 44) — a message quoting a workspace file is escaped (an entry named with ESC and BEL
@@ -48,6 +48,30 @@ export interface InitOptions {
48
48
  autonomyInteractive?: boolean;
49
49
  /** @implements A-SPEC-752.8 — test override for the operator runtime registry whose receipt names owned wiring. */
50
50
  runtimeRegistryPath?: string;
51
+ /**
52
+ * @implements A-SPEC-772.2 — doctor's reading of the Codex hooks (trust, switch-off, Stop timeout), passed in by the
53
+ * CLI: doctor imports init, so init must not import doctor (no import cycles, A-SPEC-574.3).
54
+ */
55
+ codexHookReading?: (target: string, codexConfigPath?: string) => CodexHookReading;
56
+ }
57
+ export interface CodexHookReading {
58
+ check: {
59
+ level: string;
60
+ detail: string;
61
+ } | null;
62
+ reading: {
63
+ codexPre: boolean;
64
+ codexStop: boolean;
65
+ dormant: {
66
+ file: string;
67
+ timeout: number | null;
68
+ }[];
69
+ untrusted: string[];
70
+ /** @implements A-SPEC-772.5 */ shortStops?: {
71
+ file: string;
72
+ runs: boolean;
73
+ }[];
74
+ };
51
75
  }
52
76
  export interface FileChange {
53
77
  path: string;
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
37
37
  exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
- // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8
39
+ // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6
40
40
  // @implements A-SPEC-709
41
41
  // @implements A-SPEC-769.11
42
42
  // @implements A-SPEC-340
@@ -1180,9 +1180,11 @@ function runInitUnguarded(opts) {
1180
1180
  }
1181
1181
  if (leftOwned.length > 0) {
1182
1182
  const names = leftOwned.map((l) => l.path);
1183
- const codexLeft = names.some((p) => /[\\/]\.codex[\\/]/.test(p) || p === (opts.codexConfigPath ?? '') || p === (opts.codexHooksPath ?? ''));
1183
+ // @implements A-SPEC-772.6 — also wherever CODEX_HOME puts the user-level files (not only a `.codex` folder).
1184
+ const codexLeft = names.some((p) => /[\\/]\.codex[\\/]/.test(p) || p === (opts.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)()) || p === (opts.codexHooksPath ?? (0, codex_hooks_1.defaultCodexHooksPath)()));
1185
+ // @implements A-SPEC-772.6 — the dry run's "would wire … the user-level gate hooks" is a claim about those files too.
1184
1186
  const claims = (m) => (names.some((p) => m.includes(p)) && /wired|active|repaired|written/.test(m))
1185
- || (codexLeft && /pre-tool gate runs from the user-level Codex hooks file|codex: the gate is enforced \(hooks wired\)|codex: tools and instructions wired/.test(m));
1187
+ || (codexLeft && /pre-tool gate runs from the user-level Codex hooks file|codex: the gate is enforced \(hooks wired\)|codex: tools and instructions wired|codex: would wire .*user-level gate hooks/.test(m));
1186
1188
  for (let i = messages.length - 1; i >= 0; i--)
1187
1189
  if (claims(messages[i]))
1188
1190
  messages.splice(i, 1);
@@ -1191,6 +1193,10 @@ function runInitUnguarded(opts) {
1191
1193
  ? `${l.path}: left as it is — owned by the operator runtime registry. Preview a change to it with: holmes-kit runtime-binding setup --dry-run`
1192
1194
  : `${l.path}: left as it is — owned by the operator runtime registry, but the registry's receipt and the file disagree. Inspect with: holmes-kit runtime-binding status, then preview with: holmes-kit runtime-binding setup --dry-run`);
1193
1195
  }
1196
+ // @implements A-SPEC-772.2 — the withdrawn Codex claim is replaced by what is known, never by "enforced".
1197
+ // @implements A-SPEC-772.6 — not when removing: the line describes a wiring the run takes away.
1198
+ if (codexLeft && !opts.remove && (opts.agents ?? []).includes('codex'))
1199
+ messages.push(...registryCodexLines(opts));
1194
1200
  }
1195
1201
  }
1196
1202
  // @implements A-SPEC-251.1 (round 27) — no write, removal or link goes through a link the repository carries out of the
@@ -1359,3 +1365,49 @@ function runInitUnguarded(opts) {
1359
1365
  }
1360
1366
  return { ok: true, exitCode: 0, messages, changes, removals };
1361
1367
  }
1368
+ /**
1369
+ * @implements A-SPEC-772.2 — what init can say about Codex when the operator registry owns the user-level Codex files:
1370
+ * the routing the dispatcher selects and the trust state of the routed gates (doctor's reading), plus the operator act
1371
+ * when a running Codex Stop keeps a timeout below 75 s. Measured 2026-10-17: init said nothing about Codex here, and the
1372
+ * registry-owned Stop timeout was 30 s.
1373
+ */
1374
+ function registryCodexLines(opts) {
1375
+ let routing;
1376
+ try {
1377
+ const s = (0, runtime_binding_1.runtimeBindingStatus)(opts.runtimeRegistryPath ?? (0, runtime_binding_1.defaultRuntimeRegistry)(), opts.target).selection;
1378
+ routing = `routed by the operator registry (${s.mode}, build ${s.buildId})`;
1379
+ }
1380
+ catch (e) {
1381
+ routing = `routing unknown: ${(0, codex_oracle_1.clipText)(e.message, 300)}`;
1382
+ }
1383
+ const lines = [];
1384
+ let gates = 'hook trust not read';
1385
+ try {
1386
+ const read = opts.codexHookReading?.(opts.target, opts.codexConfigPath);
1387
+ const check = read?.check ?? null;
1388
+ const reading = read?.reading;
1389
+ if (check !== null && reading !== undefined) {
1390
+ const pre = reading.codexPre ? 'PreToolUse gate trusted' : 'PreToolUse gate not trusted or switched off — trust it with /hooks';
1391
+ const stop = reading.codexStop ? 'Stop gate trusted'
1392
+ : reading.untrusted.length ? 'Stop gate wired but not yet trusted — /hooks'
1393
+ : reading.dormant.length ? 'Stop gate switched off' : 'no Stop gate';
1394
+ gates = `${pre}, ${stop}`;
1395
+ const hooksFile = opts.codexHooksPath ?? (0, codex_hooks_1.defaultCodexHooksPath)();
1396
+ // @implements A-SPEC-772.5 — read the short Stops themselves, not the row's level: a RUNNING one is FAIL (772.3).
1397
+ const short = (reading.shortStops ?? []).find((s) => s.file === hooksFile);
1398
+ if (short !== undefined) {
1399
+ lines.push(`${hooksFile}: Codex Stop hook timeout below 75 s — ${short.runs ? 'Codex can kill the Stop before its 60 s deadline answers' : 'it will be killed before its 60 s deadline answers once you trust it'}. Operator: holmes-kit runtime-binding setup (rewrites it at 75 s), then trust it once with /hooks.`);
1400
+ }
1401
+ }
1402
+ }
1403
+ catch { /* the reading is advisory; the routing line still stands */ }
1404
+ // @implements A-SPEC-772.6 — Codex does not load the hooks of a project it marks untrusted.
1405
+ let trust = '';
1406
+ try {
1407
+ const key = (0, runtime_binding_1.codexProjectUntrusted)(opts.target, opts.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)());
1408
+ if (key !== null)
1409
+ trust = `; Codex marks ${key} untrusted — project hooks do not load`;
1410
+ }
1411
+ catch { /* advisory */ }
1412
+ return [`codex: ${routing} — ${gates}${trust}; live activation unverified (workspace_preflight with harness codex reports observations).`, ...lines];
1413
+ }
@@ -4,4 +4,9 @@ export declare function runtimePlanDigest(identity: unknown, changes: {
4
4
  before: string | null;
5
5
  after: string;
6
6
  }[]): string;
7
- export declare function applyApprovedRuntimePlan(root: string, subject: string, envApproval: Approval | undefined, check: () => void, apply: () => void): void;
7
+ /**
8
+ * @implements A-SPEC-752.14 — `approvalRoot` is the governed workspace whose queue, grants and ledger hold the decision;
9
+ * it differs from `root` only for the remove of a workspace that is no longer a governed project. The request target
10
+ * still names `root`, so the operator's list shows what the plan is about.
11
+ */
12
+ export declare function applyApprovedRuntimePlan(root: string, subject: string, envApproval: Approval | undefined, check: () => void, apply: () => void, approvalRoot?: string): void;
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.runtimePlanDigest = runtimePlanDigest;
37
37
  exports.applyApprovedRuntimePlan = applyApprovedRuntimePlan;
38
- // @implements A-SPEC-752
38
+ // @implements A-SPEC-752, A-SPEC-752.14
39
39
  const path = __importStar(require("node:path"));
40
40
  const node_crypto_1 = require("node:crypto");
41
41
  const risk_gate_1 = require("../guardrail/risk-gate");
@@ -50,8 +50,13 @@ function runtimePlanDigest(identity, changes) {
50
50
  .sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
51
51
  return `sha256:${hash(JSON.stringify({ identity, files }))}`;
52
52
  }
53
- function applyApprovedRuntimePlan(root, subject, envApproval, check, apply) {
54
- const ledgerDir = path.join(root, '.ax/ledger');
53
+ /**
54
+ * @implements A-SPEC-752.14 — `approvalRoot` is the governed workspace whose queue, grants and ledger hold the decision;
55
+ * it differs from `root` only for the remove of a workspace that is no longer a governed project. The request target
56
+ * still names `root`, so the operator's list shows what the plan is about.
57
+ */
58
+ function applyApprovedRuntimePlan(root, subject, envApproval, check, apply, approvalRoot = root) {
59
+ const ledgerDir = path.join(approvalRoot, '.ax/ledger');
55
60
  const ledger = new ledger_store_1.FileLedgerStore(ledgerDir);
56
61
  // Official grants use request ids as nonces. A new plan, or retry after an attempted
57
62
  // application, needs a distinct request identity; revoking never erases spent history.
@@ -66,18 +71,18 @@ function applyApprovedRuntimePlan(root, subject, envApproval, check, apply) {
66
71
  const now = new Date().toISOString();
67
72
  if (envApproval && (0, risk_gate_1.approvalCovers)(envApproval, { kind: action.kind, target: root }, now))
68
73
  return { approval: envApproval, source: 'env' };
69
- const refused = new Set((0, approval_grants_1.refusedGrantReasons)(root, action, now).map((r) => r.nonce));
70
- const approval = (0, approval_grants_1.readGrants)(root).grants.find((g) => g.subject === subject
74
+ const refused = new Set((0, approval_grants_1.refusedGrantReasons)(approvalRoot, action, now).map((r) => r.nonce));
75
+ const approval = (0, approval_grants_1.readGrants)(approvalRoot).grants.find((g) => g.subject === subject
71
76
  && !refused.has(g.nonce) && (0, risk_gate_1.approvalCovers)(g, action, now));
72
77
  return approval ? { approval, source: 'grant' } : undefined;
73
78
  };
74
79
  const request = () => {
75
- const result = (0, approval_queue_1.enqueueApprovalRequestDetailed)(root, { ...action, risk: 'high',
80
+ const result = (0, approval_queue_1.enqueueApprovalRequestDetailed)(approvalRoot, { ...action, risk: 'high',
76
81
  why: `Review runtime-binding --dry-run for plan ${subject}; approve this exact wiring plan and retry the same command. Native trust is separate.` });
77
82
  const id = (0, approval_queue_1.approvalRequestId)(action.kind, target);
78
83
  if (result.reason !== 'written' && result.reason !== 'duplicate')
79
84
  throw new Error(`Cannot queue governance-wiring approval: ${result.reason}; nothing installed`);
80
- throw new Error(`governance-wiring approval required for plan ${subject}; request ${id}. In this workspace run holmes-kit approve --list, then holmes-kit approve --grant ${id} and retry the same runtime-binding command. If an old decision remains, revoke it and retry to request the current plan.`);
85
+ throw new Error(`governance-wiring approval required for plan ${subject}; request ${id}. In ${approvalRoot === root ? 'this workspace' : `the workspace ${approvalRoot}`} run holmes-kit approve --list, then holmes-kit approve --grant ${id} and retry the same runtime-binding command. If an old decision remains, revoke it and retry to request the current plan.`);
81
86
  };
82
87
  check();
83
88
  if (!resolve())
@@ -97,6 +102,6 @@ function applyApprovedRuntimePlan(root, subject, envApproval, check, apply) {
97
102
  }
98
103
  apply();
99
104
  if (resolved.source === 'grant' && nonce)
100
- (0, approval_grants_1.consumeGrantFile)(root, nonce);
105
+ (0, approval_grants_1.consumeGrantFile)(approvalRoot, nonce);
101
106
  });
102
107
  }
@@ -1,4 +1,4 @@
1
- import type { RuntimeHarness, RuntimeEntry } from '../runtime/binding';
1
+ import type { RuntimeHarness, RuntimeEntry, RuntimeSelection } from '../runtime/binding';
2
2
  import type { Approval } from '../guardrail/risk-gate';
3
3
  export declare const defaultRuntimeRegistry: () => string;
4
4
  export interface RuntimeBindingOptions {
@@ -14,6 +14,8 @@ export interface RuntimeBindingOptions {
14
14
  activateHooks?: string[];
15
15
  /** @implements A-SPEC-752.10 — the digest a reviewer was shown; a plan that computes to another one is not applied. */
16
16
  expectedPlanDigest?: string;
17
+ /** @implements A-SPEC-752.14 — where the operator runs remove (CLI: cwd); holds the approval of a workspace without `.ax`. */
18
+ approvalRoot?: string;
17
19
  }
18
20
  export declare function runtimeHookCommand(registryPath: string, harness: RuntimeHarness, entry: RuntimeEntry): string;
19
21
  /**
@@ -23,6 +25,11 @@ export declare function runtimeHookCommand(registryPath: string, harness: Runtim
23
25
  * A list of keys to keep missed ones that switch Holmes off, so the view names what it drops (A-SPEC-752.6).
24
26
  */
25
27
  export declare function wiringViewOf(file: string, content: string): string;
28
+ /**
29
+ * @implements A-SPEC-772.6 — the `projects` key that marks `target` (or a directory above it) untrusted in a Codex
30
+ * config, or null. Codex does not load an untrusted project's hooks.
31
+ */
32
+ export declare function codexProjectUntrusted(target: string, configPath: string): string | null;
26
33
  /**
27
34
  * @implements A-SPEC-752.8 — whether the installation receipt beside the operator registry lists `file`, and whether the
28
35
  * file still matches it. Measured 2026-10-04: init rewrote the user-level Codex files a setup plan had written, because
@@ -50,7 +57,7 @@ export declare function codexDuplicateRoutes(codexHome: string, workspace: strin
50
57
  export declare function runtimeBindingStatus(registryPath: string, workspace: string, opts?: {
51
58
  codexHome?: string;
52
59
  }): {
53
- selection: import("../runtime/binding").RuntimeSelection;
60
+ selection: RuntimeSelection;
54
61
  conflicts: string[];
55
62
  drift: {
56
63
  path: string;
@@ -58,7 +65,11 @@ export declare function runtimeBindingStatus(registryPath: string, workspace: st
58
65
  }[];
59
66
  duplicateRoutes: DuplicateRoute[];
60
67
  router: "changed" | "intact";
61
- activation: "unverified";
68
+ routerOutdated: string[];
69
+ activation: "observed" | "unverified";
70
+ observed: Record<string, string>;
71
+ observedUnrouted: Record<string, string>;
72
+ observedOther: Record<string, string>;
62
73
  };
63
74
  export declare function runRuntimeBinding(opts: RuntimeBindingOptions): unknown;
64
75
  /**
@@ -36,13 +36,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.defaultRuntimeRegistry = void 0;
37
37
  exports.runtimeHookCommand = runtimeHookCommand;
38
38
  exports.wiringViewOf = wiringViewOf;
39
+ exports.codexProjectUntrusted = codexProjectUntrusted;
39
40
  exports.registryWiringOwnership = registryWiringOwnership;
40
41
  exports.registryOwnedWiring = registryOwnedWiring;
41
42
  exports.codexDuplicateRoutes = codexDuplicateRoutes;
42
43
  exports.runtimeBindingStatus = runtimeBindingStatus;
43
44
  exports.runRuntimeBinding = runRuntimeBinding;
44
45
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
45
- // @implements A-SPEC-769.10, A-SPEC-752.11, A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8
46
+ // @implements A-SPEC-769.10, A-SPEC-752.11, A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, 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
46
47
  const fs = __importStar(require("node:fs"));
47
48
  const os = __importStar(require("node:os"));
48
49
  const path = __importStar(require("node:path"));
@@ -55,6 +56,7 @@ const runtime_binding_approval_1 = require("./runtime-binding-approval");
55
56
  const codex_toml_1 = require("./codex-toml");
56
57
  const codex_hooks_1 = require("./codex-hooks");
57
58
  const agents_1 = require("./agents");
59
+ const heartbeat_1 = require("../hooks/heartbeat");
58
60
  const defaultRuntimeRegistry = () => path.join(os.homedir(), '.holmes', 'runtime', 'bindings.json');
59
61
  exports.defaultRuntimeRegistry = defaultRuntimeRegistry;
60
62
  const digest = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
@@ -116,6 +118,9 @@ function runtimeHookCommand(registryPath, harness, entry) {
116
118
  */
117
119
  function wiringViewOf(file, content) {
118
120
  const name = path.basename(file);
121
+ // @implements A-SPEC-772.5 — every config.toml Holmes wires is Codex's, wherever CODEX_HOME puts it.
122
+ if (name === 'config.toml')
123
+ return codexConfigView(content);
119
124
  if ((name !== 'settings.json' && name !== 'settings.local.json') || path.basename(path.dirname(file)) !== '.claude')
120
125
  return content;
121
126
  let doc;
@@ -131,6 +136,77 @@ function wiringViewOf(file, content) {
131
136
  const { model: _model, ...rest } = doc;
132
137
  return JSON.stringify(rest);
133
138
  }
139
+ /**
140
+ * @implements A-SPEC-772.2 — Codex writes its own trust records (`hooks.state.*.trusted_hash`), project trust
141
+ * (`projects`) and notices (`tui`) into `~/.codex/config.toml` (measured 2026-10-17), so a whole-file digest disagreed
142
+ * with the receipt forever. The view drops exactly those; an `enabled` switch, which can turn Holmes off, stays.
143
+ */
144
+ function codexConfigView(content) {
145
+ const parsed = (0, codex_toml_1.parseCodexConfig)(content);
146
+ if (!parsed.ok)
147
+ return content;
148
+ const doc = JSON.parse(JSON.stringify(parsed.doc));
149
+ delete doc.tui;
150
+ // @implements A-SPEC-772.6 — `projects` is Codex's own per-repository trust, shared by every repository on the machine:
151
+ // one "No" anywhere made the receipt disagree forever (round 2). An untrusted governed workspace is named instead by
152
+ // `codexProjectUntrusted`.
153
+ delete doc.projects;
154
+ const hooks = doc.hooks;
155
+ if (object(hooks) && object(hooks.state)) {
156
+ const state = hooks.state;
157
+ for (const [key, entry] of Object.entries(state)) {
158
+ if (!object(entry))
159
+ continue;
160
+ delete entry.trusted_hash;
161
+ // @implements A-SPEC-772.5 — Codex's own re-enabling is not a change of wiring; a switch-off is.
162
+ if (entry.enabled === true)
163
+ delete entry.enabled;
164
+ if (Object.keys(entry).length === 0)
165
+ delete state[key];
166
+ }
167
+ if (Object.keys(state).length === 0)
168
+ delete hooks.state;
169
+ if (Object.keys(hooks).length === 0)
170
+ delete doc.hooks;
171
+ }
172
+ const sorted = (v) => Array.isArray(v) ? v.map(sorted)
173
+ : object(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted(v[k])])) : v;
174
+ return JSON.stringify(sorted(doc));
175
+ }
176
+ /**
177
+ * @implements A-SPEC-772.6 — the `projects` key that marks `target` (or a directory above it) untrusted in a Codex
178
+ * config, or null. Codex does not load an untrusted project's hooks.
179
+ */
180
+ function codexProjectUntrusted(target, configPath) {
181
+ const raw = readOptional(configPath);
182
+ if (raw === null)
183
+ return null;
184
+ const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
185
+ if (!parsed.ok)
186
+ return null;
187
+ const projects = parsed.doc.projects;
188
+ if (!object(projects))
189
+ return null;
190
+ let real = target;
191
+ try {
192
+ real = fs.realpathSync.native(target);
193
+ }
194
+ catch { /* as given */ }
195
+ // @implements A-SPEC-772.7 — the most specific key that contains the target decides (Codex looks up the exact project
196
+ // first): a trusted workspace under an untrusted parent is trusted.
197
+ let best = null;
198
+ for (const [key, entry] of Object.entries(projects)) {
199
+ if (!object(entry) || !path.isAbsolute(key))
200
+ continue;
201
+ const k = path.resolve(key);
202
+ if (![target, real].some((t) => (0, binding_1.inside)(k, t)))
203
+ continue;
204
+ const depth = k.split(path.sep).length;
205
+ if (best === null || depth > best.depth)
206
+ best = { key, depth, untrusted: entry.trust_level === 'untrusted' };
207
+ }
208
+ return best !== null && best.untrusted ? best.key : null;
209
+ }
134
210
  /**
135
211
  * @implements A-SPEC-752.8 — whether the installation receipt beside the operator registry lists `file`, and whether the
136
212
  * file still matches it. Measured 2026-10-04: init rewrote the user-level Codex files a setup plan had written, because
@@ -293,7 +369,52 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
293
369
  }
294
370
  // @implements A-SPEC-769.8 — reported beside the receipt verdicts; it changes neither `conflicts` nor `router`.
295
371
  const duplicateRoutes = codexDuplicateRoutes(opts?.codexHome ?? path.join(os.homedir(), '.codex'), workspace);
296
- return { selection, conflicts, drift, duplicateRoutes, router: routerChanged ? 'changed' : 'intact', activation: 'unverified' };
372
+ // @implements A-SPEC-772.1 — a hook observed running in the selected workspace is reported, per harness.
373
+ const beats = (0, heartbeat_1.readHookHeartbeats)(selection.workspaceRoot);
374
+ const observed = {};
375
+ const observedUnrouted = {};
376
+ const observedOther = {};
377
+ const wiringEnv = { ...process.env, ...(opts?.codexHome ? { CODEX_HOME: opts.codexHome } : {}) };
378
+ const now = Date.now();
379
+ for (const harness of agents_1.AGENTS) {
380
+ const wiring = (0, heartbeat_1.hookWiringFiles)(selection.workspaceRoot, harness, wiringEnv);
381
+ // @implements A-SPEC-772.7 — each event on its own: a routed PreToolUse is not hidden by a later Stop of another mode.
382
+ for (const event of ['pre-tool-use', 'stop']) {
383
+ const beat = beats[harness][event];
384
+ if (beat === undefined)
385
+ continue;
386
+ const one = { ...beats, [harness]: { [event]: beat } };
387
+ // @implements A-SPEC-772.5 — only a hook that ran under THIS selection (its mode and build) is its activation.
388
+ // @implements A-SPEC-772.6 — not when the harness's wiring changed after it.
389
+ const o = (0, heartbeat_1.observationOf)(one, harness, now, wiring);
390
+ if (o.state !== 'observed')
391
+ continue;
392
+ const latest = (rec) => { if (!rec[harness] || rec[harness] < o.at)
393
+ rec[harness] = o.at; };
394
+ // @implements A-SPEC-772.9 — activation is the PreToolUse GATE of this selection; a Stop alone does not count.
395
+ if (event === 'pre-tool-use' && o.mode === selection.mode && o.buildId === selection.buildId)
396
+ latest(observed);
397
+ // @implements A-SPEC-772.7 — a run without routing evidence is reported apart from activation.
398
+ else if (o.mode === 'unknown')
399
+ latest(observedUnrouted);
400
+ // @implements A-SPEC-772.10 — every other observation (a Stop of this selection, another build or mode) is named.
401
+ // @implements A-SPEC-772.11 — each uncounted event, PreToolUse first (events loop in that order); the latest
402
+ // alone hid an other-build PreToolUse behind the turn-end Stop (round 7).
403
+ else {
404
+ const entry = `${event} at ${o.at} (build ${o.buildId}, ${o.mode})`;
405
+ observedOther[harness] = observedOther[harness] ? `${observedOther[harness]}; ${entry}` : entry;
406
+ }
407
+ }
408
+ }
409
+ const activation = Object.keys(observed).length > 0 ? 'observed' : 'unverified';
410
+ // @implements A-SPEC-772.7 — the deployed dispatcher of 2026-10-15 did not pass HOLMES_HOOK_MODE while `router` said
411
+ // intact (round 3). @implements A-SPEC-772.8 — judged by that capability, not by bytes: one machine-wide copy serves
412
+ // every binding, so comparing it with the selected package was outdated forever for a development binding (round 4).
413
+ const routerOutdated = [];
414
+ const deployedDispatch = readOptional(path.join(path.dirname(registryPath), 'dispatch.js'));
415
+ if (deployedDispatch !== null && !deployedDispatch.includes('HOLMES_HOOK_MODE'))
416
+ routerOutdated.push('dispatch.js');
417
+ return { selection, conflicts, drift, duplicateRoutes, router: routerChanged ? 'changed' : 'intact', routerOutdated, activation, observed, observedUnrouted, observedOther };
297
418
  }
298
419
  function runRuntimeBinding(opts) {
299
420
  if (opts.activateHooks !== undefined && (!Array.isArray(opts.activateHooks)
@@ -310,14 +431,50 @@ function runRuntimeBinding(opts) {
310
431
  if (['binding.js', 'dispatch.js', 'hook-process.js', 'installation.json'].includes(path.basename(opts.registryPath))
311
432
  || /^(?:claude|codex|antigravity)-(?:mcp|pre-tool-use|stop|session-start)\.js$/.test(path.basename(opts.registryPath)))
312
433
  throw new Error('Registry filename conflicts with an installed runtime file');
313
- const root = (0, binding_1.workspaceRoot)(opts.workspace);
314
- if ((0, binding_1.canonicalDirectory)(opts.workspace) !== root)
434
+ // @implements A-SPEC-752.14 — a remove may name a workspace whose directory is gone (measured: G0GnMK); its root is
435
+ // resolved without the directory, and the remove proceeds only for what the registry or the receipt still records.
436
+ const vanished = opts.operation === 'remove' && path.isAbsolute(opts.workspace) && !fs.existsSync(opts.workspace);
437
+ const root = vanished ? canonicalFuture(opts.workspace) : (0, binding_1.workspaceRoot)(opts.workspace);
438
+ if (!vanished && (0, binding_1.canonicalDirectory)(opts.workspace) !== root)
315
439
  throw new Error('Register the workspace root, not a subdirectory');
316
440
  const destination = canonicalFuture(opts.registryPath);
317
441
  if (destination !== opts.registryPath || (0, binding_1.inside)(root, destination))
318
442
  throw new Error('Operator registry must be canonical and outside the workspace');
319
443
  const before = readOptional(opts.registryPath);
320
- const previous = before === null ? null : (0, binding_1.readRuntimeRegistry)(opts.registryPath);
444
+ // @implements A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16 — a vanished binding fails registry validation (its directory
445
+ // cannot be canonicalised), so remove sets aside the removed workspace's binding and every binding whose WORKSPACE is
446
+ // gone, validates the rest as before, and writes the vanished others back unchanged: it unbinds only what the operator
447
+ // named. The written registry obeys the schema's limits (count, no duplicate roots).
448
+ let vanishedBound = false;
449
+ let previous = null;
450
+ let keptVanished = [];
451
+ let setAside = [];
452
+ if (before !== null && opts.operation === 'remove') {
453
+ try {
454
+ const raw = JSON.parse(before);
455
+ const all = Array.isArray(raw?.bindings) ? raw.bindings : [];
456
+ const gone = (b) => typeof b?.workspaceRoot === 'string' && typeof b?.packageRoot === 'string'
457
+ && path.isAbsolute(b.workspaceRoot) && path.isAbsolute(b.packageRoot) && !fs.existsSync(b.workspaceRoot);
458
+ // A-SPEC-752.17: a hand-edited spelling (`w/`, `x/../w`) of a root is the same root.
459
+ const resolved = (b) => typeof b?.workspaceRoot === 'string' && path.isAbsolute(b.workspaceRoot) ? path.resolve(b.workspaceRoot) : b?.workspaceRoot;
460
+ vanishedBound = all.some((b) => resolved(b) === root);
461
+ const kept = all.filter((b) => resolved(b) !== root);
462
+ if (kept.length > 1000)
463
+ throw new Error('Invalid runtime registry schema');
464
+ if (new Set(kept.map(resolved)).size !== kept.length)
465
+ throw new Error('Duplicate runtime binding');
466
+ setAside = kept.filter(gone);
467
+ // In the registry's own order: a living binding as validation spells it, a vanished one exactly as it was.
468
+ if (setAside.length)
469
+ keptVanished = kept.map((b) => gone(b) ? b : { workspaceRoot: b?.workspaceRoot, packageRoot: b?.packageRoot });
470
+ previous = (0, binding_1.validateRegistry)({ ...raw, bindings: Array.isArray(raw?.bindings) ? kept.filter((b) => !gone(b)) : raw?.bindings });
471
+ }
472
+ catch (e) {
473
+ throw new Error(`Cannot use runtime registry ${opts.registryPath}: ${e.message}. Repair runtime-binding setup.`);
474
+ }
475
+ }
476
+ else if (before !== null)
477
+ previous = (0, binding_1.readRuntimeRegistry)(opts.registryPath);
321
478
  if (opts.operation === 'setup' && (!opts.packageRoot || !opts.releasePackageRoot))
322
479
  throw new Error('setup requires --package and --release-package');
323
480
  if (opts.operation === 'remove' && !previous)
@@ -328,15 +485,18 @@ function runRuntimeBinding(opts) {
328
485
  bindings: [...(previous?.bindings ?? []).filter((b) => b.workspaceRoot !== root), { workspaceRoot: root, packageRoot: (0, binding_1.canonicalDirectory)(opts.packageRoot) }],
329
486
  } : { ...previous, bindings: previous.bindings.filter((b) => b.workspaceRoot !== root) };
330
487
  (0, binding_1.validateRegistry)(next);
331
- for (const binding of next.bindings) {
488
+ for (const binding of [...next.bindings, ...setAside]) {
332
489
  if ((0, binding_1.inside)(binding.workspaceRoot, destination) || (0, binding_1.inside)(binding.packageRoot, destination))
333
490
  throw new Error('Operator registry must be outside registered checkouts');
334
491
  }
335
492
  if ((0, binding_1.inside)(next.releasePackageRoot, destination))
336
493
  throw new Error('Operator registry must be outside the release package');
337
494
  const releaseBuild = (0, binding_1.verifyRuntime)(next.releasePackageRoot);
338
- const selection = (0, binding_1.selectRuntime)(next, { cwd: root });
339
- const after = `${JSON.stringify(next, null, 2)}\n`;
495
+ // A vanished workspace is no longer bound after the remove: it selects the release runtime, without probing the directory.
496
+ const selection = vanished
497
+ ? { mode: 'release', workspaceRoot: root, packageRoot: next.releasePackageRoot, buildId: releaseBuild, specsRoot: path.join(root, '.ax', 'specs') }
498
+ : (0, binding_1.selectRuntime)(next, { cwd: root });
499
+ const after = `${JSON.stringify(keptVanished.length ? { ...next, bindings: keptVanished } : next, null, 2)}\n`;
340
500
  const planned = new Map();
341
501
  const conflicts = [];
342
502
  const add = (file, content) => {
@@ -778,10 +938,16 @@ function runRuntimeBinding(opts) {
778
938
  recorded.set(c.path, { path: c.path, digest: digest(wiringViewOf(c.path, c.after)) });
779
939
  // @implements A-SPEC-752.11 — the receipt forgets a removed workspace: its rows and its identity.
780
940
  if (opts.operation === 'remove') {
941
+ // A-SPEC-752.17: a row owned by a binding nested inside the root is that binding's, not the root's.
942
+ const keptInside = [...next.bindings, ...setAside].filter((b) => (0, binding_1.inside)(root, path.resolve(b.workspaceRoot)));
943
+ if (vanished && !vanishedBound && runtimeIdentities[root] === undefined
944
+ && ![...recorded.keys()].some((p) => (0, binding_1.inside)(root, p) && !keptInside.some((b) => (0, binding_1.inside)(path.resolve(b.workspaceRoot), p))))
945
+ throw new Error(`Nothing registered for ${root}; nothing written`);
781
946
  // @implements A-SPEC-752.12, A-SPEC-752.13 — a row inside a workspace that stays bound AND is nested inside the
782
947
  // removed root is that workspace's; a remaining parent of the removed root does not keep the removed root's rows.
783
948
  for (const p of [...recorded.keys()]) {
784
- if ((0, binding_1.inside)(root, p) && !next.bindings.some((b) => (0, binding_1.inside)(root, b.workspaceRoot) && (0, binding_1.inside)(b.workspaceRoot, p)))
949
+ // A-SPEC-752.16: a set-aside binding stays in the written registry, so it stays bound here too.
950
+ if ((0, binding_1.inside)(root, p) && ![...next.bindings, ...setAside].some((b) => (0, binding_1.inside)(root, b.workspaceRoot) && (0, binding_1.inside)(b.workspaceRoot, p)))
785
951
  recorded.delete(p);
786
952
  }
787
953
  delete runtimeIdentities[root];
@@ -812,6 +978,21 @@ function runRuntimeBinding(opts) {
812
978
  throw new Error('Runtime build changed since preview');
813
979
  };
814
980
  check();
981
+ // @implements A-SPEC-752.14 — a workspace without `.ax` has no approval queue or ledger: its remove is approved in the
982
+ // governed workspace the operator runs it from (measured: pilot64's emptied H0 refused with "no-project").
983
+ let approvalRoot = root;
984
+ if (opts.operation === 'remove' && !fs.existsSync(path.join(root, '.ax'))) {
985
+ let governed = null;
986
+ try {
987
+ const at = opts.approvalRoot === undefined ? null : (0, binding_1.workspaceRoot)(opts.approvalRoot);
988
+ if (at !== null && at !== root && fs.existsSync(path.join(at, '.ax')))
989
+ governed = at;
990
+ }
991
+ catch { /* an unresolvable approval root is no governed workspace */ }
992
+ if (governed === null)
993
+ throw new Error(`${root} is no longer a governed project (no .ax); run runtime-binding remove from a governed workspace — its approval queue takes the request; nothing written`);
994
+ approvalRoot = governed;
995
+ }
815
996
  if (changes.length > 0)
816
997
  (0, runtime_binding_approval_1.applyApprovedRuntimePlan)(root, planDigest, opts.approval, check, () => {
817
998
  let written = 0;
@@ -838,7 +1019,7 @@ function runRuntimeBinding(opts) {
838
1019
  catch (e) {
839
1020
  throw new Error(`Runtime setup incomplete after ${written} file(s): ${e.message}; run status and preview setup again`);
840
1021
  }
841
- });
1022
+ }, approvalRoot);
842
1023
  }
843
1024
  // @implements A-SPEC-752.7 — outside the plan digest: what git tracks is not part of the reviewed wiring plan.
844
1025
  const trackedChanges = trackedWorkspacePaths(root, changes.map((c) => c.path));
@@ -37,7 +37,7 @@ exports.TOOL_MAP = void 0;
37
37
  exports.shippedHookTimeoutMs = shippedHookTimeoutMs;
38
38
  exports.adaptPreToolUse = adaptPreToolUse;
39
39
  exports.adaptStop = adaptStop;
40
- // @implements A-SPEC-193
40
+ // @implements A-SPEC-193, A-SPEC-772.1
41
41
  // @implements A-SPEC-734
42
42
  // @implements A-SPEC-769.10, A-SPEC-769.11
43
43
  const fs = __importStar(require("node:fs"));
@@ -73,7 +73,8 @@ function shippedHookTimeoutMs(hookPath) {
73
73
  const runShippedHook = (hookPath, payload, cwd) => {
74
74
  const r = (0, node_child_process_1.spawnSync)(process.execPath, [hookPath], {
75
75
  cwd, input: payload, encoding: 'utf8', timeout: shippedHookTimeoutMs(hookPath),
76
- env: { ...process.env },
76
+ // @implements A-SPEC-772.1 — the kernel cannot tell an Antigravity call from its translated input; name it.
77
+ env: { ...process.env, HOLMES_HOOK_HARNESS: 'antigravity' },
77
78
  });
78
79
  // @implements A-SPEC-734 (round 16) — three-harness parity: the hook's "not judged" notices reach the harness as
79
80
  // they do for Claude and Codex (the adapter dropped every one — measured).
@@ -0,0 +1,47 @@
1
+ import { Agent } from '../cli/agent-registry';
2
+ export declare const HEARTBEAT_DIR: string;
3
+ export type HookEvent = 'pre-tool-use' | 'stop';
4
+ declare const SCHEMA = "holmes-hook-heartbeat/1";
5
+ export declare const OBSERVED_WITHIN_MS: number;
6
+ /** @implements A-SPEC-772.7 — `unknown`: no routing evidence (a direct-wired kernel and an older deployed dispatcher look alike). */
7
+ export interface HookBeat {
8
+ schema: typeof SCHEMA;
9
+ harness: Agent;
10
+ event: HookEvent;
11
+ at: string;
12
+ buildId: string;
13
+ mode: 'development' | 'release' | 'unknown';
14
+ }
15
+ export type HookBeats = Record<Agent, Partial<Record<HookEvent, HookBeat>>>;
16
+ export type HookObservation = {
17
+ state: 'observed' | 'stale';
18
+ event: HookEvent;
19
+ at: string;
20
+ buildId: string;
21
+ mode: HookBeat['mode'];
22
+ ageMs: number;
23
+ reason?: 'wiring changed since';
24
+ } | {
25
+ state: 'never';
26
+ };
27
+ /** The harness a hook call belongs to, or null when the evidence is absent or contradicts itself. */
28
+ export declare function hookHarnessOf(input: unknown, env: Record<string, string | undefined>): Agent | null;
29
+ export declare function recordHookHeartbeat(opts: {
30
+ root: string;
31
+ event: HookEvent;
32
+ input: unknown;
33
+ env: Record<string, string | undefined>;
34
+ now?: number;
35
+ buildId?: string;
36
+ }): void;
37
+ export declare function readHookHeartbeats(root: string, now?: number): HookBeats;
38
+ /** The latest PreToolUse or Stop record of a harness: observed within 24 h, stale beyond, never without one. */
39
+ export declare function observationOf(beats: HookBeats, harness: Agent, now?: number, wiringFiles?: readonly string[], event?: HookEvent): HookObservation;
40
+ /**
41
+ * @implements A-SPEC-772.6 — the files whose change can stop a harness running its Holmes hooks in `root`: what Claude,
42
+ * Codex and Antigravity read their hooks from (Codex's workspace trust too; its user-level trust file is excluded).
43
+ */
44
+ export declare function hookWiringFiles(root: string, harness: Agent, env?: Record<string, string | undefined>): string[];
45
+ /** "3 min", "5 h", "2 d" — for a stale observation's detail. */
46
+ export declare function ageText(ms: number): string;
47
+ export {};