@holmes-lab/holmes-kit 0.30.0 → 0.31.1

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 (139) hide show
  1. package/CHANGELOG.md +505 -0
  2. package/README.md +10 -1
  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.d.ts +41 -0
  9. package/dist/holmes/cli/agents.js +382 -2
  10. package/dist/holmes/cli/attest.d.ts +2 -0
  11. package/dist/holmes/cli/attest.js +66 -15
  12. package/dist/holmes/cli/ci-gate.js +16 -1
  13. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  14. package/dist/holmes/cli/claude-switches.js +967 -0
  15. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  16. package/dist/holmes/cli/codex-hooks.js +802 -0
  17. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  18. package/dist/holmes/cli/codex-oracle.js +1245 -0
  19. package/dist/holmes/cli/codex-toml.d.ts +35 -0
  20. package/dist/holmes/cli/codex-toml.js +321 -52
  21. package/dist/holmes/cli/doctor.d.ts +98 -8
  22. package/dist/holmes/cli/doctor.js +1328 -94
  23. package/dist/holmes/cli/index.js +26 -11
  24. package/dist/holmes/cli/init.d.ts +11 -0
  25. package/dist/holmes/cli/init.js +736 -44
  26. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  27. package/dist/holmes/cli/mcp-launcher.js +189 -6
  28. package/dist/holmes/cli/mcp-version.js +13 -2
  29. package/dist/holmes/cli/settings-merge.js +8 -2
  30. package/dist/holmes/cli/upgrade.d.ts +18 -0
  31. package/dist/holmes/cli/upgrade.js +129 -24
  32. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  33. package/dist/holmes/cli/workspace-scope.js +375 -0
  34. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  35. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  36. package/dist/holmes/cpg/cycle-detect.js +2 -1
  37. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  38. package/dist/holmes/cpg/required-calls.js +8 -1
  39. package/dist/holmes/governance/constitution-debt.js +3 -2
  40. package/dist/holmes/governance/constitution.js +15 -3
  41. package/dist/holmes/governance/provenance-chain.js +3 -2
  42. package/dist/holmes/governance/push-gate-runner.js +4 -3
  43. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  44. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  45. package/dist/holmes/guardrail/linear-match.js +256 -0
  46. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  47. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  48. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  49. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  50. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  51. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  52. package/dist/holmes/guardrail/shell-words.js +1720 -0
  53. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  54. package/dist/holmes/guardrail/write-target.js +2379 -87
  55. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  56. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  57. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  58. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  59. package/dist/holmes/hooks/rtm-refresh-child.js +3 -1
  60. package/dist/holmes/hooks/rtm-refresh.js +8 -4
  61. package/dist/holmes/hooks/session-start.d.ts +10 -0
  62. package/dist/holmes/hooks/session-start.js +31 -7
  63. package/dist/holmes/hooks/stop.d.ts +2 -1
  64. package/dist/holmes/hooks/stop.js +197 -91
  65. package/dist/holmes/mcp/approval-commit.d.ts +5 -6
  66. package/dist/holmes/mcp/approval-commit.js +18 -2
  67. package/dist/holmes/mcp/elicit-approval.js +4 -2
  68. package/dist/holmes/mcp/handlers/graph-operations.js +3 -2
  69. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  70. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  71. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  72. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  73. package/dist/holmes/mcp/handlers/requirement-triage.js +5 -3
  74. package/dist/holmes/mcp/handlers/review-evidence.js +8 -2
  75. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +11 -0
  76. package/dist/holmes/mcp/handlers/slice-orchestration.js +115 -16
  77. package/dist/holmes/mcp/handlers/spec-approval.d.ts +9 -0
  78. package/dist/holmes/mcp/handlers/spec-approval.js +110 -17
  79. package/dist/holmes/mcp/handlers/spec-authoring.js +17 -2
  80. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  81. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  82. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  83. package/dist/holmes/mcp/handlers.d.ts +81 -9
  84. package/dist/holmes/mcp/handlers.js +70 -23
  85. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  86. package/dist/holmes/mcp/harness-attestation.js +179 -0
  87. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -0
  88. package/dist/holmes/mcp/requirement-triage-evidence.js +160 -4
  89. package/dist/holmes/mcp/server.js +20 -1
  90. package/dist/holmes/mcp/tool-schemas.js +26 -9
  91. package/dist/holmes/mcp/validate-args.js +12 -0
  92. package/dist/holmes/project/bounded-io.d.ts +102 -0
  93. package/dist/holmes/project/bounded-io.js +212 -0
  94. package/dist/holmes/project/change-source.js +3 -1
  95. package/dist/holmes/project/ci-runs.js +3 -2
  96. package/dist/holmes/project/ignore.d.ts +31 -2
  97. package/dist/holmes/project/ignore.js +409 -50
  98. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  99. package/dist/holmes/project/regular-file-guard.js +149 -0
  100. package/dist/holmes/project/root.js +12 -3
  101. package/dist/holmes/reverse/anchor.js +4 -3
  102. package/dist/holmes/reverse/scan.js +6 -2
  103. package/dist/holmes/review/commit-text.js +3 -2
  104. package/dist/holmes/review/condition-hunk-replay.js +3 -2
  105. package/dist/holmes/review/failed-test-names.js +13 -10
  106. package/dist/holmes/review/findings.js +3 -1
  107. package/dist/holmes/review/kills-check.js +6 -1
  108. package/dist/holmes/review/point-in-time-replay.js +5 -4
  109. package/dist/holmes/review/replay-corpus.js +5 -4
  110. package/dist/holmes/review/run-replay.js +3 -2
  111. package/dist/holmes/review/temporal-prior.js +3 -2
  112. package/dist/holmes/review/test-evidence.js +3 -2
  113. package/dist/holmes/review/test-outcomes.js +3 -2
  114. package/dist/holmes/review/test-runner.d.ts +6 -0
  115. package/dist/holmes/review/test-runner.js +36 -15
  116. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  117. package/dist/holmes/rtm/anchor-ids.js +42 -2
  118. package/dist/holmes/rtm/file-anchors.js +4 -1
  119. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  120. package/dist/holmes/rtm/git-changes.js +3 -1
  121. package/dist/holmes/rtm/graph-store.js +3 -2
  122. package/dist/holmes/rtm/test-scope.js +9 -4
  123. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  124. package/dist/holmes/spec/compat-impact.js +682 -11
  125. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  126. package/dist/holmes/spec/entity-integration.js +3 -2
  127. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  128. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  129. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  130. package/dist/holmes/spec/renumber.js +25 -10
  131. package/dist/holmes/spec/spec-parser.js +9 -3
  132. package/dist/holmes/spec/yaml-scalar.js +2 -2
  133. package/dist/holmes/update/refresh.d.ts +5 -0
  134. package/dist/holmes/update/refresh.js +26 -1
  135. package/dist/holmes/update/update-notice.d.ts +6 -0
  136. package/dist/holmes/update/update-notice.js +18 -1
  137. package/dist/holmes/update/upgrade-plan.d.ts +28 -0
  138. package/dist/holmes/update/upgrade-plan.js +31 -2
  139. package/package.json +11 -4
@@ -36,12 +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-724, A-SPEC-721
39
+ // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738
40
40
  // @implements A-SPEC-709
41
41
  // @implements A-SPEC-340
42
42
  // @implements A-SPEC-100.2
43
43
  const fs = __importStar(require("node:fs"));
44
44
  const path = __importStar(require("node:path"));
45
+ const os = __importStar(require("node:os"));
45
46
  const settings_merge_1 = require("./settings-merge");
46
47
  const gitignore_merge_1 = require("./gitignore-merge");
47
48
  const settings_merge_2 = require("./settings-merge");
@@ -50,11 +51,16 @@ const agents_guidance_plan_1 = require("./agents-guidance-plan");
50
51
  const agents_guidance_file_1 = require("./agents-guidance-file");
51
52
  const agents_1 = require("./agents");
52
53
  const roles_readme_1 = require("./roles-readme");
54
+ const workspace_scope_1 = require("./workspace-scope");
53
55
  const mcp_launcher_1 = require("./mcp-launcher");
54
56
  const codex_toml_1 = require("./codex-toml");
57
+ const codex_hooks_1 = require("./codex-hooks");
58
+ const codex_oracle_1 = require("./codex-oracle");
55
59
  const pre_tool_use_1 = require("../hooks/pre-tool-use");
56
60
  const governed_precondition_1 = require("./governed-precondition");
57
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");
58
64
  /**
59
65
  * `holmes-kit init` — wire holmes-kit into a TARGET project (the I/O half; all merge logic is pure
60
66
  * and lives in settings-merge.ts / gitignore-merge.ts).
@@ -123,8 +129,35 @@ function readJson(file) {
123
129
  const missing = e.code === 'ENOENT';
124
130
  return { value: undefined, raw: null, parseError: false, unreadable: !missing };
125
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 };
126
159
  try {
127
- return { value: JSON.parse(raw), raw, parseError: false, unreadable: false };
160
+ return { value: JSON.parse(text), raw, parseError: false, unreadable: false };
128
161
  }
129
162
  catch {
130
163
  return { value: undefined, raw, parseError: true, unreadable: false };
@@ -208,14 +241,217 @@ function writeFileSafe(file, content) {
208
241
  }
209
242
  const settingsPathOf = (target, which) => path.join(target, '.claude', which === 'local' ? 'settings.local.json' : 'settings.json');
210
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.';
211
294
  /** Does the target already carry holmes wiring? (idempotency + self-disarm guard) */
212
295
  function alreadyWired(settings) {
213
- 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
+ }
214
438
  }
215
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) {
216
451
  const messages = [];
217
452
  const changes = [];
218
453
  const removals = [];
454
+ const pendingLinks = [];
219
455
  const guidanceFile = path.join(opts.target, 'AGENTS.md');
220
456
  let guidance;
221
457
  if (!opts.remove) {
@@ -242,7 +478,11 @@ function runInit(opts) {
242
478
  'This package ships a compiled dist/ — if you are working from the repository run `npm run build`, and if from an install, reinstall.',
243
479
  ] };
244
480
  }
245
- 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);
246
486
  if (s.parseError) {
247
487
  return { ok: false, exitCode: 2, changes, messages: [
248
488
  `${settingsPath} is not valid JSON (comments/JSONC are not supported here).`,
@@ -258,20 +498,66 @@ function runInit(opts) {
258
498
  // and both the guard and the approval requirement excluded `--remove`, which is the most complete
259
499
  // way to take governance off. A session must not be able to unwire the gate that governs it,
260
500
  // whichever flag it reaches for. Wiring is asked of BOTH settings files.
261
- 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);
262
509
  if (!opts.remove && wiredAnywhere && !opts.force && !opts.allowAdditive) {
263
510
  return { ok: false, exitCode: 2, changes, messages: [
264
511
  'This target already has holmes-kit wiring. Re-run with --force to change it.',
265
512
  ] };
266
513
  }
267
- 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)))
268
552
  && !(0, risk_gate_1.approvalCovers)(opts.approval, { kind: 'governance-wiring', target: opts.target }, new Date().toISOString())) {
269
553
  // covers, not merely well-formed (round-3): an expired or elsewhere-scoped token re-wired
270
554
  // governance — the exact master-key behaviour A-SPEC-133's narrowing exists to end.
271
555
  return { ok: false, exitCode: 2, changes, messages: [
272
556
  opts.remove
273
557
  ? 'Stripping governance wiring is also changing the wiring — an out-of-band approval is required (self-disarm prevention).'
274
- : '--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.',
275
561
  `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "governance-wiring") and re-run.`,
276
562
  ] };
277
563
  }
@@ -287,11 +573,28 @@ function runInit(opts) {
287
573
  `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "autonomy-grant") and re-run with --autonomy.`,
288
574
  ] };
289
575
  }
290
- 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
+ }
291
594
  if (m.parseError) {
292
595
  return { ok: false, exitCode: 2, changes, messages: [`${mcpPath} is not valid JSON — refusing to touch it.`] };
293
596
  }
294
- const gitignoreBefore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
597
+ const gitignoreBefore = readForMerge(gitignorePath) ?? '';
295
598
  if (opts.remove) {
296
599
  let settings = (0, settings_merge_1.removeHooks)(s.value);
297
600
  settings = (0, settings_merge_1.disableMcpServer)(settings, exports.SERVER_NAME);
@@ -305,7 +608,7 @@ function runInit(opts) {
305
608
  // @implements A-SPEC-256.1 — remove is install's mirror: the union-attributes block this init
306
609
  // wrote leaves with it (round-1 adversarial finding: it stayed behind forever).
307
610
  const rmAttrsPath = path.join(opts.target, '.gitattributes');
308
- const rmAttrsBefore = fs.existsSync(rmAttrsPath) ? fs.readFileSync(rmAttrsPath, 'utf8') : '';
611
+ const rmAttrsBefore = readForMerge(rmAttrsPath) ?? '';
309
612
  if ((0, gitignore_merge_1.hasGitignoreBlock)(rmAttrsBefore)) {
310
613
  changes.push({ path: rmAttrsPath, before: rmAttrsBefore, after: (0, gitignore_merge_1.removeGitignoreBlock)(rmAttrsBefore) });
311
614
  }
@@ -355,14 +658,20 @@ function runInit(opts) {
355
658
  const mcpEntry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
356
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' });
357
660
  }
358
- 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 });
359
668
  const gitignoreAfter = (0, gitignore_merge_1.mergeGitignore)(gitignoreBefore);
360
669
  if (gitignoreAfter !== gitignoreBefore)
361
670
  changes.push({ path: gitignorePath, before: gitignoreBefore || null, after: gitignoreAfter });
362
671
  // @implements A-SPEC-256.1 — the append-only files merge with union in every governed project,
363
672
  // not only this repository: a colleague's merge losing ledger lines is the disease.
364
673
  const gitattributesPath = path.join(opts.target, '.gitattributes');
365
- const gitattributesBefore = fs.existsSync(gitattributesPath) ? fs.readFileSync(gitattributesPath, 'utf8') : '';
674
+ const gitattributesBefore = readForMerge(gitattributesPath) ?? '';
366
675
  const gitattributesAfter = (0, gitignore_merge_1.mergeGitattributes)(gitattributesBefore);
367
676
  if (gitattributesAfter !== gitattributesBefore)
368
677
  changes.push({ path: gitattributesPath, before: gitattributesBefore || null, after: gitattributesAfter });
@@ -381,25 +690,93 @@ function runInit(opts) {
381
690
  // The active file is a user-level resource, not a target artifact: merely removing Claude/AGY
382
691
  // wiring must not probe or mutate it. Explicit `--agent codex` is the authority for both merge
383
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;
384
700
  if ((opts.agents ?? []).includes('codex')) {
385
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
+ };
386
743
  // An active config we cannot read is NOT touched. A legacy project artifact is deliberately
387
744
  // preserved: deleting a file Codex does not load would add surprise without restoring wiring.
388
745
  let codexTomlBefore = null;
389
746
  let codexUnreadable = false;
747
+ let codexUndecodable = null;
390
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).
391
751
  try {
392
- 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
+ }
393
759
  }
394
760
  catch {
395
761
  codexUnreadable = true;
396
762
  }
397
763
  }
398
764
  const wantsCodex = !codexUnreadable;
399
- if (codexUnreadable)
400
- messages.push(`Refusing to touch ${codexTomlPath} — it is not a readable file. Fix or remove it, then re-run.`);
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
+ }
401
772
  if (opts.remove) {
402
- 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) {
403
780
  const after = (0, codex_toml_1.removeCodexToml)(codexTomlBefore);
404
781
  // @implements A-SPEC-721 — the active entry is user-level: say so before anyone is surprised.
405
782
  if (after !== codexTomlBefore)
@@ -423,13 +800,184 @@ function runInit(opts) {
423
800
  // another spelling would declare it twice; Codex would then reject the whole shared config.
424
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.`);
425
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.`);
808
+ }
426
809
  else if (wantsCodex && opts.mcp) {
810
+ const repairing = codexTomlBefore !== null && codexLoadProblem(codexTomlBefore) !== null;
427
811
  const mcpBin = path.join(opts.packageRoot, 'bin', 'holmes-mcp.js');
428
812
  const entry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
429
813
  const after = (0, codex_toml_1.mergeCodexToml)(codexTomlBefore, (0, codex_toml_1.codexMcpBlock)(entry, opts.specsDir));
430
- if (after !== codexTomlBefore)
431
- changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
432
- messages.push(`Codex MCP wiring is active from ${codexTomlPath}; restart Codex in the target workspace.`);
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
+ }
433
981
  }
434
982
  }
435
983
  if (opts.dryRun) {
@@ -454,8 +1002,10 @@ function runInit(opts) {
454
1002
  else {
455
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.
456
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).
457
1007
  for (const p of planned)
458
- 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: '' });
459
1009
  if (planned.length)
460
1010
  messages.push(`Would install/refresh ${planned.length} recovery skill(s): ${planned.map((p) => (0, playbook_skills_1.invocableSkillName)(p.name)).join(', ')}`);
461
1011
  }
@@ -464,8 +1014,14 @@ function runInit(opts) {
464
1014
  // set the real run produces (the A-SPEC-190 §9 discipline). Claude was already wired above, so its list is empty.
465
1015
  if (!opts.remove) {
466
1016
  for (const agent of opts.agents ?? []) {
467
- for (const f of (0, agents_1.agentFiles)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir, launcher: opts.mcpLauncher })) {
468
- 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);
469
1025
  // @implements A-SPEC-576.2 — AGENTS.md is the one file here a PERSON edits. Regeneration
470
1026
  // used to overwrite it whole: it deleted the ADR-018 parity rule a commit had just added,
471
1027
  // and said nothing. The merge runs in the COMPUTE phase so `--dry-run` predicts the same
@@ -489,11 +1045,14 @@ function runInit(opts) {
489
1045
  if (wiring) {
490
1046
  if (wiring.refused) {
491
1047
  messages.push(`${f.path}: ${wiring.refused}`);
1048
+ if (path.basename(f.path) === 'hooks.json')
1049
+ hooksRefused = true;
492
1050
  continue;
493
1051
  }
494
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).
495
1054
  if (wiring.preserved.length > 0)
496
- 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)}`);
497
1056
  for (const n of wiring.notes)
498
1057
  messages.push(n);
499
1058
  continue;
@@ -504,42 +1063,122 @@ function runInit(opts) {
504
1063
  // launcher never runs (it splits on whitespace). Saying "enforced" over it was a false PASS
505
1064
  // measured on a Windows install under a spaced user directory; the warning replaces the claim.
506
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;
507
1108
  if (spaced.length > 0)
508
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))}.`);
509
1131
  else
510
1132
  messages.push(agents_1.HARNESS_ENFORCES[agent]
511
1133
  ? `${agent}: the gate is enforced (hooks wired).`
512
- : `${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.`);
513
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).
514
1145
  for (const link of (0, agents_1.agentLinks)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir })) {
515
1146
  if (opts.dryRun) {
516
1147
  messages.push(`Would link ${link.path} -> ${link.target} (${link.why})`);
517
1148
  continue;
518
1149
  }
519
- try {
520
- if (!fs.existsSync(link.path)) {
521
- fs.mkdirSync(path.dirname(link.path), { recursive: true });
522
- fs.symlinkSync(link.target, link.path, 'dir');
523
- messages.push(`linked ${link.path} -> ${link.target}`);
524
- }
525
- }
526
- catch (e) {
527
- // on a filesystem that cannot make symlinks (some Windows setups), state the fact and move on —
528
- // silently making a copy is exactly where drift starts.
529
- messages.push(`could not link ${link.path} (${e instanceof Error ? e.message : String(e)}) —`
530
- + ` for this harness to see the skills, link or copy ${link.target} yourself.`);
531
- }
1150
+ pendingLinks.push(link);
532
1151
  }
533
1152
  }
534
1153
  }
535
1154
  if (guidance && !changes.some(c => c.path === guidanceFile)) {
536
1155
  changes.push({ path: guidanceFile, before: guidance.before, after: guidance.after });
537
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
+ }
538
1177
  if (!opts.dryRun) {
539
1178
  // @implements A-SPEC-190 §17/§18 (round 13) — a write we refuse to make (unreadable original)
540
1179
  // or cannot finish (rename failure) is a REFUSAL with a next action, not a raw Node stack. The
541
1180
  // files already written stay written and are reported; nothing half-written is left behind.
542
- for (const c of changes) {
1181
+ for (const [ci, c] of changes.entries()) {
543
1182
  if (c.after === null)
544
1183
  continue;
545
1184
  try {
@@ -552,16 +1191,58 @@ function runInit(opts) {
552
1191
  writeFileSafe(c.path, c.after);
553
1192
  }
554
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);
555
1205
  return { ok: false, exitCode: 2, changes, messages: [
556
- ...messages,
1206
+ ...messages.filter((m) => !claims(m)),
557
1207
  e instanceof Error ? e.message : String(e),
1208
+ ...(written.length > 0 ? [`Written before the failure: ${written.join(', ')}`] : []),
558
1209
  'Check permissions and ownership, then run again — a file we could not read was not overwritten.',
559
1210
  ] };
560
1211
  }
561
1212
  }
1213
+ for (const link of pendingLinks) {
1214
+ try {
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
+ }
1228
+ }
1229
+ catch (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.`);
1234
+ }
1235
+ }
562
1236
  if (!opts.remove && opts.mode === 'governed') {
563
- for (const d of SPEC_SUBDIRS)
564
- 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
+ }
565
1246
  }
566
1247
  // @implements A-SPEC-142
567
1248
  // The recovery layer. Measured before this existed: `npm pack` carried zero playbooks and init
@@ -609,9 +1290,20 @@ function runInit(opts) {
609
1290
  // dry run left .ax/roles/README.md behind. Introduced by REQ-153, which added the guidance
610
1291
  // without threading the flag through. The message still prints, because describing what WOULD
611
1292
  // happen is exactly what a dry run is for.
612
- if (!opts.dryRun)
613
- (0, roles_readme_1.installRolesReadme)(opts.target);
614
- 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.');
615
1307
  }
616
1308
  // @implements A-SPEC-686 — the tier, said where the consumer is already reading posture.
617
1309
  // Probed 2026-09-19: init announced the guardrail mode, the harness, the skills and the role