@holmes-lab/holmes-kit 0.29.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/CHANGELOG.md +556 -0
  2. package/README.md +15 -5
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  9. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  10. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  11. package/dist/holmes/cli/agents-guidance.js +11 -8
  12. package/dist/holmes/cli/agents.d.ts +41 -0
  13. package/dist/holmes/cli/agents.js +382 -2
  14. package/dist/holmes/cli/attest.d.ts +2 -0
  15. package/dist/holmes/cli/attest.js +66 -15
  16. package/dist/holmes/cli/ci-gate.js +16 -1
  17. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  18. package/dist/holmes/cli/claude-switches.js +967 -0
  19. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  20. package/dist/holmes/cli/codex-hooks.js +802 -0
  21. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  22. package/dist/holmes/cli/codex-oracle.js +1245 -0
  23. package/dist/holmes/cli/codex-toml.d.ts +58 -1
  24. package/dist/holmes/cli/codex-toml.js +456 -40
  25. package/dist/holmes/cli/doctor.d.ts +108 -8
  26. package/dist/holmes/cli/doctor.js +1408 -98
  27. package/dist/holmes/cli/index.js +23 -11
  28. package/dist/holmes/cli/init.d.ts +13 -0
  29. package/dist/holmes/cli/init.js +749 -77
  30. package/dist/holmes/cli/interactive-prompt.js +2 -2
  31. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  32. package/dist/holmes/cli/mcp-launcher.js +189 -6
  33. package/dist/holmes/cli/mcp-version.js +13 -2
  34. package/dist/holmes/cli/settings-merge.js +8 -2
  35. package/dist/holmes/cli/upgrade.d.ts +13 -0
  36. package/dist/holmes/cli/upgrade.js +116 -23
  37. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  38. package/dist/holmes/cli/workspace-scope.js +375 -0
  39. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  40. package/dist/holmes/cli/worktree-readiness.js +17 -3
  41. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  42. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  43. package/dist/holmes/cpg/cycle-detect.js +2 -1
  44. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  45. package/dist/holmes/cpg/required-calls.js +8 -1
  46. package/dist/holmes/governance/autonomy.d.ts +9 -0
  47. package/dist/holmes/governance/autonomy.js +28 -1
  48. package/dist/holmes/governance/constitution-debt.js +3 -2
  49. package/dist/holmes/governance/constitution.js +15 -3
  50. package/dist/holmes/governance/provenance-chain.js +3 -2
  51. package/dist/holmes/governance/push-gate-runner.js +4 -3
  52. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  53. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  54. package/dist/holmes/guardrail/linear-match.js +256 -0
  55. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  56. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  57. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  58. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  59. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  60. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  61. package/dist/holmes/guardrail/shell-words.js +1720 -0
  62. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  63. package/dist/holmes/guardrail/write-target.js +2379 -87
  64. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  65. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  66. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  67. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  68. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  69. package/dist/holmes/hooks/rtm-refresh-child.js +102 -18
  70. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  71. package/dist/holmes/hooks/rtm-refresh.js +60 -15
  72. package/dist/holmes/hooks/session-start.d.ts +10 -0
  73. package/dist/holmes/hooks/session-start.js +31 -7
  74. package/dist/holmes/hooks/stop.d.ts +2 -1
  75. package/dist/holmes/hooks/stop.js +197 -91
  76. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  77. package/dist/holmes/mcp/approval-adapters.js +21 -0
  78. package/dist/holmes/mcp/approval-commit.d.ts +20 -0
  79. package/dist/holmes/mcp/approval-commit.js +108 -0
  80. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  81. package/dist/holmes/mcp/approval-intent.js +67 -0
  82. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  83. package/dist/holmes/mcp/approval-policy.js +18 -0
  84. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  85. package/dist/holmes/mcp/elicit-approval.js +8 -3
  86. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  87. package/dist/holmes/mcp/handlers/graph-operations.js +15 -6
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  89. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  90. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  91. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  92. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  93. package/dist/holmes/mcp/handlers/requirement-triage.js +48 -11
  94. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  95. package/dist/holmes/mcp/handlers/review-evidence.js +15 -5
  96. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +18 -0
  97. package/dist/holmes/mcp/handlers/slice-orchestration.js +122 -16
  98. package/dist/holmes/mcp/handlers/spec-approval.d.ts +35 -2
  99. package/dist/holmes/mcp/handlers/spec-approval.js +175 -57
  100. package/dist/holmes/mcp/handlers/spec-authoring.js +36 -3
  101. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  102. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  103. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  104. package/dist/holmes/mcp/handlers.d.ts +126 -8
  105. package/dist/holmes/mcp/handlers.js +109 -18
  106. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  107. package/dist/holmes/mcp/harness-attestation.js +179 -0
  108. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  109. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  110. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +72 -2
  111. package/dist/holmes/mcp/requirement-triage-evidence.js +227 -1
  112. package/dist/holmes/mcp/server.js +24 -3
  113. package/dist/holmes/mcp/supervisor.js +7 -3
  114. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  115. package/dist/holmes/mcp/tool-schemas.js +54 -7
  116. package/dist/holmes/mcp/validate-args.js +12 -0
  117. package/dist/holmes/project/bounded-io.d.ts +102 -0
  118. package/dist/holmes/project/bounded-io.js +212 -0
  119. package/dist/holmes/project/change-source.js +3 -1
  120. package/dist/holmes/project/ci-runs.js +3 -2
  121. package/dist/holmes/project/ignore.d.ts +31 -2
  122. package/dist/holmes/project/ignore.js +409 -50
  123. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  124. package/dist/holmes/project/regular-file-guard.js +149 -0
  125. package/dist/holmes/project/root.js +12 -3
  126. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  127. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  128. package/dist/holmes/reverse/anchor.js +4 -3
  129. package/dist/holmes/reverse/scan.js +6 -2
  130. package/dist/holmes/review/commit-text.js +3 -2
  131. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  132. package/dist/holmes/review/condition-hunk-replay.js +13 -2
  133. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  134. package/dist/holmes/review/failed-test-names.js +13 -10
  135. package/dist/holmes/review/findings.js +3 -1
  136. package/dist/holmes/review/kills-check.js +6 -1
  137. package/dist/holmes/review/point-in-time-replay.js +5 -4
  138. package/dist/holmes/review/replay-corpus.js +5 -4
  139. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  140. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  141. package/dist/holmes/review/run-replay.js +3 -2
  142. package/dist/holmes/review/scope.js +6 -1
  143. package/dist/holmes/review/temporal-prior.js +3 -2
  144. package/dist/holmes/review/test-evidence.js +3 -2
  145. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  146. package/dist/holmes/review/test-outcomes.js +92 -2
  147. package/dist/holmes/review/test-runner.d.ts +6 -0
  148. package/dist/holmes/review/test-runner.js +36 -15
  149. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  150. package/dist/holmes/rtm/anchor-ids.js +42 -2
  151. package/dist/holmes/rtm/file-anchors.js +4 -1
  152. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  153. package/dist/holmes/rtm/git-changes.js +3 -1
  154. package/dist/holmes/rtm/graph-store.js +3 -2
  155. package/dist/holmes/rtm/test-scope.js +9 -4
  156. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  157. package/dist/holmes/spec/compat-impact.js +682 -11
  158. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  159. package/dist/holmes/spec/entity-integration.js +3 -2
  160. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  161. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  162. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  163. package/dist/holmes/spec/renumber.js +25 -10
  164. package/dist/holmes/spec/spec-parser.js +9 -3
  165. package/dist/holmes/spec/yaml-scalar.js +2 -2
  166. package/dist/holmes/update/refresh.js +3 -1
  167. package/dist/holmes/update/update-notice.d.ts +6 -0
  168. package/dist/holmes/update/update-notice.js +18 -1
  169. package/package.json +11 -4
@@ -36,11 +36,13 @@ 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
39
40
  // @implements A-SPEC-709
40
41
  // @implements A-SPEC-340
41
42
  // @implements A-SPEC-100.2
42
43
  const fs = __importStar(require("node:fs"));
43
44
  const path = __importStar(require("node:path"));
45
+ const os = __importStar(require("node:os"));
44
46
  const settings_merge_1 = require("./settings-merge");
45
47
  const gitignore_merge_1 = require("./gitignore-merge");
46
48
  const settings_merge_2 = require("./settings-merge");
@@ -49,11 +51,16 @@ const agents_guidance_plan_1 = require("./agents-guidance-plan");
49
51
  const agents_guidance_file_1 = require("./agents-guidance-file");
50
52
  const agents_1 = require("./agents");
51
53
  const roles_readme_1 = require("./roles-readme");
54
+ const workspace_scope_1 = require("./workspace-scope");
52
55
  const mcp_launcher_1 = require("./mcp-launcher");
53
56
  const codex_toml_1 = require("./codex-toml");
57
+ const codex_hooks_1 = require("./codex-hooks");
58
+ const codex_oracle_1 = require("./codex-oracle");
54
59
  const pre_tool_use_1 = require("../hooks/pre-tool-use");
55
60
  const governed_precondition_1 = require("./governed-precondition");
56
61
  const risk_gate_1 = require("../guardrail/risk-gate");
62
+ const bounded_io_1 = require("../project/bounded-io");
63
+ const claude_switches_1 = require("./claude-switches");
57
64
  /**
58
65
  * `holmes-kit init` — wire holmes-kit into a TARGET project (the I/O half; all merge logic is pure
59
66
  * and lives in settings-merge.ts / gitignore-merge.ts).
@@ -122,8 +129,35 @@ function readJson(file) {
122
129
  const missing = e.code === 'ENOENT';
123
130
  return { value: undefined, raw: null, parseError: false, unreadable: !missing };
124
131
  }
132
+ return parsedJson(raw);
133
+ }
134
+ /**
135
+ * @implements A-SPEC-251.1 (round 26) — a settings file or `.mcp.json` init cannot read is refused before anything is
136
+ * written: an unreadable settings file let init write `.mcp.json` and then fail, the dry run promised "the gate is
137
+ * enforced", and the self-disarm guard read an unreadable file as "not wired" (measured).
138
+ */
139
+ function readJsonOrRefuse(file) {
140
+ const r = readJson(file);
141
+ if (r.unreadable) {
142
+ let why = '';
143
+ try {
144
+ fs.readFileSync(file, 'utf8');
145
+ }
146
+ catch (e) {
147
+ why = (e instanceof Error ? e.message : String(e)).slice(0, 300);
148
+ }
149
+ throw new InitRefusal(`could not read ${file}, so it was not overwritten${why === '' ? '' : `: ${why}`}`);
150
+ }
151
+ return r;
152
+ }
153
+ function parsedJson(raw) {
154
+ // @implements A-SPEC-251.1 (round 35) — an empty, whitespace-only or BOM-only file is `{}` to Claude, and a BOM is not part
155
+ // of the JSON (init refused them — measured).
156
+ const text = raw.replace(/^\uFEFF/, '');
157
+ if (text.trim() === '')
158
+ return { value: {}, raw, parseError: false, unreadable: false };
125
159
  try {
126
- return { value: JSON.parse(raw), raw, parseError: false, unreadable: false };
160
+ return { value: JSON.parse(text), raw, parseError: false, unreadable: false };
127
161
  }
128
162
  catch {
129
163
  return { value: undefined, raw, parseError: true, unreadable: false };
@@ -207,14 +241,217 @@ function writeFileSafe(file, content) {
207
241
  }
208
242
  const settingsPathOf = (target, which) => path.join(target, '.claude', which === 'local' ? 'settings.local.json' : 'settings.json');
209
243
  exports.settingsPathOf = settingsPathOf;
244
+ /**
245
+ * @implements A-SPEC-251.1 (round 32) — where a settings file's hook structure has the wrong shape (a TypeError ended init
246
+ * on five such shapes — measured): the path to the first bad value, else null.
247
+ */
248
+ function hookShapeProblem(settings) {
249
+ // Round 33: the whole file — a settings file that is not an object, or MCP server lists that are not lists of strings,
250
+ // crashed init or were merged into nonsense (`"abc"` became `["a","b","c",…]` — measured).
251
+ if (settings === undefined)
252
+ return null;
253
+ if (settings === null || typeof settings !== 'object' || Array.isArray(settings))
254
+ return 'the file is not a JSON object';
255
+ for (const key of ['enabledMcpjsonServers', 'disabledMcpjsonServers']) {
256
+ const v = settings[key];
257
+ if (v !== undefined && (!Array.isArray(v) || !v.every((x) => typeof x === 'string')))
258
+ return `\`${key}\` is not a list of names`;
259
+ }
260
+ // Round 33: an entry Claude cannot load makes it apply nothing from the file (A-SPEC-251.2). Round 34: judged by Claude
261
+ // 2.1.281's own loader, over the whole file (a top-level `"PreToolUse"`, `timeout: 0` and `matcher: null` were wired and
262
+ // called "enforced" — measured).
263
+ const dropped = (0, claude_switches_1.claudeDropsFile)(settings);
264
+ if (dropped !== null)
265
+ return `${dropped} — Claude would apply nothing in this file`;
266
+ const hooks = settings.hooks;
267
+ // Round 33: Claude ignores a null `hooks` and a null event — they are empty here too (they were refused — measured).
268
+ if (hooks === undefined || hooks === null)
269
+ return null;
270
+ if (typeof hooks !== 'object' || Array.isArray(hooks))
271
+ return '`hooks` is not an object';
272
+ for (const [event, groups] of Object.entries(hooks)) {
273
+ // Round 34: a key that is not an event is dropped by Claude and kept as it is here (`"matcher": "x"` beside the events
274
+ // was refused — measured).
275
+ if (groups === null || !(0, claude_switches_1.isClaudeEvent)(event))
276
+ continue;
277
+ if (!Array.isArray(groups))
278
+ return `\`hooks.${event.slice(0, 64)}\` is not a list`;
279
+ for (const [i, g] of groups.entries()) {
280
+ if (g === null || typeof g !== 'object' || Array.isArray(g))
281
+ return `\`hooks.${event.slice(0, 64)}[${i}]\` is not an object`;
282
+ const hs = g.hooks;
283
+ if (hs !== undefined && !Array.isArray(hs))
284
+ return `\`hooks.${event.slice(0, 64)}[${i}].hooks\` is not a list`;
285
+ for (const [j, h] of (Array.isArray(hs) ? hs : []).entries()) {
286
+ if (h === null || typeof h !== 'object' || Array.isArray(h))
287
+ return `\`hooks.${event.slice(0, 64)}[${i}].hooks[${j}]\` is not an object`;
288
+ }
289
+ }
290
+ }
291
+ return null;
292
+ }
293
+ const SHAPE_HINT = 'Fix that value by hand (Claude skips or refuses it too), then run init again. Nothing was written.';
210
294
  /** Does the target already carry holmes wiring? (idempotency + self-disarm guard) */
211
295
  function alreadyWired(settings) {
212
- return Object.values(settings?.hooks ?? {}).some((groups) => (groups ?? []).some((g) => (g.hooks ?? []).some((h) => (0, settings_merge_1.isHolmesCommand)(h.command))));
296
+ // Round 34: a key beside the events may hold any value (Claude drops it).
297
+ return Object.values(settings?.hooks ?? {}).some((groups) => Array.isArray(groups)
298
+ && groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => (0, settings_merge_1.isHolmesCommand)(h?.command))));
299
+ }
300
+ /**
301
+ * @implements A-SPEC-251.1 (confirmation rounds 24–25) — a file init reads before it writes (to merge or keep it) that
302
+ * cannot be read is a refusal before any write: a directory, a link to `/dev/zero` or an unreadable file — shapes a
303
+ * repository can carry — at `.gitignore`, `.gitattributes` or an agent wiring file gave a stack trace (also with
304
+ * `--dry-run`/`--remove`), and the round-24 refusal kept "Codex MCP wiring is active" beside "could not read"
305
+ * (measured). The refusal carries no other message: nothing was written, so no claim stands.
306
+ */
307
+ class InitRefusal extends Error {
308
+ hint;
309
+ /** A-SPEC-251.1 (round 29): what to do, when it is not the unreadable-file advice (a link refusal said "a regular, readable file"). */
310
+ constructor(message, hint) {
311
+ super(message);
312
+ this.hint = hint;
313
+ }
314
+ }
315
+ /**
316
+ * @implements A-SPEC-251.1 (round 27/28) — the first link on the way from the target to `file` that leads out of the
317
+ * target, with where it leads; null when there is none. Round 28 judges by DESTINATION, not by git's tracking: a case
318
+ * variant `.AGENTS`, a submodule's link and a git that did not answer each slipped the round-27 "tracked links only"
319
+ * test and `~/.codex/hooks.json` was broken again (measured). The one exception is the dotfiles pattern: a Claude
320
+ * settings FILE that is itself a link the repository holding it does not carry (asked case-folded, from that link's own
321
+ * repository); a git that does not answer there refuses too.
322
+ */
323
+ function repoCarriedEscape(target, file) {
324
+ const rel = path.relative(target, file);
325
+ if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
326
+ return null;
327
+ let realTarget;
328
+ try {
329
+ realTarget = fs.realpathSync.native(target);
330
+ }
331
+ catch {
332
+ return null;
333
+ }
334
+ const parts = rel.split(path.sep);
335
+ let cur = target;
336
+ for (let i = 0; i < parts.length; i++) {
337
+ cur = path.join(cur, parts[i]);
338
+ let st;
339
+ try {
340
+ st = fs.lstatSync(cur);
341
+ }
342
+ catch {
343
+ return null;
344
+ }
345
+ if (!st.isSymbolicLink())
346
+ continue;
347
+ let to;
348
+ // Round 29: a dangling link resolves from its REAL parent (resolved from the spelled one, a target reached through a
349
+ // directory link read its in-target dangling link as leading out — measured).
350
+ try {
351
+ to = fs.realpathSync.native(cur);
352
+ }
353
+ catch {
354
+ try {
355
+ to = path.resolve(fs.realpathSync.native(path.dirname(cur)), fs.readlinkSync(cur));
356
+ }
357
+ catch {
358
+ to = cur;
359
+ }
360
+ }
361
+ const inside = path.relative(realTarget, to);
362
+ if (inside === '' || (inside !== '..' && !inside.startsWith('..' + path.sep) && !path.isAbsolute(inside)))
363
+ continue;
364
+ const settingsFile = i === parts.length - 1 && parts.length === 2 && parts[0].toLowerCase() === '.claude' && /^settings(?:\.local)?\.json$/i.test(parts[1]);
365
+ if (settingsFile && dotfileDestination(to) && linkCarried(cur) === false)
366
+ continue;
367
+ return { link: cur, to };
368
+ }
369
+ return null;
370
+ }
371
+ /**
372
+ * @implements A-SPEC-251.1 (round 29) — the dotfiles exception's destination: a Claude settings file by name, outside every
373
+ * harness configuration home (a settings link to `~/.codex/hooks.json` merged Claude settings into Codex's user hooks and
374
+ * turned the Codex gate off everywhere — measured).
375
+ */
376
+ function dotfileDestination(to) {
377
+ if (!/^settings(?:\.local)?\.json$/i.test(path.basename(to)))
378
+ return false;
379
+ const home = (() => { try {
380
+ return os.homedir();
381
+ }
382
+ catch {
383
+ return '';
384
+ } })();
385
+ // Round 30: `$CLAUDE_CONFIG_DIR` is Claude's home when set (a link to its settings.json took Holmes hooks into the
386
+ // user-level settings — measured).
387
+ const homes = [process.env.CODEX_HOME, process.env.CLAUDE_CONFIG_DIR, home && path.join(home, '.codex'), home && path.join(home, '.claude'), home && path.join(home, '.gemini')]
388
+ .filter((h) => typeof h === 'string' && h !== '')
389
+ .map((h) => { try {
390
+ return fs.realpathSync.native(h);
391
+ }
392
+ catch {
393
+ return path.resolve(h);
394
+ } });
395
+ const fold = (p) => p.normalize('NFC').toUpperCase();
396
+ return !homes.some((h) => { const r = path.relative(fold(h), fold(to)); return r === '' || (r !== '..' && !r.startsWith('..' + path.sep) && !path.isAbsolute(r)); });
397
+ }
398
+ /** Whether the repository holding `link` tracks it (case-folded); null when git did not answer. */
399
+ function linkCarried(link) {
400
+ const dir = path.dirname(link);
401
+ const top = (0, bounded_io_1.gitOnce)(dir, ['rev-parse', '--show-toplevel'], 'repo');
402
+ // Round 29: no git where a `.git` exists does not answer (PATH without git wrote through a tracked link — measured).
403
+ // Round 30: from the real directory too (a target reached through a link into a repository subdirectory walked only
404
+ // the spelled path and found no `.git` — measured).
405
+ if (top.status !== 0 && top.error?.code === 'ENOENT'
406
+ && ((0, bounded_io_1.gitEntryAbove)(dir) || (0, bounded_io_1.gitEntryAbove)((() => { try {
407
+ return fs.realpathSync.native(dir);
408
+ }
409
+ catch {
410
+ return dir;
411
+ } })())))
412
+ return null;
413
+ if (top.status !== 0)
414
+ return (0, bounded_io_1.gitAnswerOf)(top, dir) === 'no-repository' ? false : null;
415
+ let realTop;
416
+ let realDir;
417
+ try {
418
+ realTop = fs.realpathSync.native(top.stdout.trim());
419
+ realDir = fs.realpathSync.native(dir);
420
+ }
421
+ catch {
422
+ return null;
423
+ }
424
+ const rel = [path.relative(realTop, realDir), path.basename(link)].filter((x) => x !== '').join('/').split(path.sep).join('/');
425
+ const listed = (0, bounded_io_1.gitOnce)(realTop, ['ls-files', '-z', '--', `:(icase,literal)${rel}`], 'repo');
426
+ if (listed.status !== 0)
427
+ return null;
428
+ const fold = (p) => p.normalize('NFC').toUpperCase();
429
+ return listed.stdout.split('\0').some((e) => fold(e) === fold(rel));
430
+ }
431
+ function readForMerge(p) {
432
+ try {
433
+ return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
434
+ }
435
+ catch (e) {
436
+ throw new InitRefusal(`could not read ${p}, so it was not overwritten: ${(e instanceof Error ? e.message : String(e)).slice(0, 300)}`);
437
+ }
213
438
  }
214
439
  function runInit(opts) {
440
+ try {
441
+ return runInitUnguarded(opts);
442
+ }
443
+ catch (e) {
444
+ if (!(e instanceof InitRefusal))
445
+ throw e;
446
+ return { ok: false, exitCode: 2, changes: [], messages: [e.message,
447
+ e.hint ?? 'Check that it is a regular, readable file (not a directory or a link to a device), then run again. Nothing was written.'] };
448
+ }
449
+ }
450
+ function runInitUnguarded(opts) {
215
451
  const messages = [];
216
452
  const changes = [];
217
453
  const removals = [];
454
+ const pendingLinks = [];
218
455
  const guidanceFile = path.join(opts.target, 'AGENTS.md');
219
456
  let guidance;
220
457
  if (!opts.remove) {
@@ -241,7 +478,11 @@ function runInit(opts) {
241
478
  'This package ships a compiled dist/ — if you are working from the repository run `npm run build`, and if from an install, reinstall.',
242
479
  ] };
243
480
  }
244
- const s = readJson(settingsPath);
481
+ // @implements A-SPEC-251.1 (0.31.0) — an npx wiring hands each session workspace the server's launch; say so once.
482
+ if (opts.mcp && !opts.remove && (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: path.join(opts.packageRoot, 'bin', 'holmes-mcp.js'), flag: opts.mcpLauncher }).command === 'npx') {
483
+ messages.push(mcp_launcher_1.NPX_WIRING_NOTE);
484
+ }
485
+ const s = readJsonOrRefuse(settingsPath);
245
486
  if (s.parseError) {
246
487
  return { ok: false, exitCode: 2, changes, messages: [
247
488
  `${settingsPath} is not valid JSON (comments/JSONC are not supported here).`,
@@ -257,20 +498,66 @@ function runInit(opts) {
257
498
  // and both the guard and the approval requirement excluded `--remove`, which is the most complete
258
499
  // way to take governance off. A session must not be able to unwire the gate that governs it,
259
500
  // whichever flag it reaches for. Wiring is asked of BOTH settings files.
260
- const wiredAnywhere = ['local', 'project'].some((which) => alreadyWired(readJson((0, exports.settingsPathOf)(opts.target, which)).value));
501
+ const wiredAnywhere = ['local', 'project'].map((which) => {
502
+ const file = (0, exports.settingsPathOf)(opts.target, which);
503
+ const value = readJsonOrRefuse(file).value;
504
+ const problem = hookShapeProblem(value);
505
+ if (problem !== null)
506
+ throw new InitRefusal(`${file}: ${problem}, so it was not changed — fix it by hand and run again`, SHAPE_HINT);
507
+ return alreadyWired(value);
508
+ }).some((w) => w);
261
509
  if (!opts.remove && wiredAnywhere && !opts.force && !opts.allowAdditive) {
262
510
  return { ok: false, exitCode: 2, changes, messages: [
263
511
  'This target already has holmes-kit wiring. Re-run with --force to change it.',
264
512
  ] };
265
513
  }
266
- if ((opts.force || (opts.remove && wiredAnywhere))
514
+ // @implements A-SPEC-727 — Codex's config.toml and hooks.json are user-level: removing their
515
+ // holmes-kit entries disarms Codex in EVERY workspace, so it is self-disarm whether or not the
516
+ // named target is wired (an empty --target must not be a door around the approval).
517
+ const codexAsked = (opts.agents ?? []).includes('codex');
518
+ const readOrNull = (p) => { try {
519
+ return fs.readFileSync(p, 'utf8');
520
+ }
521
+ catch {
522
+ return null;
523
+ } };
524
+ // @implements A-SPEC-727 (round 6) — the hooks file is read as Codex reads it: strict UTF-8. An
525
+ // undecodable file is judged by its bytes' text for Holmes commands, and refused for rewriting.
526
+ const readHooksOrNull = (p) => {
527
+ try {
528
+ const d = (0, codex_hooks_1.decodeCodexHooksBytes)(fs.readFileSync(p));
529
+ return d.ok ? d.text : d.lossy;
530
+ }
531
+ catch {
532
+ return null;
533
+ }
534
+ };
535
+ const codexUserWired = opts.remove && codexAsked && (() => {
536
+ const toml = readOrNull(opts.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)());
537
+ const hooks = readHooksOrNull(opts.codexHooksPath ?? (0, codex_hooks_1.defaultCodexHooksPath)());
538
+ return (toml !== null && (0, codex_toml_1.removeCodexToml)(toml) !== toml) || (hooks !== null && (0, codex_hooks_1.holmesCommandsPresent)(hooks));
539
+ })();
540
+ // Codex keys trust by (event, group index, hook index) plus the definition's hash (measured with
541
+ // codex-cli 0.155.1 `hooks/list`). A merge that would change the identity of any hook already in
542
+ // the file — re-pointing at another install, restoring a narrowed matcher, moving a group — switches
543
+ // it off in every workspace until trusted again: a disarm by Holmes's own CLI, so it asks first.
544
+ const codexHooksRepoint = !opts.remove && codexAsked && (() => {
545
+ const hooks = readHooksOrNull(opts.codexHooksPath ?? (0, codex_hooks_1.defaultCodexHooksPath)());
546
+ if (hooks === null)
547
+ return false;
548
+ const merged = (0, codex_hooks_1.mergeCodexUserHooks)(hooks, opts.packageRoot);
549
+ return merged.ok && (0, codex_hooks_1.codexHooksTrustChanges)(hooks, merged.content);
550
+ })();
551
+ if ((opts.force || codexHooksRepoint || (opts.remove && (wiredAnywhere || codexUserWired)))
267
552
  && !(0, risk_gate_1.approvalCovers)(opts.approval, { kind: 'governance-wiring', target: opts.target }, new Date().toISOString())) {
268
553
  // covers, not merely well-formed (round-3): an expired or elsewhere-scoped token re-wired
269
554
  // governance — the exact master-key behaviour A-SPEC-133's narrowing exists to end.
270
555
  return { ok: false, exitCode: 2, changes, messages: [
271
556
  opts.remove
272
557
  ? 'Stripping governance wiring is also changing the wiring — an out-of-band approval is required (self-disarm prevention).'
273
- : '--force changes existing governance wiring and requires an out-of-band approval that covers it.',
558
+ : codexHooksRepoint && !opts.force
559
+ ? `Re-wiring the Codex user hooks would change hooks Codex already trusts (another holmes-kit install, a changed matcher, or a moved group); Codex would treat them as new, untrusted hooks — off in every workspace until trusted again with /hooks — so an out-of-band approval is required.`
560
+ : '--force changes existing governance wiring and requires an out-of-band approval that covers it.',
274
561
  `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "governance-wiring") and re-run.`,
275
562
  ] };
276
563
  }
@@ -286,11 +573,28 @@ function runInit(opts) {
286
573
  `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "autonomy-grant") and re-run with --autonomy.`,
287
574
  ] };
288
575
  }
289
- const m = readJson(mcpPath);
576
+ const m = readJsonOrRefuse(mcpPath);
577
+ // @implements A-SPEC-251.1 (round 33) — a `.mcp.json` whose shape cannot be merged is refused by name (`mcpServers:
578
+ // "abc"` became index keys, an env string became keys `0`, `1` — measured). Round 34: only when init writes it
579
+ // (`--no-mcp` exited 2 over a file it does not touch — measured).
580
+ if (opts.mcp) {
581
+ const v = m.value;
582
+ const obj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
583
+ const servers = obj(v) ? v.mcpServers : undefined;
584
+ const own = obj(servers) ? servers[exports.SERVER_NAME] : undefined;
585
+ const problem = v === undefined ? null
586
+ : !obj(v) ? 'the file is not a JSON object'
587
+ : servers !== undefined && !obj(servers) ? '`mcpServers` is not an object'
588
+ : own !== undefined && !obj(own) ? `\`mcpServers.${exports.SERVER_NAME}\` is not an object`
589
+ : own !== undefined && own.env !== undefined && !obj(own.env) ? `\`mcpServers.${exports.SERVER_NAME}.env\` is not an object`
590
+ : null;
591
+ if (problem !== null)
592
+ throw new InitRefusal(`${mcpPath}: ${problem}, so it was not changed — fix it by hand and run again`, SHAPE_HINT);
593
+ }
290
594
  if (m.parseError) {
291
595
  return { ok: false, exitCode: 2, changes, messages: [`${mcpPath} is not valid JSON — refusing to touch it.`] };
292
596
  }
293
- const gitignoreBefore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
597
+ const gitignoreBefore = readForMerge(gitignorePath) ?? '';
294
598
  if (opts.remove) {
295
599
  let settings = (0, settings_merge_1.removeHooks)(s.value);
296
600
  settings = (0, settings_merge_1.disableMcpServer)(settings, exports.SERVER_NAME);
@@ -304,7 +608,7 @@ function runInit(opts) {
304
608
  // @implements A-SPEC-256.1 — remove is install's mirror: the union-attributes block this init
305
609
  // wrote leaves with it (round-1 adversarial finding: it stayed behind forever).
306
610
  const rmAttrsPath = path.join(opts.target, '.gitattributes');
307
- const rmAttrsBefore = fs.existsSync(rmAttrsPath) ? fs.readFileSync(rmAttrsPath, 'utf8') : '';
611
+ const rmAttrsBefore = readForMerge(rmAttrsPath) ?? '';
308
612
  if ((0, gitignore_merge_1.hasGitignoreBlock)(rmAttrsBefore)) {
309
613
  changes.push({ path: rmAttrsPath, before: rmAttrsBefore, after: (0, gitignore_merge_1.removeGitignoreBlock)(rmAttrsBefore) });
310
614
  }
@@ -354,14 +658,20 @@ function runInit(opts) {
354
658
  const mcpEntry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
355
659
  changes.push({ path: mcpPath, before: m.raw, after: JSON.stringify((0, settings_merge_1.mergeMcpServers)(m.value, exports.SERVER_NAME, mcpEntry, opts.specsDir, opts.autonomy), null, 2) + '\n' });
356
660
  }
357
- changes.push({ path: settingsPath, before: s.raw, after: JSON.stringify(settings, null, 2) + '\n' });
661
+ const settingsText = JSON.stringify(settings, null, 2) + '\n';
662
+ // @implements A-SPEC-251.1 (rounds 35–36) — Claude does not read a settings file over 2 MiB: the file init writes must not
663
+ // be one (a file init does not write is Claude's to read as it is — a 1.6 MiB one-line project file was refused, measured).
664
+ if (Buffer.byteLength(settingsText) > claude_switches_1.CLAUDE_SETTINGS_MAX_BYTES) {
665
+ throw new InitRefusal(`${settingsPath}: the file would be larger than ${claude_switches_1.CLAUDE_SETTINGS_MAX_BYTES / (1024 * 1024)} MiB, which Claude does not read, so it was not changed`, SHAPE_HINT);
666
+ }
667
+ changes.push({ path: settingsPath, before: s.raw, after: settingsText });
358
668
  const gitignoreAfter = (0, gitignore_merge_1.mergeGitignore)(gitignoreBefore);
359
669
  if (gitignoreAfter !== gitignoreBefore)
360
670
  changes.push({ path: gitignorePath, before: gitignoreBefore || null, after: gitignoreAfter });
361
671
  // @implements A-SPEC-256.1 — the append-only files merge with union in every governed project,
362
672
  // not only this repository: a colleague's merge losing ledger lines is the disease.
363
673
  const gitattributesPath = path.join(opts.target, '.gitattributes');
364
- const gitattributesBefore = fs.existsSync(gitattributesPath) ? fs.readFileSync(gitattributesPath, 'utf8') : '';
674
+ const gitattributesBefore = readForMerge(gitattributesPath) ?? '';
365
675
  const gitattributesAfter = (0, gitignore_merge_1.mergeGitattributes)(gitattributesBefore);
366
676
  if (gitattributesAfter !== gitattributesBefore)
367
677
  changes.push({ path: gitattributesPath, before: gitattributesBefore || null, after: gitattributesAfter });
@@ -375,47 +685,102 @@ function runInit(opts) {
375
685
  }
376
686
  messages.push('Restart Claude Code — hooks and MCP servers are read at session start.');
377
687
  }
378
- // @implements A-SPEC-266 — Codex reads MCP servers from `.codex/config.toml` (TOML
379
- // `[mcp_servers.*]`), NOT the `.codex/mcp_config.json` (JSON) this project used to write and Codex
380
- // never loaded. That file also holds the user's other Codex settings, so — like `.mcp.json` — we
381
- // MERGE only our table. The obsolete JSON is migrated away so no dead wiring is left behind.
382
- let codexJsonToMigrate = null; // deleted only after the write loop confirms config.toml
383
- {
384
- const codexDir = path.join(opts.target, '.codex');
385
- const codexTomlPath = path.join(codexDir, 'config.toml');
386
- const codexJsonPath = path.join(codexDir, 'mcp_config.json');
387
- // A `.codex/config.toml` we cannot read (a directory, a permission wall, a dangling symlink) is
388
- // NOT touched — reading it eagerly with readFileSync threw and crashed the whole init. Mirror the
389
- // `.mcp.json` "refusing to touch it" discipline: skip codex wiring and say so, migrate nothing.
688
+ // @implements A-SPEC-721 — Codex CLI loads its default user config, not a table merely placed in
689
+ // the repository. The owned server table is merged there and has no fixed HOLMES_SPECS binding.
690
+ // The active file is a user-level resource, not a target artifact: merely removing Claude/AGY
691
+ // wiring must not probe or mutate it. Explicit `--agent codex` is the authority for both merge
692
+ // and owned-table removal, so tests and consumers can safely operate without a writable home.
693
+ // A-SPEC-727 (round 5): the summary line claims the Codex gate only when the hooks file was wired.
694
+ let codexHooksWired = false;
695
+ // A-SPEC-251.1 (round 27): and the tools only when the MCP registration was written (`--no-mcp` and a refused shape
696
+ // still said "tools … wired" — measured).
697
+ let codexMcpWired = false;
698
+ // @implements A-SPEC-738 (round 6) — a claim made without Codex is labelled, as doctor's lines are.
699
+ let codexApproximate = null;
700
+ if ((opts.agents ?? []).includes('codex')) {
701
+ const codexTomlPath = opts.codexConfigPath ?? (0, codex_toml_1.defaultCodexConfigPath)();
702
+ const hooksPath = opts.codexHooksPath ?? (0, codex_hooks_1.defaultCodexHooksPath)();
703
+ // @implements A-SPEC-738 — whether Codex loads a config or hooks file is Codex's answer where codex
704
+ // is installed (asked over copies, locally, once per distinct pair); otherwise the emulation.
705
+ let oracleFound;
706
+ const oracleAnswers = new Map();
707
+ const askCodexAbout = (configText, hooksText) => {
708
+ const key = JSON.stringify([configText, hooksText]);
709
+ const hit = oracleAnswers.get(key);
710
+ if (hit)
711
+ return hit;
712
+ const input = { configBytes: configText === null ? null : Buffer.from(configText, 'utf8'), hooksBytes: hooksText === null ? null : Buffer.from(hooksText, 'utf8'), cwd: opts.target, realConfigPath: codexTomlPath, realHooksPath: hooksPath };
713
+ let v;
714
+ if (opts.codexOracle)
715
+ v = opts.codexOracle(input);
716
+ else {
717
+ oracleFound ??= (0, codex_oracle_1.findCodex)(process.env, process.platform);
718
+ v = oracleFound.found ? (0, codex_oracle_1.askCodex)({ codex: oracleFound.codex, ...input }) : { available: false, reason: oracleFound.reason };
719
+ }
720
+ oracleAnswers.set(key, v);
721
+ return v;
722
+ };
723
+ const currentHooksText = () => { try {
724
+ return fs.existsSync(hooksPath) ? fs.readFileSync(hooksPath, 'utf8') : null;
725
+ }
726
+ catch {
727
+ return null;
728
+ } };
729
+ const otherLayerNotes = new Set();
730
+ // @implements A-SPEC-738 (round 12) — a layer note is printed only while the ask AFTER the write still
731
+ // reports it (measured: a partial holmes-kit layer refused the file BEFORE the write and init printed
732
+ // "nothing loads" beside "is active" while the merged result loaded).
733
+ let postWriteAsk = null;
734
+ const codexLoadProblem = (configText) => {
735
+ const v = askCodexAbout(configText, currentHooksText());
736
+ if (!v.available)
737
+ return (0, codex_toml_1.codexConfigLoadProblem)(configText);
738
+ // Round 3: another layer's refusal is not this file's fault — never refuse (or loop on) it.
739
+ if (v.configError === null && v.otherConfigError !== undefined)
740
+ otherLayerNotes.add((0, codex_oracle_1.clipText)(v.otherConfigError.trim(), 600));
741
+ return v.configError === null ? null : `Codex refuses it: ${(0, codex_oracle_1.clipText)(v.configError.trim(), 600)}`;
742
+ };
743
+ // An active config we cannot read is NOT touched. A legacy project artifact is deliberately
744
+ // preserved: deleting a file Codex does not load would add surprise without restoring wiring.
390
745
  let codexTomlBefore = null;
391
746
  let codexUnreadable = false;
747
+ let codexUndecodable = null;
392
748
  if (fs.existsSync(codexTomlPath)) {
749
+ // @implements A-SPEC-731 (round 6) — read as bytes and decode strictly: a lenient read wrote
750
+ // U+FFFD over the user's bytes and into the backup (measured).
393
751
  try {
394
- codexTomlBefore = fs.readFileSync(codexTomlPath, 'utf8');
752
+ const decoded = (0, codex_toml_1.readCodexConfigBytes)(fs.readFileSync(codexTomlPath));
753
+ if (decoded.ok)
754
+ codexTomlBefore = decoded.text;
755
+ else {
756
+ codexUnreadable = true;
757
+ codexUndecodable = decoded.reason;
758
+ }
395
759
  }
396
760
  catch {
397
761
  codexUnreadable = true;
398
762
  }
399
763
  }
400
- const wantsCodex = (opts.agents ?? []).includes('codex') && !codexUnreadable;
401
- if (codexUnreadable)
402
- messages.push(`Refusing to touch ${codexTomlPath} — it is not a readable file. Fix or remove it, then re-run.`);
403
- // @implements A-SPEC-266 (round-2 F3) — the obsolete JSON is deleted AFTER the config.toml write is
404
- // confirmed, never before: an eager delete followed by a failed toml write left the user with NO
405
- // codex wiring at all (and a message claiming nothing was lost). Here we only PLAN the migration;
406
- // the deletion runs post-write-loop (dry-run just previews it in `removals`).
407
- const migrateAwayCodexJson = () => {
408
- if (!fs.existsSync(codexJsonPath))
409
- return;
410
- if (opts.dryRun) {
411
- removals.push(codexJsonPath);
412
- return;
413
- }
414
- codexJsonToMigrate = codexJsonPath;
415
- };
764
+ const wantsCodex = !codexUnreadable;
765
+ // @implements A-SPEC-251.1 (round 27) — refused before anything is written, like every other file init reads: the
766
+ // message said "Refusing to touch" and init went on to claim the Codex gate and tools wired, exit 0 (measured).
767
+ if (codexUnreadable) {
768
+ throw new InitRefusal(codexUndecodable
769
+ ? `could not read ${codexTomlPath}, so it was not overwritten: ${codexUndecodable}`
770
+ : `could not read ${codexTomlPath}, so it was not overwritten: it is not a readable file`);
771
+ }
416
772
  if (opts.remove) {
417
- if (codexTomlBefore !== null) {
773
+ // @implements A-SPEC-731 (round 4) — a removal that would leave a loadable config unloadable (or
774
+ // still configuring holmes-kit) writes nothing.
775
+ const removalProblem = (after) => codexTomlBefore !== null && codexLoadProblem(codexTomlBefore) === null && after.trim() !== '' ? (0, codex_toml_1.codexConfigWriteProblem)(after, null) : null;
776
+ if (codexTomlBefore !== null && removalProblem((0, codex_toml_1.removeCodexToml)(codexTomlBefore)) !== null) {
777
+ messages.push(`Refusing to rewrite ${codexTomlPath}: ${removalProblem((0, codex_toml_1.removeCodexToml)(codexTomlBefore))}. Remove the holmes-kit entry by hand.`);
778
+ }
779
+ else if (codexTomlBefore !== null) {
418
780
  const after = (0, codex_toml_1.removeCodexToml)(codexTomlBefore);
781
+ // @implements A-SPEC-721 — the active entry is user-level: say so before anyone is surprised.
782
+ if (after !== codexTomlBefore)
783
+ messages.push(`${codexTomlPath} is Codex's user-level config: removing its holmes-kit entry turns Holmes MCP off in Codex for every workspace, not only ${opts.target}. Re-run holmes-kit init --agent codex in any workspace to restore it.`);
419
784
  if (after.trim() === '' && after !== codexTomlBefore) {
420
785
  // Our table was the only content — delete the file rather than leave it empty.
421
786
  if (opts.dryRun)
@@ -429,15 +794,190 @@ function runInit(opts) {
429
794
  changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
430
795
  }
431
796
  }
432
- migrateAwayCodexJson();
797
+ }
798
+ else if (wantsCodex && opts.mcp && codexTomlBefore !== null && (0, codex_toml_1.unownedHolmesShape)(codexTomlBefore)) {
799
+ // @implements A-SPEC-721 — merging our table into a file that already configures holmes-kit in
800
+ // another spelling would declare it twice; Codex would then reject the whole shared config.
801
+ messages.push(`Refusing to rewrite ${codexTomlPath}: it configures holmes-kit in a shape holmes-kit does not own (dotted keys, an inline table under [mcp_servers], or a holmes-kit subtable outside its table). Edit it by hand to a single [mcp_servers.holmes-kit] table, then re-run.`);
802
+ }
803
+ else if (wantsCodex && opts.mcp && codexTomlBefore !== null && codexLoadProblem(codexTomlBefore) !== null
804
+ && (0, codex_toml_1.codexConfigWriteProblem)((0, codex_toml_1.mergeCodexToml)(codexTomlBefore, (0, codex_toml_1.codexMcpBlock)((0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: path.join(opts.packageRoot, 'bin', 'holmes-mcp.js'), flag: opts.mcpLauncher }), opts.specsDir)), (() => { const e = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: path.join(opts.packageRoot, 'bin', 'holmes-mcp.js'), flag: opts.mcpLauncher }); return { command: e.command, args: e.args, env: { HOLMES_MCP_AUTORELOAD: '1' } }; })()) !== null) {
805
+ // @implements A-SPEC-731 (round 4/5) — Codex refuses a config that does not parse; merging into it
806
+ // would wire nothing while reporting success — unless replacing our own table is what repairs it.
807
+ messages.push(`Refusing to rewrite ${codexTomlPath}: it does not load in Codex (${codexLoadProblem(codexTomlBefore)}). Fix it by hand, then re-run.`);
433
808
  }
434
809
  else if (wantsCodex && opts.mcp) {
810
+ const repairing = codexTomlBefore !== null && codexLoadProblem(codexTomlBefore) !== null;
435
811
  const mcpBin = path.join(opts.packageRoot, 'bin', 'holmes-mcp.js');
436
812
  const entry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
437
813
  const after = (0, codex_toml_1.mergeCodexToml)(codexTomlBefore, (0, codex_toml_1.codexMcpBlock)(entry, opts.specsDir));
438
- if (after !== codexTomlBefore)
439
- changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
440
- migrateAwayCodexJson();
814
+ // @implements A-SPEC-731 (round 4) — the result is parsed before it is written: it must load, with
815
+ // exactly the entry holmes-kit writes (a closed inline `mcp_servers = { … }` cannot take our table).
816
+ const writeProblem = (0, codex_toml_1.codexConfigWriteProblem)(after, { command: entry.command, args: entry.args, env: { HOLMES_MCP_AUTORELOAD: '1' } })
817
+ // @implements A-SPEC-731 (round 6) — a result Codex would still refuse whole (another server,
818
+ // `model`, an out-of-range integer…) is not "active": write nothing and say why (measured).
819
+ ?? (() => { const lp = codexLoadProblem(after); return lp === null ? null : `Codex would refuse the whole file: ${lp}`; })();
820
+ if (writeProblem !== null) {
821
+ messages.push(`Refusing to rewrite ${codexTomlPath}: ${writeProblem}. Edit it by hand to a single [mcp_servers.holmes-kit] table (or remove holmes-kit from mcp_servers), then re-run.`);
822
+ }
823
+ else {
824
+ if (after !== codexTomlBefore)
825
+ changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
826
+ codexMcpWired = !opts.dryRun;
827
+ if (repairing)
828
+ messages.push(`${codexTomlPath} did not load (${codexLoadProblem(codexTomlBefore)}); holmes-kit repaired its own [mcp_servers.holmes-kit] table, and the result loads.`);
829
+ // @implements A-SPEC-738 (round 2) — "active" only if Codex would run THIS entry: a trusted project
830
+ // layer can replace it (measured: init said active while Codex ran an old install).
831
+ const seen = askCodexAbout(after, currentHooksText());
832
+ postWriteAsk = seen;
833
+ // @implements A-SPEC-738 (round 12) — a layer that hollows the gate (disabled tools) or redirects
834
+ // the store (env.HOLMES_SPECS, cwd) on the EFFECTIVE table (measured: init said "active").
835
+ const hollow = seen.available ? (0, codex_oracle_1.hollowedGateTools)(seen.holmesTable) : null;
836
+ // Round 14: against the file being written — a relative HOLMES_SPECS and CLAUDE_PROJECT_DIR redirect too.
837
+ const redirect = (0, codex_oracle_1.tableRedirection)(seen.available ? seen.holmesTable : null, (0, codex_oracle_1.ownHolmesTableOf)(after));
838
+ // @implements A-SPEC-738 (round 13) — authority another layer puts in the server's environment, or a
839
+ // second Holmes server carrying one (measured: init said "active" beside a forged HOLMES_APPROVAL).
840
+ // @implements A-SPEC-738 (round 16) — every layer node launch is checked against this install (shared cap).
841
+ // Round 18: and every layer npx launch against this install's version.
842
+ const install = { bin: (() => { try {
843
+ return fs.realpathSync.native(path.join(opts.packageRoot, 'bin', 'holmes-mcp.js'));
844
+ }
845
+ catch {
846
+ return null;
847
+ } })(), budget: { left: codex_oracle_1.INSTALL_CHECKS_MAX }, version: (0, mcp_launcher_1.readPackageVersion)(opts.packageRoot) ?? null };
848
+ const envFound = (0, codex_oracle_1.envFindings)(seen.available ? seen.holmesTable : null, (0, codex_oracle_1.ownHolmesTableOf)(after), true, install);
849
+ // @implements A-SPEC-738 (round 14) — a server the written file itself carries with that authority is the
850
+ // user's own (doctor WARNs it); only authority from another layer blocks "active".
851
+ const authority = [...envFound.authorityFromLayer, ...envFound.envVarsFromLayer.map((k) => (k === codex_oracle_1.UNREADABLE_ENV_VAR ? k : `env_vars ${k}`)),
852
+ ...(seen.available ? seen.otherHolmesServers ?? [] : [])
853
+ .filter((s) => { const f = (0, codex_oracle_1.envFindings)(s.table, (0, codex_oracle_1.ownHolmesTableOf)(after, s.name), s.holmes !== false, install); return f.authorityFromLayer.length + f.envVarsFromLayer.length > 0; })
854
+ .map((s) => (s.holmes !== false ? `a second Holmes server [mcp_servers.${(0, codex_oracle_1.clipText)(s.name, 80)}]` : `the server [mcp_servers.${(0, codex_oracle_1.clipText)(s.name, 80)}]`))];
855
+ const effective = seen.available && seen.holmesTable && typeof seen.holmesTable.command === 'string'
856
+ ? [seen.holmesTable.command, Array.isArray(seen.holmesTable.args) ? seen.holmesTable.args : entry.args] : null;
857
+ const overridden = effective !== null && JSON.stringify(effective) !== JSON.stringify([entry.command, entry.args]);
858
+ // @implements A-SPEC-738 (round 7) — a layer that DISABLES the server (measured: init said active while
859
+ // Codex's effective table carried `enabled = false` from a trusted project layer).
860
+ const disabledByLayer = seen.available && seen.holmesTable !== null
861
+ && (seen.holmesTable.enabled === false || (Array.isArray(seen.holmesTable.enabled_tools) && seen.holmesTable.enabled_tools.length === 0));
862
+ // Round 4: nothing is "active" in a workspace whose configuration Codex refuses (another layer).
863
+ const layerBlocked = seen.available && seen.otherConfigError !== undefined;
864
+ if (!seen.available)
865
+ codexApproximate = seen.reason;
866
+ // @implements A-SPEC-727 (round 9) — a dry run writes nothing, so it cannot say "is active".
867
+ messages.push(opts.dryRun
868
+ ? `Codex MCP wiring would be made in ${codexTomlPath} (dry run — nothing written).`
869
+ : layerBlocked
870
+ ? `Codex MCP wiring was written to ${codexTomlPath}, but Codex refuses this workspace's configuration because of another layer — nothing from Codex loads here until that file is fixed.`
871
+ : overridden
872
+ ? `Codex MCP wiring was written to ${codexTomlPath}, but another layer (a trusted project's .codex/config.toml or a profile) replaces it: Codex runs \`${(0, codex_oracle_1.clipText)(String(effective[0]))}\`. Remove or rewire that layer.`
873
+ : disabledByLayer
874
+ ? `Codex MCP wiring was written to ${codexTomlPath}, but another layer (a trusted project's .codex/config.toml or a profile) disables it: Codex's effective [mcp_servers.holmes-kit] sets ${seen.available && seen.holmesTable?.enabled === false ? 'enabled = false' : 'enabled_tools = []'}. Remove that setting from the layer.`
875
+ : authority.length > 0
876
+ ? `Codex MCP wiring was written to ${codexTomlPath}, but another layer (a trusted project's .codex/config.toml or a profile) hands the Holmes server an approval, autonomy, gate or egress-consent channel (${(0, codex_oracle_1.cappedList)(authority)}). Remove those settings from that layer.`
877
+ : hollow !== null
878
+ ? `Codex MCP wiring was written to ${codexTomlPath}, but another layer (a trusted project's .codex/config.toml or a profile) disables its governance tools (${hollow}) — the gate cannot act. Remove the disabled_tools/enabled_tools setting from that layer.`
879
+ : redirect.specs !== null || redirect.cwd !== null || redirect.projectDir !== null
880
+ ? `Codex MCP wiring was written to ${codexTomlPath}, but another layer (a trusted project's .codex/config.toml or a profile) redirects it: Codex's effective [mcp_servers.holmes-kit] sets ${redirect.specs !== null ? `env.HOLMES_SPECS = ${(0, codex_oracle_1.clipText)(redirect.specs)}` : redirect.projectDir !== null ? `env.CLAUDE_PROJECT_DIR = ${(0, codex_oracle_1.clipText)(redirect.projectDir)}` : `cwd = ${(0, codex_oracle_1.clipText)(String(redirect.cwd))}`}, so the server binds its spec store there, not to the session workspace. Remove that setting from the layer.`
881
+ : !seen.available
882
+ ? `Codex MCP wiring is active from ${codexTomlPath} (approximate — Codex was not asked: ${seen.reason}); restart Codex in the target workspace.`
883
+ : `Codex MCP wiring is active from ${codexTomlPath}; restart Codex in the target workspace.`);
884
+ }
885
+ }
886
+ for (const note of otherLayerNotes) {
887
+ // Round 12: after a write that loads, the pre-write refusal is history.
888
+ const stillBlocked = postWriteAsk === null || !postWriteAsk.available || postWriteAsk.otherConfigError !== undefined;
889
+ if (!stillBlocked)
890
+ continue;
891
+ messages.push(`Codex refuses this workspace's configuration because of another layer (not ${codexTomlPath}): ${note}. Nothing from Codex loads here until that file is fixed.`);
892
+ }
893
+ // @implements A-SPEC-727 — codex-cli 0.155 removed plugin hooks, so the gate is wired into the
894
+ // user-level hooks file Codex loads for every workspace. Holmes owns only groups whose every
895
+ // command is a Holmes kernel; an unreadable or malformed file is left untouched and named.
896
+ let hooksBefore = null;
897
+ let hooksUnreadable = false;
898
+ let hooksUndecodable = null;
899
+ if (fs.existsSync(hooksPath)) {
900
+ try {
901
+ const d = (0, codex_hooks_1.decodeCodexHooksBytes)(fs.readFileSync(hooksPath));
902
+ if (d.ok)
903
+ hooksBefore = d.text;
904
+ else
905
+ hooksUndecodable = d.lossy;
906
+ }
907
+ catch {
908
+ hooksUnreadable = true;
909
+ }
910
+ }
911
+ if (hooksUndecodable !== null) {
912
+ // Codex refuses the whole file; rewriting it would replace the user's bytes with U+FFFD.
913
+ messages.push(opts.remove && !(0, codex_hooks_1.holmesCommandsPresent)(hooksUndecodable)
914
+ ? `${hooksPath} is not valid UTF-8 and holds no holmes-kit hooks — left untouched.`
915
+ : `Refusing to rewrite ${hooksPath}: not valid UTF-8 (Codex cannot load it either). ${opts.remove ? 'Remove the holmes-kit hook entries by hand.' : 'Fix it by hand, then re-run.'}`);
916
+ }
917
+ else if (hooksUnreadable) {
918
+ messages.push(`Refusing to touch ${hooksPath} — it is not a readable file. Fix or remove it, then re-run.`);
919
+ }
920
+ else if (opts.remove) {
921
+ if (hooksBefore !== null && (0, codex_hooks_1.holmesCommandsPresent)(hooksBefore)) {
922
+ const r = (0, codex_hooks_1.removeCodexUserHooks)(hooksBefore);
923
+ if (!r.ok)
924
+ messages.push(`Refusing to rewrite ${hooksPath}: ${r.reason}. Remove the holmes-kit hook entries by hand.`);
925
+ else if (r.content !== hooksBefore || r.empty)
926
+ messages.push(`${hooksPath} is Codex's user-level hooks file: removing its holmes-kit hooks turns the Holmes gate off in Codex for every workspace, not only ${opts.target}. Re-run holmes-kit init --agent codex in any workspace to restore it.`);
927
+ if (r.ok && r.empty) {
928
+ if (opts.dryRun)
929
+ removals.push(hooksPath);
930
+ else {
931
+ fs.rmSync(hooksPath, { force: true });
932
+ messages.push(`Removed ${hooksPath} (holmes-kit hooks were its only content).`);
933
+ }
934
+ }
935
+ else if (r.ok && r.content !== hooksBefore)
936
+ changes.push({ path: hooksPath, before: hooksBefore, after: r.content });
937
+ }
938
+ }
939
+ else {
940
+ const r = (0, codex_hooks_1.mergeCodexUserHooks)(hooksBefore, opts.packageRoot);
941
+ // @implements A-SPEC-738 — a hooks file Codex would drop whole (measured: an mcp_tool `input` that
942
+ // is not a map) is not written as "wired"; nor is one next to a config Codex refuses.
943
+ const pendingConfig = changes.find((c) => c.path === codexTomlPath)?.after ?? codexTomlBefore;
944
+ const hooksVerdict = r.ok ? askCodexAbout(typeof pendingConfig === 'string' ? pendingConfig : null, r.content) : undefined;
945
+ if (!r.ok)
946
+ messages.push(`Refusing to rewrite ${hooksPath}: ${r.reason}. Fix it by hand, then re-run.`);
947
+ else if (hooksVerdict?.available && hooksVerdict.hookErrors.length > 0) {
948
+ messages.push(`Refusing to rewrite ${hooksPath}: Codex would not load the Holmes gate from it (${(0, codex_oracle_1.cappedList)(hooksVerdict.hookErrors.map((e) => e.trim()))}). Fix it by hand, then re-run.`);
949
+ }
950
+ else {
951
+ if (r.content !== hooksBefore)
952
+ changes.push({ path: hooksPath, before: hooksBefore, after: r.content });
953
+ if (codexHooksRepoint)
954
+ messages.push(`The Codex user hooks in ${hooksPath} changed hooks Codex already trusted. Codex treats them as new hooks: the gate is off in every workspace until you trust it again with /hooks.`);
955
+ // @implements A-SPEC-738 (round 2) — "wired" only if Codex LISTS the gate (measured: with
956
+ // [features] codex_hooks = false it lists nothing and init still said wired).
957
+ const listed = !hooksVerdict?.available || hooksVerdict.hooks.some((h) => h.enabled && /^pre_?tool_?use$/i.test(h.event) && /[\\/]dist[\\/]holmes[\\/]hooks[\\/]pre-tool-use\.js\b/.test(h.command ?? ''));
958
+ // @implements A-SPEC-738 (round 5) — `[hooks.state]` is keyed by the real hooks path, which a copy
959
+ // cannot show: read it as doctor does (measured: init said wired while doctor FAILed the same files).
960
+ const disabled = (0, codex_oracle_1.holmesPreToolDisabled)(typeof pendingConfig === 'string' ? pendingConfig : null, r.content, hooksPath);
961
+ codexHooksWired = !opts.dryRun && listed && !disabled;
962
+ if (hooksVerdict !== undefined && !hooksVerdict.available)
963
+ codexApproximate = hooksVerdict.reason;
964
+ // Round 6: under a layer refusal the cause is that refusal, not a hooks switch (measured message).
965
+ const layerRefused = hooksVerdict?.available === true && hooksVerdict.configError === null && hooksVerdict.otherConfigError !== undefined;
966
+ messages.push(opts.dryRun
967
+ ? `Would wire the Codex gate hooks in ${hooksPath} (dry run — nothing written). Codex runs them only after you trust them once: open codex and run /hooks.`
968
+ : disabled
969
+ ? `Codex gate hooks were written to ${hooksPath}, but the Holmes PreToolUse hook is disabled in ${codexTomlPath} ([hooks.state] enabled = false) — the gate is not active. Re-enable it in codex with /hooks.`
970
+ : listed
971
+ ? (hooksVerdict !== undefined && !hooksVerdict.available
972
+ ? `Codex gate hooks are wired in ${hooksPath} (approximate — Codex was not asked: ${hooksVerdict.reason}). Codex runs them only after you trust them once: open codex and run /hooks.`
973
+ : `Codex gate hooks are wired in ${hooksPath}. Codex runs them only after you trust them once: open codex and run /hooks.`)
974
+ : layerRefused
975
+ ? `Codex gate hooks were written to ${hooksPath}, but Codex refuses this workspace's configuration because of another layer, so it lists no hooks at all — the gate is not active until that file is fixed.`
976
+ : `Codex gate hooks were written to ${hooksPath}, but Codex lists no enabled Holmes PreToolUse hook (hooks switched off, e.g. [features] hooks = false, or an entry Codex drops) — the gate is not active.`);
977
+ if (hooksVerdict?.available && (hooksVerdict.otherHookProblems ?? []).length > 0) {
978
+ messages.push(`Note: Codex could not load another hooks source: ${(0, codex_oracle_1.cappedList)(hooksVerdict.otherHookProblems ?? [])}.`);
979
+ }
980
+ }
441
981
  }
442
982
  }
443
983
  if (opts.dryRun) {
@@ -462,8 +1002,10 @@ function runInit(opts) {
462
1002
  else {
463
1003
  // even an aliased one is not installed (it is refused before the write) — if the plan promises more than the run, that too is a lie.
464
1004
  const planned = states.filter((x) => x.state !== 'foreign' && x.state !== 'orphaned' && x.state !== 'source-unreadable' && x.state !== 'aliased');
1005
+ // A-SPEC-251.1 (round 27): planned, with no content here (their own step writes them) — `''`, not `null`, which
1006
+ // means "nothing to write" and hid every planned SKILL.md from the dry run (measured).
465
1007
  for (const p of planned)
466
- changes.push({ path: (0, playbook_skills_1.skillPathFor)(opts.target, p.name), before: null, after: null });
1008
+ changes.push({ path: (0, playbook_skills_1.skillPathFor)(opts.target, p.name), before: null, after: '' });
467
1009
  if (planned.length)
468
1010
  messages.push(`Would install/refresh ${planned.length} recovery skill(s): ${planned.map((p) => (0, playbook_skills_1.invocableSkillName)(p.name)).join(', ')}`);
469
1011
  }
@@ -472,8 +1014,14 @@ function runInit(opts) {
472
1014
  // set the real run produces (the A-SPEC-190 §9 discipline). Claude was already wired above, so its list is empty.
473
1015
  if (!opts.remove) {
474
1016
  for (const agent of opts.agents ?? []) {
475
- for (const f of (0, agents_1.agentFiles)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir, launcher: opts.mcpLauncher })) {
476
- const before = fs.existsSync(f.path) ? fs.readFileSync(f.path, 'utf8') : null;
1017
+ // A-SPEC-251.1 (round 33): a refused hooks file means this harness's gate was not wired ("left untouched" was followed
1018
+ // by "the gate is enforced" — measured).
1019
+ let hooksRefused = false;
1020
+ for (const f of (0, agents_1.agentFiles)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir, launcher: opts.mcpLauncher, mcp: opts.mcp })) {
1021
+ // @implements A-SPEC-251.1 (confirmation round 24) — a wiring file init would overwrite but cannot read (a
1022
+ // directory, a link to `/dev/zero`, EACCES — shapes a repository can carry) is refused like `.mcp.json`; it was
1023
+ // a stack trace and exit 1 (measured).
1024
+ const before = readForMerge(f.path);
477
1025
  // @implements A-SPEC-576.2 — AGENTS.md is the one file here a PERSON edits. Regeneration
478
1026
  // used to overwrite it whole: it deleted the ADR-018 parity rule a commit had just added,
479
1027
  // and said nothing. The merge runs in the COMPUTE phase so `--dry-run` predicts the same
@@ -497,11 +1045,14 @@ function runInit(opts) {
497
1045
  if (wiring) {
498
1046
  if (wiring.refused) {
499
1047
  messages.push(`${f.path}: ${wiring.refused}`);
1048
+ if (path.basename(f.path) === 'hooks.json')
1049
+ hooksRefused = true;
500
1050
  continue;
501
1051
  }
502
1052
  changes.push({ path: f.path, before, after: wiring.content });
1053
+ // A-SPEC-251.1 (round 25): other tools' entry names are clipped (a 900 KB name made a 900 KB line — measured).
503
1054
  if (wiring.preserved.length > 0)
504
- messages.push(`${f.path}: kept ${wiring.preserved.length} ${wiring.preserved.length === 1 ? 'entry that is' : 'entries that are'} not holmes-kit's — ${wiring.preserved.join(', ')}`);
1055
+ messages.push(`${f.path}: kept ${wiring.preserved.length} ${wiring.preserved.length === 1 ? 'entry that is' : 'entries that are'} not holmes-kit's — ${(0, codex_oracle_1.cappedList)(wiring.preserved)}`);
505
1056
  for (const n of wiring.notes)
506
1057
  messages.push(n);
507
1058
  continue;
@@ -512,42 +1063,122 @@ function runInit(opts) {
512
1063
  // launcher never runs (it splits on whitespace). Saying "enforced" over it was a false PASS
513
1064
  // measured on a Windows install under a spaced user directory; the warning replaces the claim.
514
1065
  const spaced = agent === 'antigravity' ? (0, agents_1.antigravityHookWarnings)(opts.packageRoot) : [];
1066
+ // @implements A-SPEC-251.1 (round 30) — Claude's own switches can turn every hook off; "enforced" is not said over
1067
+ // them (a committed `disableAllHooks` read "the gate is enforced" — measured).
1068
+ // Round 50: judged on the settings this run is about to write, not on the disk before it (an install under `a$b` read
1069
+ // "enforced" on the first init and "not confirmed" on the second — measured).
1070
+ const plannedSettings = new Map();
1071
+ for (const c of changes)
1072
+ if (/^settings(?:\.local)?\.json$/.test(path.basename(c.path)) && typeof c.after === 'string')
1073
+ plannedSettings.set(c.path, c.after);
1074
+ const switches = agent === 'claude' ? (0, claude_switches_1.claudeSwitches)(opts.target, undefined, plannedSettings) : null;
1075
+ // @implements A-SPEC-251.2 (round 46) — what doctor reads for agy before "enforced": the whole hooks file as agy's parser
1076
+ // loads it (one bad sibling drops the file), the user-level entry of the same name, and the `node` the launcher finds.
1077
+ // Round 48: as doctor orders them — evidence that no gate runs is said before any "not confirmed" reason.
1078
+ const agySwitched = agent === 'antigravity' ? (0, agents_1.agySwitches)(opts.target) : null;
1079
+ const agyNot = agent !== 'antigravity' ? null : (() => {
1080
+ if (agySwitched !== null && agySwitched.offIn !== null)
1081
+ return `the holmes-kit entry is switched off in ${(0, codex_oracle_1.clipText)(agySwitched.offIn, 400)} ("enabled": false), so the gate is NOT enforced`;
1082
+ const hj = changes.find((c) => path.basename(c.path) === 'hooks.json' && path.basename(path.dirname(c.path)) === '.agents');
1083
+ if (hj !== undefined && typeof hj.after === 'string') {
1084
+ let problem = null;
1085
+ // Round 47 (owner decision 2026-09-27): only the file init writes alone is confirmed.
1086
+ try {
1087
+ const merged = JSON.parse(hj.after);
1088
+ problem = (0, agents_1.agyHooksFileProblem)(hj.after, merged) ?? ((0, agents_1.agyCanonicalFile)(merged, hj.after) ? null : 'it holds more than the holmes-kit entry init writes');
1089
+ }
1090
+ catch {
1091
+ problem = 'the merged file is not JSON';
1092
+ }
1093
+ if (problem !== null)
1094
+ return `whether agy loads .agents/hooks.json is not confirmed — ${problem}`;
1095
+ }
1096
+ const user = agySwitched ?? { offIn: null, unconfirmed: null };
1097
+ return user.unconfirmed !== null ? `whether agy runs the gate is not confirmed — ${user.unconfirmed}` : null;
1098
+ })();
1099
+ // Round 50: doctor's own workspace predicate (the target, the repository around it, its worktrees) — judged by the target
1100
+ // alone, a `node` of the enclosing repository read "enforced" beside doctor's WARN.
1101
+ const realTargetHere = (() => { try {
1102
+ return fs.realpathSync.native(opts.target);
1103
+ }
1104
+ catch {
1105
+ return path.resolve(opts.target);
1106
+ } })();
1107
+ const nodeHit = agent === 'antigravity' || agent === 'claude' ? (0, mcp_launcher_1.gateNodeFinding)(agent === 'antigravity' ? path.join(opts.target, '.agents') : opts.target, (place) => !(0, workspace_scope_1.targetHoldsHome)(realTargetHere) && ((0, workspace_scope_1.inWorkspace)(realTargetHere, place) || (0, workspace_scope_1.isWithin)(path.resolve(opts.target), place)), agent === 'antigravity') : null;
515
1108
  if (spaced.length > 0)
516
1109
  messages.push(...spaced);
1110
+ else if (hooksRefused)
1111
+ messages.push(`${agent}: its hooks file was not changed (see above), so the gate is not wired for ${agent}.`);
1112
+ else if (switches !== null && switches.hooksOff.length > 0)
1113
+ messages.push(`claude: hooks wired, but Claude runs none of them here — switched off by ${switches.hooksOff.join(', ')}; the gate is not enforced until that setting is removed.`);
1114
+ // Round 50: for Claude too, evidence that no gate runs is said before a reason that is not confirmed.
1115
+ else if (agent === 'claude' && nodeHit !== null && nodeHit.level === 'FAIL')
1116
+ messages.push(`claude: hooks wired, but "node" where claude runs its hooks is ${(0, codex_oracle_1.clipText)(nodeHit.file, 400)}, found through that directory or a relative PATH entry, so the gate is NOT enforced.`);
1117
+ // A-SPEC-251.1 (round 31): an unreadable settings file may hold such a switch — unknown, not "enforced".
1118
+ else if (switches !== null && switches.unreadable.length > 0)
1119
+ messages.push(`claude: hooks wired; could not read ${switches.unreadable.join(', ')}, so whether a setting there switches Claude's hooks off is unknown.`);
1120
+ // A-SPEC-251.1 (round 39): a gate entry of another shape than init's, or a shell prefix — not confirmed, not "enforced".
1121
+ else if (switches !== null && switches.unconfirmed.length > 0)
1122
+ messages.push(`claude: hooks wired; whether Claude's gate blocks is not confirmed — ${switches.unconfirmed.join(', ')}.`);
1123
+ else if (agyNot !== null && /NOT enforced/.test(agyNot))
1124
+ messages.push(`antigravity: hooks wired, but ${agyNot}.`);
1125
+ else if (nodeHit !== null && nodeHit.level === 'FAIL')
1126
+ messages.push(`${agent}: hooks wired, but "node" where ${agent} runs its hooks is ${(0, codex_oracle_1.clipText)(nodeHit.file, 400)}, found through that directory or a relative PATH entry, so the gate is NOT enforced.`);
1127
+ else if (agyNot !== null)
1128
+ messages.push(`antigravity: hooks wired, but ${agyNot}.`);
1129
+ else if (nodeHit !== null)
1130
+ messages.push(`${agent}: hooks wired; ${(0, mcp_launcher_1.gateNodeUnconfirmed)(nodeHit, (s) => (0, codex_oracle_1.clipText)(s, 400))}.`);
517
1131
  else
518
1132
  messages.push(agents_1.HARNESS_ENFORCES[agent]
519
1133
  ? `${agent}: the gate is enforced (hooks wired).`
520
- : `${agent}: only tools and instructions were wired — this harness does not enforce the gate.`);
1134
+ : agent === 'codex' && codexHooksWired
1135
+ // @implements A-SPEC-727 — codex-cli 0.155+ loads the gate from the user-level hooks file wired
1136
+ // above; saying "does not enforce" beside "hooks are wired" contradicted itself.
1137
+ ? `codex: ${codexMcpWired ? 'tools and instructions' : `instructions (not the MCP tools${opts.mcp ? ' — see above' : ': --no-mcp'})`} wired${codexApproximate !== null ? ` (approximate — Codex was not asked: ${codexApproximate})` : ''}; the pre-tool gate runs from the user-level Codex hooks file once you trust it with /hooks (codex-cli 0.155+).`
1138
+ : agent === 'codex' && opts.dryRun
1139
+ // Round 8: a dry run said "does not enforce" right after "would wire the gate hooks".
1140
+ ? `codex: would wire ${opts.mcp ? 'tools, ' : ''}instructions and the user-level gate hooks (dry run — nothing written); the gate runs once you trust the hooks with /hooks.`
1141
+ : `${agent}: only ${agent === 'codex' && !codexMcpWired ? 'instructions were' : 'tools and instructions were'} wired — this harness does not enforce the gate.`);
521
1142
  // a link is placement, not content — a dry-run only says so, and only the real run creates it.
1143
+ // A-SPEC-251.1 (round 26): in the write phase — made while planning, it stayed behind a later refusal that said
1144
+ // "Nothing was written" (measured).
522
1145
  for (const link of (0, agents_1.agentLinks)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir })) {
523
1146
  if (opts.dryRun) {
524
1147
  messages.push(`Would link ${link.path} -> ${link.target} (${link.why})`);
525
1148
  continue;
526
1149
  }
527
- try {
528
- if (!fs.existsSync(link.path)) {
529
- fs.mkdirSync(path.dirname(link.path), { recursive: true });
530
- fs.symlinkSync(link.target, link.path, 'dir');
531
- messages.push(`linked ${link.path} -> ${link.target}`);
532
- }
533
- }
534
- catch (e) {
535
- // on a filesystem that cannot make symlinks (some Windows setups), state the fact and move on —
536
- // silently making a copy is exactly where drift starts.
537
- messages.push(`could not link ${link.path} (${e instanceof Error ? e.message : String(e)}) —`
538
- + ` for this harness to see the skills, link or copy ${link.target} yourself.`);
539
- }
1150
+ pendingLinks.push(link);
540
1151
  }
541
1152
  }
542
1153
  }
543
1154
  if (guidance && !changes.some(c => c.path === guidanceFile)) {
544
1155
  changes.push({ path: guidanceFile, before: guidance.before, after: guidance.after });
545
1156
  }
1157
+ // @implements A-SPEC-251.1 (round 27) — no write, removal or link goes through a link the repository carries out of the
1158
+ // target: a cloned repo's `.agents -> ../../.codex` made the default init merge Antigravity's hooks into
1159
+ // `~/.codex/hooks.json` and turn the Codex gate off everywhere (measured). A user's own (untracked) link is followed
1160
+ // as before (A-SPEC-190 §15).
1161
+ // The skills, roles and spec directories are written by their own steps: their destinations are checked too — every
1162
+ // skill's own (round 28: one representative path let a link at `.claude/skills/holmes-tdd-slice` overwrite another
1163
+ // project's SKILL.md — measured).
1164
+ const skillStates = (() => { try {
1165
+ return require('./playbook-skills').playbookSkillStates(opts.packageRoot, opts.target);
1166
+ }
1167
+ catch {
1168
+ return [];
1169
+ } })();
1170
+ const ownSteps = [...skillStates.map((x) => (0, playbook_skills_1.skillPathFor)(opts.target, x.name)), path.join(opts.target, '.claude', 'skills', 'holmes-kit', 'SKILL.md'),
1171
+ path.join(opts.target, '.ax', 'roles', 'README.md'), path.join(opts.target, opts.specsDir, SPEC_SUBDIRS[0], 'x')];
1172
+ for (const p of [...changes.filter((c) => c.after !== null).map((c) => c.path), ...removals, ...pendingLinks.map((l) => l.path), ...ownSteps]) {
1173
+ const escape = repoCarriedEscape(opts.target, p);
1174
+ if (escape !== null)
1175
+ throw new InitRefusal(`${p} would be written through ${escape.link}, a link to ${escape.to} outside the target — init writes only inside the target (a settings file linked to your own dotfiles, outside every harness configuration home, is the one exception)`, 'Remove or replace that link, then run again. Nothing was written.');
1176
+ }
546
1177
  if (!opts.dryRun) {
547
1178
  // @implements A-SPEC-190 §17/§18 (round 13) — a write we refuse to make (unreadable original)
548
1179
  // or cannot finish (rename failure) is a REFUSAL with a next action, not a raw Node stack. The
549
1180
  // files already written stay written and are reported; nothing half-written is left behind.
550
- for (const c of changes) {
1181
+ for (const [ci, c] of changes.entries()) {
551
1182
  if (c.after === null)
552
1183
  continue;
553
1184
  try {
@@ -560,28 +1191,58 @@ function runInit(opts) {
560
1191
  writeFileSafe(c.path, c.after);
561
1192
  }
562
1193
  catch (e) {
1194
+ // @implements A-SPEC-727 (round 8) — a claim about a file that was not written is withdrawn, and
1195
+ // so is every later claim that it enabled (the summary line).
1196
+ // Round 9: every file from the failed one on was never written (measured: a config.toml
1197
+ // EACCES left "hooks are wired in …/hooks.json" standing for a file that did not exist).
1198
+ const unwritten = changes.slice(ci).map((x) => x.path);
1199
+ // Round 10: the per-harness summary lines name no path, so they are withdrawn by shape.
1200
+ // A-SPEC-251.1 (round 26): "written to" is a claim too (it stayed for a config.toml that was not written).
1201
+ const claims = (m) => (unwritten.some((p) => m.includes(p)) && /wired|active|repaired|written/.test(m))
1202
+ || /pre-tool gate runs from the user-level Codex hooks file|: the gate is enforced \(hooks wired\)|: tools and instructions wired/.test(m);
1203
+ // Round 26: what was written before the failure is named (the written `.mcp.json` was not reported — measured).
1204
+ const written = changes.slice(0, ci).filter((x) => x.after !== null).map((x) => x.path);
563
1205
  return { ok: false, exitCode: 2, changes, messages: [
564
- ...messages,
1206
+ ...messages.filter((m) => !claims(m)),
565
1207
  e instanceof Error ? e.message : String(e),
1208
+ ...(written.length > 0 ? [`Written before the failure: ${written.join(', ')}`] : []),
566
1209
  'Check permissions and ownership, then run again — a file we could not read was not overwritten.',
567
1210
  ] };
568
1211
  }
569
1212
  }
570
- // @implements A-SPEC-266 (round-2 F3) — the config.toml write above is confirmed now, so it is
571
- // safe to remove the obsolete JSON. Doing it earlier risked deleting codex's only wiring and then
572
- // failing the toml write.
573
- if (codexJsonToMigrate !== null && fs.existsSync(codexJsonToMigrate)) {
1213
+ for (const link of pendingLinks) {
574
1214
  try {
575
- fs.rmSync(codexJsonToMigrate, { force: true });
576
- messages.push(`Removed obsolete ${codexJsonToMigrate} (Codex never read it — MCP wiring now lives in config.toml).`);
1215
+ // Round 30: an entry already there — a dangling link included, which `existsSync` follows — is left as it is
1216
+ // ("could not link … EEXIST" was printed over a link that resolves once the skills land — measured).
1217
+ if (!(() => { try {
1218
+ fs.lstatSync(link.path);
1219
+ return true;
1220
+ }
1221
+ catch {
1222
+ return false;
1223
+ } })()) {
1224
+ fs.mkdirSync(path.dirname(link.path), { recursive: true });
1225
+ fs.symlinkSync(link.target, link.path, 'dir');
1226
+ messages.push(`linked ${link.path} -> ${link.target}`);
1227
+ }
577
1228
  }
578
1229
  catch (e) {
579
- messages.push(`Could not remove obsolete ${codexJsonToMigrate}: ${e instanceof Error ? e.message : String(e)}`);
1230
+ // on a filesystem that cannot make symlinks (some Windows setups), state the fact and move on —
1231
+ // silently making a copy is exactly where drift starts.
1232
+ messages.push(`could not link ${link.path} (${e instanceof Error ? e.message : String(e)}) —`
1233
+ + ` for this harness to see the skills, link or copy ${link.target} yourself.`);
580
1234
  }
581
1235
  }
582
1236
  if (!opts.remove && opts.mode === 'governed') {
583
- for (const d of SPEC_SUBDIRS)
584
- fs.mkdirSync(path.join(opts.target, opts.specsDir, d), { recursive: true });
1237
+ // A-SPEC-251.1 (round 27): a file in a spec subdirectory's place is reported, not a stack trace after the writes.
1238
+ for (const d of SPEC_SUBDIRS) {
1239
+ try {
1240
+ fs.mkdirSync(path.join(opts.target, opts.specsDir, d), { recursive: true });
1241
+ }
1242
+ catch (e) {
1243
+ messages.push(`could not create ${path.join(opts.specsDir, d)}: ${(e instanceof Error ? e.message : String(e)).slice(0, 300)} — create it by hand before writing specs there.`);
1244
+ }
1245
+ }
585
1246
  }
586
1247
  // @implements A-SPEC-142
587
1248
  // The recovery layer. Measured before this existed: `npm pack` carried zero playbooks and init
@@ -629,9 +1290,20 @@ function runInit(opts) {
629
1290
  // dry run left .ax/roles/README.md behind. Introduced by REQ-153, which added the guidance
630
1291
  // without threading the flag through. The message still prints, because describing what WOULD
631
1292
  // happen is exactly what a dry run is for.
632
- if (!opts.dryRun)
633
- (0, roles_readme_1.installRolesReadme)(opts.target);
634
- messages.push('Role policy is OPTIONAL and currently off — see .ax/roles/README.md to enable it.');
1293
+ // A-SPEC-251.1 (round 25): a file at `.ax` or `.ax/roles` gave a stack trace after the other writes (measured).
1294
+ let rolesReadme = true;
1295
+ if (!opts.dryRun) {
1296
+ try {
1297
+ (0, roles_readme_1.installRolesReadme)(opts.target);
1298
+ }
1299
+ catch (e) {
1300
+ rolesReadme = false;
1301
+ messages.push(`could not write .ax/roles/README.md: ${(e instanceof Error ? e.message : String(e)).slice(0, 300)}`);
1302
+ }
1303
+ }
1304
+ // A-SPEC-251.1 (round 26): not a pointer to a file that could not be written.
1305
+ if (rolesReadme)
1306
+ messages.push('Role policy is OPTIONAL and currently off — see .ax/roles/README.md to enable it.');
635
1307
  }
636
1308
  // @implements A-SPEC-686 — the tier, said where the consumer is already reading posture.
637
1309
  // Probed 2026-09-19: init announced the guardrail mode, the harness, the skills and the role