@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
@@ -1,4 +1,38 @@
1
1
  import { McpServerEntry } from './mcp-launcher';
2
+ type TomlTable = Record<string, unknown>;
3
+ /** The parsed document, or the parser's reason for refusing it (Codex refuses such a file whole). */
4
+ export declare function parseCodexConfig(raw: string): {
5
+ ok: true;
6
+ doc: TomlTable;
7
+ } | {
8
+ ok: false;
9
+ reason: string;
10
+ };
11
+ /** @implements A-SPEC-727 (round 10) — whether the holmes-kit table sets `enabled = false`. */
12
+ export declare function codexHolmesDisabled(raw: string): boolean;
13
+ /** Why Codex cannot load this config, or null when it parses. */
14
+ /**
15
+ * @implements A-SPEC-731 (round 6) — bytes → text only when they are valid UTF-8: Codex refuses the
16
+ * whole file otherwise, and a lenient read rewrote the bytes (and the backup) with U+FFFD (measured).
17
+ */
18
+ export declare function readCodexConfigBytes(bytes: Uint8Array): {
19
+ ok: true;
20
+ text: string;
21
+ } | {
22
+ ok: false;
23
+ reason: string;
24
+ };
25
+ export declare function codexConfigLoadProblem(raw: string): string | null;
26
+ /**
27
+ * @implements A-SPEC-731 (round 4) — the write a caller is about to make, judged by the parser: null
28
+ * when `after` loads and its holmes-kit entry is exactly `want` (or absent when `want` is null), else
29
+ * the reason to write nothing.
30
+ */
31
+ export declare function codexConfigWriteProblem(after: string, want: {
32
+ command: string;
33
+ args: string[];
34
+ env?: Record<string, string>;
35
+ } | null): string | null;
2
36
  /** The one table holmes-kit owns in a Codex config.toml. */
3
37
  export declare const CODEX_TABLE = "mcp_servers.holmes-kit";
4
38
  /**
@@ -56,3 +90,4 @@ export declare function invalidTomlEscape(raw: string): {
56
90
  escape: string;
57
91
  line: number;
58
92
  } | null;
93
+ export {};
@@ -34,6 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.CODEX_TABLE = void 0;
37
+ exports.parseCodexConfig = parseCodexConfig;
38
+ exports.codexHolmesDisabled = codexHolmesDisabled;
39
+ exports.readCodexConfigBytes = readCodexConfigBytes;
40
+ exports.codexConfigLoadProblem = codexConfigLoadProblem;
41
+ exports.codexConfigWriteProblem = codexConfigWriteProblem;
37
42
  exports.defaultCodexConfigPath = defaultCodexConfigPath;
38
43
  exports.codexMcpBlock = codexMcpBlock;
39
44
  exports.mergeCodexToml = mergeCodexToml;
@@ -44,7 +49,7 @@ exports.mentionsHolmes = mentionsHolmes;
44
49
  exports.unownedHolmesShape = unownedHolmesShape;
45
50
  exports.readCodexFixedSpecs = readCodexFixedSpecs;
46
51
  exports.invalidTomlEscape = invalidTomlEscape;
47
- // @implements A-SPEC-721
52
+ // @implements A-SPEC-733, A-SPEC-731, A-SPEC-721
48
53
  // @implements A-SPEC-266
49
54
  // Codex reads default MCP servers from `$CODEX_HOME/config.toml` (normally
50
55
  // `~/.codex/config.toml`), not from a repository-local `.codex/config.toml`. This module owns only
@@ -52,6 +57,252 @@ exports.invalidTomlEscape = invalidTomlEscape;
52
57
  // has no HOLMES_SPECS binding: it resolves its governed workspace from the active Codex session cwd.
53
58
  const path = __importStar(require("node:path"));
54
59
  const os = __importStar(require("node:os"));
60
+ // @implements A-SPEC-731 (round 4) — READ with a real TOML 1.0 parser (owner decision 2026-09-24): three
61
+ // review rounds kept finding the hand scanner reading values out of strings and subtables. Writes stay
62
+ // textual (only our region changes) and are re-parsed before they happen.
63
+ const smol_toml_1 = require("smol-toml");
64
+ const linear_match_1 = require("../guardrail/linear-match");
65
+ const isTable = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
66
+ /** The parsed document, or the parser's reason for refusing it (Codex refuses such a file whole). */
67
+ function parseCodexConfig(raw) {
68
+ // CRLF reads as LF inside multi-line strings, as tomllib reads it (TOML lets a parser normalize).
69
+ // Round 5: integers beyond 2^53 load as BigInt (Codex loads them); impossible dates are refused,
70
+ // which the parser alone would roll over (`1979-02-30` → March 2).
71
+ if (raw.startsWith('\uFEFF\uFEFF'))
72
+ return { ok: false, reason: 'the file starts with two byte-order marks (Codex: invalid unquoted key)' };
73
+ const text = raw.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
74
+ let doc;
75
+ try {
76
+ doc = (0, smol_toml_1.parse)(text, { integersAsBigInt: 'asNeeded' });
77
+ }
78
+ catch (e) {
79
+ return { ok: false, reason: String(e instanceof Error ? e.message : e).split('\n')[0].slice(0, 300) };
80
+ }
81
+ const badDate = impossibleDateLiteral(text);
82
+ if (badDate !== null)
83
+ return { ok: false, reason: `invalid date ${badDate} (that day does not exist in its month)` };
84
+ return { ok: true, doc };
85
+ }
86
+ const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
87
+ /** The first date literal OUTSIDE strings and comments whose day does not exist, or null (linear). */
88
+ function impossibleDateLiteral(text) {
89
+ let i = 0;
90
+ while (i < text.length) {
91
+ const c = text[i];
92
+ if (c === '#') {
93
+ const nl = text.indexOf('\n', i);
94
+ i = nl < 0 ? text.length : nl;
95
+ continue;
96
+ }
97
+ if (c === '"' || c === "'") {
98
+ const triple = text.startsWith(c.repeat(3), i);
99
+ const delim = triple ? c.repeat(3) : c;
100
+ let j = i + delim.length;
101
+ while (j < text.length && !text.startsWith(delim, j) && !(!triple && text[j] === '\n')) {
102
+ if (c === '"' && text[j] === '\\')
103
+ j++;
104
+ j++;
105
+ }
106
+ i = j + delim.length;
107
+ continue;
108
+ }
109
+ if (/[0-9]/.test(c) && (i === 0 || !/[\w.-]/.test(text[i - 1]))) {
110
+ const m = /^(\d{4})-(\d{2})-(\d{2})(?![\d-])/.exec(text.slice(i, i + 11));
111
+ if (m) {
112
+ // Round 7: a date-shaped KEY (`2023-02-30 = 1`, `[2023-02-30]`, `2023-02-30.a`) is a key.
113
+ const after = /^[ \t]*(.?)/.exec(text.slice(i + 10, i + 40))?.[1] ?? '';
114
+ const lineStart = text.lastIndexOf('\n', i) + 1;
115
+ const beforeOnLine = text.slice(lineStart, i);
116
+ if (after === '=' || after === '.' || (after === ']' && !beforeOnLine.includes('=')) || (/[{,][ \t]*$/.test(beforeOnLine) && after === '=')) {
117
+ i += 10;
118
+ continue;
119
+ }
120
+ const y = +m[1], mo = +m[2], d = +m[3];
121
+ const leap = (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
122
+ const max = mo >= 1 && mo <= 12 ? (mo === 2 && leap ? 29 : DAYS[mo - 1]) : 0;
123
+ if (d < 1 || d > max)
124
+ return m[0];
125
+ i += 10;
126
+ continue;
127
+ }
128
+ }
129
+ i++;
130
+ }
131
+ return null;
132
+ }
133
+ /** @implements A-SPEC-727 (round 10) — whether the holmes-kit table sets `enabled = false`. */
134
+ function codexHolmesDisabled(raw) {
135
+ const p = parseCodexConfig(raw);
136
+ if (!p.ok)
137
+ return false;
138
+ const entry = holmesEntryOf(p.doc);
139
+ return entry !== null && entry.enabled === false;
140
+ }
141
+ /** `mcp_servers["holmes-kit"]` of a parsed document, when it is a table. */
142
+ function holmesEntryOf(doc) {
143
+ const servers = Object.prototype.hasOwnProperty.call(doc, 'mcp_servers') ? doc.mcp_servers : undefined;
144
+ if (!isTable(servers) || !Object.prototype.hasOwnProperty.call(servers, 'holmes-kit'))
145
+ return null;
146
+ const entry = servers['holmes-kit'];
147
+ return isTable(entry) ? entry : null;
148
+ }
149
+ /** Why Codex cannot load this config, or null when it parses. */
150
+ /**
151
+ * @implements A-SPEC-731 (round 6) — bytes → text only when they are valid UTF-8: Codex refuses the
152
+ * whole file otherwise, and a lenient read rewrote the bytes (and the backup) with U+FFFD (measured).
153
+ */
154
+ function readCodexConfigBytes(bytes) {
155
+ // Round 7: keep the BOM in the text (parseCodexConfig strips exactly one; two is a load problem).
156
+ try {
157
+ return { ok: true, text: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes) };
158
+ }
159
+ catch {
160
+ return { ok: false, reason: 'the file is not valid UTF-8 (Codex refuses it whole)' };
161
+ }
162
+ }
163
+ const I64_MIN = -(BigInt(2) ** BigInt(63));
164
+ const I64_MAX = BigInt(2) ** BigInt(63) - BigInt(1);
165
+ const ARRAY_DEPTH_LIMIT = 80;
166
+ const isStr = (v) => typeof v === 'string';
167
+ const isStrArray = (v) => Array.isArray(v) && v.every(isStr);
168
+ const isStrTable = (v) => isTable(v) && Object.values(v).every(isStr);
169
+ const isEnvVar = (v) => isStr(v) || (isTable(v) && isStr(v.name)
170
+ && Object.keys(v).every((k) => k === 'name' || k === 'source') && (v.source === undefined || v.source === 'local' || v.source === 'remote'));
171
+ const isNonNegNumber = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0) || (typeof v === 'bigint' && v >= BigInt(0));
172
+ /** Values Codex refuses anywhere: integers outside i64, arrays nested past its recursion limit. */
173
+ function valueProblem(v, where, depth = 0) {
174
+ if (typeof v === 'bigint' && (v < I64_MIN || v > I64_MAX))
175
+ return `${where} is an integer outside the signed 64-bit range`;
176
+ // Round 7 (measured): Codex's recursion limit counts tables (inline or by header/dotted key) as well
177
+ // as arrays.
178
+ if (Array.isArray(v) || isTable(v)) {
179
+ if (depth + 1 > ARRAY_DEPTH_LIMIT)
180
+ return `${where} nests tables/arrays deeper than Codex reads (${ARRAY_DEPTH_LIMIT})`;
181
+ const entries = Array.isArray(v) ? v.map((x, i) => [`[${i}]`, x]) : Object.entries(v).map(([k, x]) => [`.${k}`, x]);
182
+ for (const [k, x] of entries) {
183
+ const p = valueProblem(x, `${where}${k}`, depth + 1);
184
+ if (p)
185
+ return p;
186
+ }
187
+ }
188
+ return null;
189
+ }
190
+ /** One `[mcp_servers.<name>]` table as Codex deserializes it (measured refusals only). */
191
+ function serverProblem(name, t) {
192
+ const at = `mcp_servers.${name}`;
193
+ if (!isTable(t))
194
+ return `${at} is not a table (Codex expects one server table)`;
195
+ const hasCommand = t.command !== undefined, hasUrl = t.url !== undefined;
196
+ if (!hasCommand && !hasUrl)
197
+ return `${at} has neither command nor url (Codex: invalid transport)`;
198
+ if (hasCommand && hasUrl)
199
+ return `${at} has both command and url (Codex: invalid transport)`;
200
+ if (hasCommand && !isStr(t.command))
201
+ return `${at}.command is not a string`;
202
+ if (hasUrl && !isStr(t.url))
203
+ return `${at}.url is not a string`;
204
+ if (t.args !== undefined && !isStrArray(t.args))
205
+ return `${at}.args is not an array of strings`;
206
+ // Round 7 (measured): an env_vars entry is a string or { name, source = "local"|"remote" }.
207
+ if (t.env_vars !== undefined && !(Array.isArray(t.env_vars) && t.env_vars.every(isEnvVar)))
208
+ return `${at}.env_vars entries are not strings or { name, source } tables`;
209
+ if (t.env !== undefined && !isStrTable(t.env))
210
+ return `${at}.env is not a table of strings`;
211
+ if (t.enabled !== undefined && typeof t.enabled !== 'boolean')
212
+ return `${at}.enabled is not a boolean`;
213
+ if (t.required !== undefined && typeof t.required !== 'boolean')
214
+ return `${at}.required is not a boolean`;
215
+ if (t.cwd !== undefined && !isStr(t.cwd))
216
+ return `${at}.cwd is not a string`;
217
+ for (const k of ['startup_timeout_sec', 'tool_timeout_sec']) {
218
+ if (t[k] !== undefined && !(isNonNegNumber(t[k]) && Number(t[k]) < 1e19))
219
+ return `${at}.${k} is not a non-negative number below 1e19`;
220
+ }
221
+ if (t.startup_timeout_ms !== undefined && !((typeof t.startup_timeout_ms === 'number' && Number.isInteger(t.startup_timeout_ms) && t.startup_timeout_ms >= 0) || (typeof t.startup_timeout_ms === 'bigint' && t.startup_timeout_ms >= BigInt(0)))) {
222
+ return `${at}.startup_timeout_ms is not a non-negative integer`;
223
+ }
224
+ for (const k of ['enabled_tools', 'disabled_tools'])
225
+ if (t[k] !== undefined && !isStrArray(t[k]))
226
+ return `${at}.${k} is not an array of strings`;
227
+ for (const k of ['http_headers', 'env_http_headers'])
228
+ if (t[k] !== undefined && !isStrTable(t[k]))
229
+ return `${at}.${k} is not a table of strings`;
230
+ for (const k of ['bearer_token_env_var', 'environment_id'])
231
+ if (t[k] !== undefined && !isStr(t[k]))
232
+ return `${at}.${k} is not a string`;
233
+ // Transport-specific fields (measured: "… is not supported for streamable_http / stdio").
234
+ const notFor = hasUrl ? ['args', 'env', 'env_vars', 'cwd', 'bearer_token'] : ['http_headers', 'env_http_headers', 'bearer_token_env_var', 'bearer_token', 'oauth_resource'];
235
+ for (const k of notFor)
236
+ if (t[k] !== undefined)
237
+ return `${at}.${k} is not supported for ${hasUrl ? 'a url (streamable_http)' : 'a command (stdio)'} server`;
238
+ return null;
239
+ }
240
+ function codexConfigLoadProblem(raw) {
241
+ const p = parseCodexConfig(raw);
242
+ if (!p.ok)
243
+ return p.reason;
244
+ // @implements A-SPEC-731 (round 6) — what Codex refuses OUTSIDE the holmes-kit table refuses the
245
+ // whole file too; doctor had said PASS and init "active" for such files (measured).
246
+ const anywhere = valueProblem(p.doc, 'the config', -1);
247
+ if (anywhere)
248
+ return anywhere;
249
+ if (p.doc.model !== undefined && !isStr(p.doc.model))
250
+ return 'model is not a string';
251
+ if (p.doc.mcp_servers !== undefined) {
252
+ if (!isTable(p.doc.mcp_servers))
253
+ return 'mcp_servers is not a table';
254
+ for (const [name, t] of Object.entries(p.doc.mcp_servers)) {
255
+ if (name === 'holmes-kit')
256
+ continue; // judged below with its own messages
257
+ const sp = serverProblem(name, t);
258
+ if (sp)
259
+ return sp;
260
+ }
261
+ }
262
+ // Round 5: an entry Codex cannot deserialize makes it refuse the whole shared file.
263
+ if (!hasHolmesKey(p.doc))
264
+ return null;
265
+ const servers = p.doc.mcp_servers;
266
+ const entry = servers['holmes-kit'];
267
+ if (!isTable(entry))
268
+ return 'mcp_servers.holmes-kit is not a table (Codex expects one server table)';
269
+ if (entry.command !== undefined && typeof entry.command !== 'string')
270
+ return 'mcp_servers.holmes-kit.command is not a string';
271
+ if (entry.args !== undefined && (!Array.isArray(entry.args) || !entry.args.every((a) => typeof a === 'string')))
272
+ return 'mcp_servers.holmes-kit.args is not an array of strings';
273
+ if (entry.env !== undefined && !isTable(entry.env))
274
+ return 'mcp_servers.holmes-kit.env is not a table';
275
+ return serverProblem('holmes-kit', entry);
276
+ }
277
+ /**
278
+ * @implements A-SPEC-731 (round 4) — the write a caller is about to make, judged by the parser: null
279
+ * when `after` loads and its holmes-kit entry is exactly `want` (or absent when `want` is null), else
280
+ * the reason to write nothing.
281
+ */
282
+ function codexConfigWriteProblem(after, want) {
283
+ const p = parseCodexConfig(after);
284
+ if (!p.ok)
285
+ return `the result would not load as TOML (${p.reason})`;
286
+ const entry = holmesEntryOf(p.doc);
287
+ if (want === null)
288
+ return entry === null && !hasHolmesKey(p.doc) ? null : 'holmes-kit would still be configured after removal';
289
+ if (entry === null)
290
+ return 'the result would not carry a [mcp_servers.holmes-kit] table (is mcp_servers a closed inline table?)';
291
+ let same = false;
292
+ try {
293
+ same = entry.command === want.command && JSON.stringify(entry.args) === JSON.stringify(want.args)
294
+ && JSON.stringify(entry.env ?? null) === JSON.stringify(want.env ?? null)
295
+ && Object.keys(entry).every((k) => ['command', 'args', 'env'].includes(k));
296
+ }
297
+ catch {
298
+ same = false;
299
+ } // a BigInt value is not the entry holmes-kit writes
300
+ return same ? null : 'the holmes-kit entry in the result would not be exactly the one holmes-kit writes';
301
+ }
302
+ const hasHolmesKey = (doc) => {
303
+ const servers = Object.prototype.hasOwnProperty.call(doc, 'mcp_servers') ? doc.mcp_servers : undefined;
304
+ return isTable(servers) && Object.prototype.hasOwnProperty.call(servers, 'holmes-kit');
305
+ };
55
306
  /** The one table holmes-kit owns in a Codex config.toml. */
56
307
  exports.CODEX_TABLE = 'mcp_servers.holmes-kit';
57
308
  const HEADER = `[${exports.CODEX_TABLE}]`;
@@ -188,7 +439,10 @@ function lineStartStates(lines) {
188
439
  * append a duplicate table and invalidate the whole file — round-1 quoted-key, round-2 whitespace).
189
440
  * Returns null when the line is not a table header.
190
441
  */
191
- function tableKeyPath(line) {
442
+ function tableKeyPath(rawLine) {
443
+ // @implements A-SPEC-731 (round 1) — a CRLF file leaves `\r` on every line, and `.` never matches it:
444
+ // `[mcp_servers.holmes-kit] # mine\r` was not our table and init refused it as an unowned shape.
445
+ const line = rawLine.replace(/\r$/, '');
192
446
  const m = line.match(/^\s*\[\[?([^\]]*)\]\]?\s*(#.*)?$/);
193
447
  if (!m)
194
448
  return null;
@@ -196,17 +450,27 @@ function tableKeyPath(line) {
196
450
  const segs = [];
197
451
  let cur = '';
198
452
  let q = null;
453
+ // @implements A-SPEC-731 — basic-string ("…") segments are decoded as TOML decodes them:
454
+ // `[mcp_servers."holmes\u002dkit"]` IS `[mcp_servers.holmes-kit]` (tomllib agrees). An invalid escape
455
+ // makes the header unparsed — never ours.
456
+ const quotedBasic = new Set();
199
457
  for (let i = 0; i < inner.length; i++) {
200
458
  const c = inner[i];
201
459
  if (q) {
202
460
  if (c === q)
203
461
  q = null;
462
+ else if (c === '\\' && q === '"') {
463
+ cur += c + (inner[i + 1] ?? '');
464
+ i++;
465
+ } // keep the escape; decoded below
204
466
  else
205
467
  cur += c;
206
468
  continue;
207
469
  }
208
470
  if (c === '"' || c === "'") {
209
471
  q = c;
472
+ if (c === '"')
473
+ quotedBasic.add(segs.length);
210
474
  continue;
211
475
  }
212
476
  if (c === '.') {
@@ -223,7 +487,12 @@ function tableKeyPath(line) {
223
487
  segs.push(cur);
224
488
  if (q !== null)
225
489
  return null; // unbalanced quote — not a clean header
226
- return segs;
490
+ try {
491
+ return segs.map((seg, i) => (quotedBasic.has(i) && seg.includes('\\') ? unescapeToml(seg) : seg));
492
+ }
493
+ catch {
494
+ return null;
495
+ }
227
496
  }
228
497
  const isOurTable = (kp) => kp.length === 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
229
498
  const isOurPrefix = (kp) => kp.length >= 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
@@ -259,6 +528,10 @@ function ourRegion(lines) {
259
528
  break;
260
529
  } // any non-our (incl. unparseable) header closes us
261
530
  }
531
+ // @implements A-SPEC-731 (round 6) — comments and blank lines before the next header belong to what
532
+ // follows: rewiring deleted "# ---- my other server (keep!) ----" (measured).
533
+ while (end > start + 1 && states[end - 1].ml === null && /^\s*(#[^\n]*)?$/.test(lines[end - 1].replace(/\r$/, '')))
534
+ end--;
262
535
  return { start, end };
263
536
  }
264
537
  /**
@@ -275,11 +548,11 @@ function mergeCodexToml(existing, block) {
275
548
  if (region) {
276
549
  const after = lines.slice(region.end);
277
550
  const merged = [...lines.slice(0, region.start), ...blockLines, ...after];
278
- return merged.join('\n').replace(/\n*$/, '\n');
551
+ return `${(0, linear_match_1.trimTrailing)(merged.join('\n'), '\n')}\n`;
279
552
  }
280
553
  // Append: exactly one blank line between the user's content and our block.
281
- const base = existing.replace(/\n*$/, '');
282
- return `${base}\n\n${block.replace(/\n*$/, '')}\n`;
554
+ const base = (0, linear_match_1.trimTrailing)(existing, '\n');
555
+ return `${base}\n\n${(0, linear_match_1.trimTrailing)(block, '\n')}\n`;
283
556
  }
284
557
  /** Strip our region from `existing`, preserving everything else. Absent → returned unchanged. */
285
558
  function removeCodexToml(existing) {
@@ -296,7 +569,7 @@ function removeCodexToml(existing) {
296
569
  const joined = merged.join('\n');
297
570
  if (joined.trim() === '')
298
571
  return '';
299
- return joined.replace(/\n*$/, '\n');
572
+ return `${(0, linear_match_1.trimTrailing)(joined, '\n')}\n`;
300
573
  }
301
574
  /**
302
575
  * Read `{command,args}` from our table in a config.toml — for doctor's drift check. Parses only the
@@ -304,30 +577,14 @@ function removeCodexToml(existing) {
304
577
  * translating an unreadable wiring into a pass).
305
578
  */
306
579
  function readCodexHolmesEntry(raw) {
307
- const lines = raw.split('\n');
308
- const region = ourRegion(lines);
309
- if (!region)
580
+ // @implements A-SPEC-731 (round 4) — what the parser loads, nothing else.
581
+ const parsed = parseCodexConfig(raw);
582
+ if (!parsed.ok)
310
583
  return null;
311
- let command = null;
312
- let args = null;
313
- try {
314
- for (let i = region.start + 1; i < region.end; i++) {
315
- const cmd = lines[i].match(/^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"\s*(#.*)?$/);
316
- if (cmd)
317
- command = unescapeToml(cmd[1]);
318
- const arr = lines[i].match(/^\s*args\s*=\s*\[(.*)\]\s*(#.*)?$/);
319
- if (arr)
320
- args = parseTomlStringArray(arr[1]);
321
- }
322
- }
323
- catch (e) {
324
- if (e instanceof InvalidTomlEscape)
325
- return null; // @implements A-SPEC-585 — unreadable, not mangled
326
- throw e;
327
- }
328
- if (command === null || args === null)
584
+ const entry = holmesEntryOf(parsed.doc);
585
+ if (entry === null || typeof entry.command !== 'string' || !Array.isArray(entry.args) || !entry.args.every((a) => typeof a === 'string'))
329
586
  return null;
330
- return { command, args };
587
+ return { command: entry.command, args: entry.args };
331
588
  }
332
589
  /** @implements A-SPEC-721 — whether the config carries Holmes's table at all (well-formed or not). */
333
590
  function hasCodexHolmesTable(raw) {
@@ -373,7 +630,8 @@ function holmesLines(raw) {
373
630
  out.push({ i, header: true, text });
374
631
  continue;
375
632
  }
376
- const eq = text.indexOf('=');
633
+ // A-SPEC-731 (round 2): the key ends at the first `=` OUTSIDE quotes (`"a=b"` is one key).
634
+ const eq = firstUnquoted(text, '=');
377
635
  if (eq <= 0)
378
636
  continue;
379
637
  const key = tableKeyPath(`[${text.slice(0, eq).trim()}]`);
@@ -386,7 +644,8 @@ function holmesLines(raw) {
386
644
  }
387
645
  /** @implements A-SPEC-721 — whether the shared config configures the Holmes server at all. */
388
646
  function mentionsHolmes(raw) {
389
- return holmesLines(raw).length > 0;
647
+ const parsed = parseCodexConfig(raw);
648
+ return parsed.ok ? hasHolmesKey(parsed.doc) : holmesLines(raw).length > 0;
390
649
  }
391
650
  /**
392
651
  * @implements A-SPEC-721 — Holmes settings outside the one region init owns (dotted keys, an inline
@@ -395,6 +654,10 @@ function mentionsHolmes(raw) {
395
654
  */
396
655
  function unownedHolmesShape(raw) {
397
656
  const region = ourRegion(raw.split('\n'));
657
+ // Round 4: holmes-kit configured without our table region (a root inline `mcp_servers = { … }`).
658
+ const parsed = parseCodexConfig(raw);
659
+ if (parsed.ok && hasHolmesKey(parsed.doc) && region === null)
660
+ return true;
398
661
  return holmesLines(raw).some(({ i }) => !region || i < region.start || i >= region.end);
399
662
  }
400
663
  /**
@@ -403,20 +666,32 @@ function unownedHolmesShape(raw) {
403
666
  * value binds one fixed project.
404
667
  */
405
668
  function readCodexFixedSpecs(raw) {
406
- for (const { text } of holmesLines(raw)) {
407
- const m = text.match(/(?:^|[\s{,.])["']?HOLMES_SPECS["']?\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')/);
408
- if (!m)
669
+ // @implements A-SPEC-731 (round 4) — `env.HOLMES_SPECS` of the loaded entry; nothing else is a pin.
670
+ const parsed = parseCodexConfig(raw);
671
+ if (parsed.ok) {
672
+ const env = holmesEntryOf(parsed.doc)?.env;
673
+ return isTable(env) && typeof env.HOLMES_SPECS === 'string' ? env.HOLMES_SPECS : null;
674
+ }
675
+ return null;
676
+ }
677
+ /** Index of the first `ch` in `line` outside basic/literal strings, or -1. */
678
+ function firstUnquoted(line, ch) {
679
+ let q = null;
680
+ for (let i = 0; i < line.length; i++) {
681
+ const c = line[i];
682
+ if (q) {
683
+ if (c === '\\' && q === '"')
684
+ i++;
685
+ else if (c === q)
686
+ q = null;
409
687
  continue;
410
- if (m[2] !== undefined)
411
- return m[2];
412
- try {
413
- return unescapeToml(m[1]);
414
- }
415
- catch {
416
- return null;
417
688
  }
689
+ if (c === '"' || c === "'")
690
+ q = c;
691
+ else if (c === ch)
692
+ return i;
418
693
  }
419
- return null;
694
+ return -1;
420
695
  }
421
696
  /**
422
697
  * @implements A-SPEC-585
@@ -461,7 +736,10 @@ function firstInvalidEscape(s) {
461
736
  continue;
462
737
  }
463
738
  const width = e === 'u' ? 4 : e === 'U' ? 8 : 0;
464
- if (width > 0 && new RegExp(`^[0-9a-fA-F]{${width}}$`).test(s.slice(i + 2, i + 2 + width))) {
739
+ const hex = s.slice(i + 2, i + 2 + width);
740
+ // Round 4: a scalar value only — beyond U+10FFFF or a surrogate is not a TOML escape (it threw).
741
+ const cp = width > 0 && new RegExp(`^[0-9a-fA-F]{${width}}$`).test(hex) ? parseInt(hex, 16) : -1;
742
+ if (cp >= 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff)) {
465
743
  i += 1 + width;
466
744
  continue;
467
745
  }
@@ -482,12 +760,3 @@ function unescapeToml(s) {
482
760
  return SIMPLE_ESCAPES[e];
483
761
  });
484
762
  }
485
- /** Parse a TOML inline array of basic strings: `"a", "b"` → ['a','b']. Non-conforming → []. */
486
- function parseTomlStringArray(inner) {
487
- const out = [];
488
- const re = /"((?:[^"\\]|\\.)*)"/g;
489
- let mm;
490
- while ((mm = re.exec(inner)) !== null)
491
- out.push(unescapeToml(mm[1]));
492
- return out;
493
- }