@holmes-lab/holmes-kit 0.2.0 → 0.3.0

package/dist/holmes/assoc/ppr.js

@@ -0,0 +1,110 @@
+"use strict";
+// @implements A-SPEC-467
+/**
+ * Personalized PageRank over the RTM/CPG edge set — the associative-recall primitive.
+ *
+ * Why this exists: the shipped retrieval primitives sit at two extremes. `issue_localize` stops at
+ * one spec hop (its own comment defers anything further), and `rtm_impact` returns an UNGRADED
+ * transitive closure — measured on the replay corpus, 84% of a commit's co-changed files are
+ * reachable through that closure while the analysis names 11% of them: the bottleneck is selection
+ * within reach, not reach. What is missing between the two is graded multi-hop mass —
+ * Score(1-hop) > Score(2-hop) > … > 0 — which is exactly what a damped random walk provides.
+ *
+ * Eleven graph/semantic mechanisms were measured and rejected on this corpus before this one
+ * (binary k-hop expansion, caller closure, co-change retrieval, dense embeddings, …). PPR is
+ * structurally different from all of them: it produces a RANKING over nodes rather than an
+ * admission set, and the geometric damping suppresses the crowd problem that sank the closure.
+ * That difference is the reason this module exists; whether it PAYS is decided by the replay arm
+ * (rerank and admit modes scored separately, three corpora), never assumed here.
+ *
+ * Deterministic, pure, no I/O. PPR mass never enters a gate decision — association proposes,
+ * the deterministic layers judge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAdjacency = buildAdjacency;
+exports.personalizedPageRank = personalizedPageRank;
+/** Build the weighted, direction-aware, hub-damped transition structure once per graph. */
+function buildAdjacency(edges, profile) {
+    // Degree first (undirected, unweighted): the hub penalty divides by how CONNECTED the target is,
+    // not by how heavily this particular rel weighs it.
+    const degree = new Map();
+    const kept = [];
+    for (const e of edges) {
+        const w = profile.rels[e.rel];
+        if (w === undefined || (w.fwd <= 0 && w.back <= 0))
+            continue;
+        kept.push({ src: e.src, dst: e.dst, fwd: w.fwd, back: w.back });
+        degree.set(e.src, (degree.get(e.src) ?? 0) + 1);
+        degree.set(e.dst, (degree.get(e.dst) ?? 0) + 1);
+    }
+    const damp = (node) => profile.hubExponent > 0 ? Math.pow(degree.get(node) ?? 1, profile.hubExponent) : 1;
+    const raw = new Map();
+    const nodes = new Set();
+    const add = (from, to, w) => {
+        if (w <= 0)
+            return;
+        (raw.get(from) ?? raw.set(from, []).get(from)).push({ to, w: w / damp(to) });
+    };
+    for (const e of kept) {
+        nodes.add(e.src);
+        nodes.add(e.dst);
+        add(e.src, e.dst, e.fwd);
+        add(e.dst, e.src, e.back);
+    }
+    // Normalize out-mass per node so the walk is a probability distribution.
+    for (const [, list] of raw) {
+        const total = list.reduce((a, b) => a + b.w, 0);
+        for (const o of list)
+            o.w /= total;
+    }
+    return { out: raw, nodes };
+}
+/**
+ * Power iteration: v' = d·(Wᵀv + danglingMass·s) + (1−d)·s.
+ *
+ * Dangling mass refluxes to the SEEDS, not uniformly — a node with no out-edges returns the walk
+ * to the question rather than to the whole graph, and this is also what keeps a disconnected
+ * component at exactly zero. The vector always sums to 1 (asserted by test): a distribution that
+ * silently leaks mass would make cross-config comparisons meaningless.
+ */
+function personalizedPageRank(adj, seeds, opts) {
+    const { d } = opts;
+    const maxIter = opts.maxIter ?? 10;
+    const eps = opts.eps ?? 1e-4;
+    const seedTotal = [...seeds.values()].reduce((a, b) => a + b, 0);
+    if (seedTotal <= 0)
+        return new Map();
+    const s = new Map();
+    for (const [k, v] of seeds)
+        if (v > 0)
+            s.set(k, v / seedTotal);
+    let v = new Map(s);
+    for (let i = 0; i < maxIter; i++) {
+        // walk = Wᵀv + dangling·s (dangling mass returns to the seeds), then v' = d·walk + (1−d)·s.
+        const walk = new Map();
+        let dangling = 0;
+        for (const [node, mass] of v) {
+            const out = adj.out.get(node);
+            if (out === undefined || out.length === 0) {
+                dangling += mass;
+                continue;
+            }
+            for (const o of out)
+                walk.set(o.to, (walk.get(o.to) ?? 0) + mass * o.w);
+        }
+        const next = new Map();
+        for (const [k, sv] of s)
+            walk.set(k, (walk.get(k) ?? 0) + dangling * sv);
+        for (const [k, m] of walk)
+            next.set(k, d * m);
+        for (const [k, sv] of s)
+            next.set(k, (next.get(k) ?? 0) + (1 - d) * sv);
+        let l1 = 0;
+        for (const k of new Set([...v.keys(), ...next.keys()]))
+            l1 += Math.abs((v.get(k) ?? 0) - (next.get(k) ?? 0));
+        v = next;
+        if (eps > 0 && l1 < eps)
+            break;
+    }
+    return v;
+}

package/dist/holmes/cli/agents.d.ts

@@ -13,19 +13,32 @@ export type Agent = (typeof AGENTS)[number];
  * 그 하네스에서 게이트가 **집행되는가**.
  *
  * - `claude` — PreToolUse/Stop 훅. 이 저장소가 처음부터 배선해 온 하네스.
- * - `antigravity` — PreToolUse/Stop 훅이 있고 `deny`/`continue` 로 막을 수 있다(설치본의
- *   `agy-customizations` 규약 문서와 실제 대화 기록에서 실측).
- * - `codex` — 실측했다(codex-cli 0.149.0, 2026-08-23). 훅 규약 자체는 우리 것과 **동일**하다:
- *   바이너리 스키마가 `PreToolUse` / `permissionDecision: allow|deny|ask` / `stop_hook_active` /
- *   `hookSpecificOutput` 를 그대로 쓰고, codex 입력 형식으로 우리 `pre-tool-use.js` 를 먹이면 정확히
- *   `deny` 를 낸다. 그런데도 `false` 인 이유는 **배선 경로**다: codex 의 훅은 `config.toml` 의
- *   `[[hooks]]` 로 로드되지 않는다(잘못된 타입을 넣어도 `--strict-config` 가 통과 — 스키마 밖이다).
- *   `hook_runtime` 트레이스는 실제 셸 도구 실행에도 진입하지 않았고, 바이너리 문자열이 훅을
- *   `Plugins`/`RemotePlugin` 시스템(`codex plugin`, `--with-hooks` scaffold)으로 로드한다고 말한다.
- *   즉 codex 훅 집행은 **plugin 패키징**이 필요하며 MCP·config 배선으로는 닿지 않는다(REQ-248 로 남김).
- *   그때까지 codex 는 MCP 서버로만 지배되며, 그 경로는 실증됐다(spec_approve 등 서버측 승인 게이트).
+ * - `antigravity` — **true**, 실기 프로브로 확인(2026-08-30, `agy -p` 비대화 실행). Codex 에서
+ *   무너진 세 단계를 여기서는 전부 통과한다: `.agents/hooks.json` 이 적재되고(훅이 41회 호출됨),
+ *   페이로드가 어댑터의 `TOOL_MAP` 과 정확히 맞으며(`write_to_file`/`TargetFile`/`CodeContent`),
+ *   미승인 쓰기에 `deny` 를 내자 **파일이 생성되지 않았다.** Stop 훅의 헌법 감사와 루프 가드도
+ *   같은 실행에서 발화했다. 이 값의 근거는 이제 규약 문서가 아니라 실측이다.
+ * - `codex` — **false**, 실측(codex-cli 0.151.0, 2026-08-30, A-SPEC-442). Codex 는 훅을 집행할
+ *   수 있다: 벤더 규약대로 배선한 플러그인을 설치하면 PreToolUse 가 발화하고, exit 2 를 내면
+ *   `echo BLOCKED > blocked.txt` 가 실제로 실행되지 않는다(프로브 4회 중 3·4번째).
+ *
+ *   그런데 Codex 는 플러그인을 **설치된 마켓플레이스 스냅샷**에서만 적재한다. 프로젝트 폴더에
+ *   매니페스트를 놓아도, 그것을 마켓플레이스로 등록해 두어도, 사용자가 `codex plugin add` 를
+ *   실행하기 전에는 훅이 발화하지 않는다(프로브 1·2번째). 설치는 사용자의 행위이고 doctor 는
+ *   오프라인이므로, init 이 끝난 시점에 이 값이 참이라고 말할 근거가 없다.
+ *
+ *   A-SPEC-441 은 이 값을 true 로 올렸다. 그 결과 `AGENTS_MD(true)` 가 집행되지 않는 하네스에
+ *   "Gates are **enforced**" 라고 적었다 — 이 파일의 머리말이 하지 말라고 적어 둔 바로 그것이다.
  */
 export declare const HARNESS_ENFORCES: Record<Agent, boolean>;
+/**
+ * @implements A-SPEC-442
+ * codex 플러그인이 저장소 안에서 사는 자리. 저장소 루트에 `plugins/` 를 만들지 않으려고
+ * 중첩 경로를 쓴다 — 마켓플레이스의 `source.path` 가 `./` 로 시작하는 상대경로이기만 하면
+ * 중첩이 허용된다는 것은 실측으로 확인했다.
+ */
+export declare const CODEX_PLUGIN_DIR: string;
+export declare const CODEX_MARKETPLACE = "holmes-kit-local";
 export interface AgentWiringOptions {
     target: string;
     packageRoot: string;

package/dist/holmes/cli/agents.js

@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
+exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
 exports.agentFiles = agentFiles;
 exports.agentLinks = agentLinks;
+// @implements A-SPEC-442
 // @implements A-SPEC-193
 const path = __importStar(require("node:path"));
 const mcp_launcher_1 = require("./mcp-launcher");
@@ -52,23 +53,36 @@ exports.AGENTS = ['claude', 'antigravity', 'codex'];
  * 그 하네스에서 게이트가 **집행되는가**.
  *
  * - `claude` — PreToolUse/Stop 훅. 이 저장소가 처음부터 배선해 온 하네스.
- * - `antigravity` — PreToolUse/Stop 훅이 있고 `deny`/`continue` 로 막을 수 있다(설치본의
- *   `agy-customizations` 규약 문서와 실제 대화 기록에서 실측).
- * - `codex` — 실측했다(codex-cli 0.149.0, 2026-08-23). 훅 규약 자체는 우리 것과 **동일**하다:
- *   바이너리 스키마가 `PreToolUse` / `permissionDecision: allow|deny|ask` / `stop_hook_active` /
- *   `hookSpecificOutput` 를 그대로 쓰고, codex 입력 형식으로 우리 `pre-tool-use.js` 를 먹이면 정확히
- *   `deny` 를 낸다. 그런데도 `false` 인 이유는 **배선 경로**다: codex 의 훅은 `config.toml` 의
- *   `[[hooks]]` 로 로드되지 않는다(잘못된 타입을 넣어도 `--strict-config` 가 통과 — 스키마 밖이다).
- *   `hook_runtime` 트레이스는 실제 셸 도구 실행에도 진입하지 않았고, 바이너리 문자열이 훅을
- *   `Plugins`/`RemotePlugin` 시스템(`codex plugin`, `--with-hooks` scaffold)으로 로드한다고 말한다.
- *   즉 codex 훅 집행은 **plugin 패키징**이 필요하며 MCP·config 배선으로는 닿지 않는다(REQ-248 로 남김).
- *   그때까지 codex 는 MCP 서버로만 지배되며, 그 경로는 실증됐다(spec_approve 등 서버측 승인 게이트).
+ * - `antigravity` — **true**, 실기 프로브로 확인(2026-08-30, `agy -p` 비대화 실행). Codex 에서
+ *   무너진 세 단계를 여기서는 전부 통과한다: `.agents/hooks.json` 이 적재되고(훅이 41회 호출됨),
+ *   페이로드가 어댑터의 `TOOL_MAP` 과 정확히 맞으며(`write_to_file`/`TargetFile`/`CodeContent`),
+ *   미승인 쓰기에 `deny` 를 내자 **파일이 생성되지 않았다.** Stop 훅의 헌법 감사와 루프 가드도
+ *   같은 실행에서 발화했다. 이 값의 근거는 이제 규약 문서가 아니라 실측이다.
+ * - `codex` — **false**, 실측(codex-cli 0.151.0, 2026-08-30, A-SPEC-442). Codex 는 훅을 집행할
+ *   수 있다: 벤더 규약대로 배선한 플러그인을 설치하면 PreToolUse 가 발화하고, exit 2 를 내면
+ *   `echo BLOCKED > blocked.txt` 가 실제로 실행되지 않는다(프로브 4회 중 3·4번째).
+ *
+ *   그런데 Codex 는 플러그인을 **설치된 마켓플레이스 스냅샷**에서만 적재한다. 프로젝트 폴더에
+ *   매니페스트를 놓아도, 그것을 마켓플레이스로 등록해 두어도, 사용자가 `codex plugin add` 를
+ *   실행하기 전에는 훅이 발화하지 않는다(프로브 1·2번째). 설치는 사용자의 행위이고 doctor 는
+ *   오프라인이므로, init 이 끝난 시점에 이 값이 참이라고 말할 근거가 없다.
+ *
+ *   A-SPEC-441 은 이 값을 true 로 올렸다. 그 결과 `AGENTS_MD(true)` 가 집행되지 않는 하네스에
+ *   "Gates are **enforced**" 라고 적었다 — 이 파일의 머리말이 하지 말라고 적어 둔 바로 그것이다.
  */
 exports.HARNESS_ENFORCES = {
     claude: true,
     antigravity: true,
     codex: false,
 };
+/**
+ * @implements A-SPEC-442
+ * codex 플러그인이 저장소 안에서 사는 자리. 저장소 루트에 `plugins/` 를 만들지 않으려고
+ * 중첩 경로를 쓴다 — 마켓플레이스의 `source.path` 가 `./` 로 시작하는 상대경로이기만 하면
+ * 중첩이 허용된다는 것은 실측으로 확인했다.
+ */
+exports.CODEX_PLUGIN_DIR = path.join('.holmes', 'codex-plugin', 'holmes-kit');
+exports.CODEX_MARKETPLACE = 'holmes-kit-local';
 const q = (p) => p;
 // @implements A-SPEC-251.1 — same launch contract as the Claude wiring: npx-pin for installed
 // packageRoots, node for source checkouts. Shared via mcpEntryForInstall so all three harnesses
@@ -99,6 +113,17 @@ const mcpConfig = (packageRoot, specsDir, launcher) => {
 // Antigravity gate was silently off. (The MCP config above is different: it passes `args` as an
 // array, where quoting would put literal quote characters into the path.)
 const hookCommand = (packageRoot, script) => `node "${path.join(packageRoot, 'bin', script)}"`;
+/**
+ * @implements A-SPEC-442
+ * Codex 훅이 부를 것: **Claude 와 같은 정책 커널**.
+ *
+ * Codex 의 PreToolUse 출력 스키마는 `hookSpecificOutput.permissionDecision`(allow|deny|ask)이며,
+ * 이것은 Claude 규약과 같은 모양이다(codex 0.151.0 바이너리의 JSON 스키마에서 확인). 커널은
+ * 이미 그 형식을 낸다. 반면 antigravity 어댑터는 `toolCall.name` 을 찾고 `{"decision":"deny"}` 를
+ * exit 0 으로 낸다 — 실기에서 Codex 는 그것을 이해하지 못하고 `PreToolUse Failed` 로 처리하며
+ * **차단하지 않는다**(실측). 적재되는 훅과 말이 통하는 훅은 다른 문제이고, 둘 다 틀려 있었다.
+ */
+const kernelCommand = (packageRoot, script) => `node "${path.join(packageRoot, 'dist', 'holmes', 'hooks', script)}"`;
 const hooksJson = (packageRoot) => `${JSON.stringify({
     'holmes-kit': {
         PreToolUse: [{
@@ -137,11 +162,12 @@ This repository operates under **No Spec, No Code** governance. An approved spec
 
 1. Run \`spec_slice_init\` or \`spec_create\` to author REQ -> H-SPEC -> A-SPEC.
 2. Approve specs via \`spec_slice_approve\` or \`spec_approve\`.
-3. **Write tests first** and verify failure (RED stage).
-4. Approve the mirroring T-SPEC (\`A-SPEC-188\` -> \`T-SPEC-188\`).
-5. Implement source code (GREEN stage).
+3. **Before editing source**, run \`maintenance_analyze({ root, request, persist: true })\` and keep the digest it returns — that persisted analysis is what the pre-edit evidence gate checks.
+4. **Write tests first** and verify failure (RED stage).
+5. Approve the mirroring T-SPEC (\`A-SPEC-188\` -> \`T-SPEC-188\`).
+6. Implement source code (GREEN stage).
 
-Use \`spec_next\` to check the next required governance step. Use \`phase_check\` to verify action permissions ahead of execution.
+Use \`spec_next\` to check the next required governance step. Use \`phase_check\` to verify action permissions ahead of execution. Use \`impact_gate_check\` to ask what the pre-edit evidence gate would say about an edit — it is advisory and blocks nothing, so it answers the same way in every harness.
 
 ## Enforcement in this Harness
 
@@ -169,8 +195,58 @@ function agentFiles(agent, opts) {
                 { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.antigravity) },
             ];
         case 'codex':
+            // @implements A-SPEC-442 (was A-SPEC-266, A-SPEC-441) — Codex plugin, at the layout Codex reads:
+            //   1. the repository becomes a LOCAL MARKETPLACE (`.agents/plugins/marketplace.json`),
+            //      because Codex loads plugins only from installed marketplace snapshots;
+            //   2. the plugin manifest's `hooks` names `./hooks.json` at the PLUGIN ROOT — the vendor's
+            //      plugin reference (embedded in the codex binary) defines it that way, and the
+            //      `./hooks/hooks.json` A-SPEC-441 emitted was measured never to load.
+            // The MCP wiring stays in `.codex/config.toml` (merged by init.ts).
+            // Wiring is not installation: the user still runs `codex plugin marketplace add` and
+            // `codex plugin add`, which is why HARNESS_ENFORCES.codex is false.
             return [
-                { path: path.join(target, '.codex', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir, opts.launcher) },
+                {
+                    path: path.join(target, '.agents', 'plugins', 'marketplace.json'),
+                    content: `${JSON.stringify({
+                        name: exports.CODEX_MARKETPLACE,
+                        interface: { displayName: 'Holmes-Kit (local)' },
+                        plugins: [{
+                                name: 'holmes-kit',
+                                source: { source: 'local', path: `./${exports.CODEX_PLUGIN_DIR.split(path.sep).join('/')}` },
+                                policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+                                category: 'Developer Tools',
+                            }],
+                    }, null, 2)}\n`,
+                },
+                {
+                    path: path.join(target, exports.CODEX_PLUGIN_DIR, '.codex-plugin', 'plugin.json'),
+                    content: `${JSON.stringify({
+                        name: 'holmes-kit',
+                        version: '0.2.1',
+                        description: 'Holmes-Kit deterministic governance plugin for Codex',
+                        hooks: './hooks.json',
+                    }, null, 2)}\n`,
+                },
+                {
+                    path: path.join(target, exports.CODEX_PLUGIN_DIR, 'hooks.json'),
+                    content: `${JSON.stringify({
+                        hooks: {
+                            PreToolUse: [{
+                                    matcher: '.*',
+                                    hooks: [{
+                                            type: 'command',
+                                            command: kernelCommand(packageRoot, 'pre-tool-use.js'),
+                                            timeout: 30,
+                                        }],
+                                }],
+                            Stop: [{
+                                    type: 'command',
+                                    command: kernelCommand(packageRoot, 'stop.js'),
+                                    timeout: 30,
+                                }],
+                        },
+                    }, null, 2)}\n`,
+                },
                 { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.codex) },
             ];
         default:

package/dist/holmes/cli/codex-toml.d.ts

@@ -0,0 +1,26 @@
+import { McpServerEntry } from './mcp-launcher';
+/** The one table holmes-kit owns in a Codex config.toml. */
+export declare const CODEX_TABLE = "mcp_servers.holmes-kit";
+/**
+ * Serialize the `[mcp_servers.holmes-kit]` table. `env` is an inline table so the whole entry is ONE
+ * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary
+ * unambiguous: our region runs from the header to the next table header. Ends with a trailing newline.
+ */
+export declare function codexMcpBlock(entry: McpServerEntry, specsDir: string): string;
+/**
+ * Merge `block` (a full `codexMcpBlock` output) into `existing`. When `existing` is null/empty the
+ * block stands alone. When our table is already present its region is REPLACED (no duplicate); when
+ * absent the block is appended after a blank-line separator. Every other line is preserved verbatim.
+ */
+export declare function mergeCodexToml(existing: string | null, block: string): string;
+/** Strip our region from `existing`, preserving everything else. Absent → returned unchanged. */
+export declare function removeCodexToml(existing: string): string;
+/**
+ * Read `{command,args}` from our table in a config.toml — for doctor's drift check. Parses only the
+ * shape `codexMcpBlock` writes; anything it cannot read returns null (doctor then WARNs rather than
+ * translating an unreadable wiring into a pass).
+ */
+export declare function readCodexHolmesEntry(raw: string): {
+    command: string;
+    args: string[];
+} | null;

package/dist/holmes/cli/codex-toml.js

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_TABLE = void 0;
+exports.codexMcpBlock = codexMcpBlock;
+exports.mergeCodexToml = mergeCodexToml;
+exports.removeCodexToml = removeCodexToml;
+exports.readCodexHolmesEntry = readCodexHolmesEntry;
+/** The one table holmes-kit owns in a Codex config.toml. */
+exports.CODEX_TABLE = 'mcp_servers.holmes-kit';
+const HEADER = `[${exports.CODEX_TABLE}]`;
+/** TOML basic-string escape — backslash and quote, the named whitespace escapes, then any remaining
+ * C0 control character as \uXXXX. Built by code point so no literal control byte lives in the source. */
+function tomlStr(s) {
+    let out = '';
+    for (const ch of s) {
+        const code = ch.codePointAt(0);
+        if (ch === '\\')
+            out += '\\\\';
+        else if (ch === '"')
+            out += '\\"';
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        else
+            out += ch;
+    }
+    return `"${out}"`;
+}
+/**
+ * Serialize the `[mcp_servers.holmes-kit]` table. `env` is an inline table so the whole entry is ONE
+ * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary
+ * unambiguous: our region runs from the header to the next table header. Ends with a trailing newline.
+ */
+function codexMcpBlock(entry, specsDir) {
+    const args = entry.args.map(tomlStr).join(', ');
+    return [
+        HEADER,
+        `command = ${tomlStr(entry.command)}`,
+        `args = [${args}]`,
+        `env = { HOLMES_SPECS = ${tomlStr(specsDir)} }`,
+        '',
+    ].join('\n');
+}
+/** Advance the string/bracket state across one line's characters (comments end the line). */
+function advance(line, st) {
+    let { ml, depth } = st;
+    let i = 0;
+    while (i < line.length) {
+        if (ml === '"""') {
+            if (line.startsWith('"""', i)) {
+                ml = null;
+                i += 3;
+            }
+            else if (line[i] === '\\') {
+                i += 2;
+            }
+            else
+                i += 1;
+            continue;
+        }
+        if (ml === "'''") { // literal: no escapes
+            if (line.startsWith("'''", i)) {
+                ml = null;
+                i += 3;
+            }
+            else
+                i += 1;
+            continue;
+        }
+        if (line.startsWith('"""', i)) {
+            ml = '"""';
+            i += 3;
+            continue;
+        }
+        if (line.startsWith("'''", i)) {
+            ml = "'''";
+            i += 3;
+            continue;
+        }
+        const c = line[i];
+        if (c === '#')
+            break; // comment runs to end of line
+        if (c === '"') {
+            i += 1;
+            while (i < line.length && line[i] !== '"') {
+                if (line[i] === '\\')
+                    i += 1;
+                i += 1;
+            }
+            i += 1;
+            continue;
+        }
+        if (c === "'") {
+            i += 1;
+            while (i < line.length && line[i] !== "'")
+                i += 1;
+            i += 1;
+            continue;
+        }
+        if (c === '[' || c === '{') {
+            depth += 1;
+            i += 1;
+            continue;
+        }
+        if (c === ']' || c === '}') {
+            depth = Math.max(0, depth - 1);
+            i += 1;
+            continue;
+        }
+        i += 1;
+    }
+    return { ml, depth };
+}
+/** State at the START of each line (index-aligned to `lines`). */
+function lineStartStates(lines) {
+    const states = [];
+    let st = { ml: null, depth: 0 };
+    for (const line of lines) {
+        states.push(st);
+        st = advance(line, st);
+    }
+    return states;
+}
+/**
+ * The dotted key path of a table-header line, quotes stripped and each segment trimmed — so
+ * `[mcp_servers.holmes-kit]`, `[mcp_servers."holmes-kit"]`, and `[ mcp_servers . holmes-kit ]` all
+ * yield ['mcp_servers','holmes-kit'] (TOML treats them as the SAME table; missing an alias would
+ * append a duplicate table and invalidate the whole file — round-1 quoted-key, round-2 whitespace).
+ * Returns null when the line is not a table header.
+ */
+function tableKeyPath(line) {
+    const m = line.match(/^\s*\[\[?([^\]]*)\]\]?\s*(#.*)?$/);
+    if (!m)
+        return null;
+    const inner = m[1];
+    const segs = [];
+    let cur = '';
+    let q = null;
+    for (let i = 0; i < inner.length; i++) {
+        const c = inner[i];
+        if (q) {
+            if (c === q)
+                q = null;
+            else
+                cur += c;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            q = c;
+            continue;
+        }
+        if (c === '.') {
+            segs.push(cur.trim());
+            cur = '';
+            continue;
+        }
+        cur += c;
+    }
+    segs.push(cur.trim());
+    if (q !== null)
+        return null; // unbalanced quote — not a clean header
+    return segs;
+}
+const isOurTable = (kp) => kp.length === 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
+const isOurPrefix = (kp) => kp.length >= 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
+/**
+ * Locate our region as a [start, end) line-index pair, or null if absent. `start` is our table's
+ * header line; `end` is the first later line that opens a DIFFERENT top-level table (exclusive), or
+ * lines.length. Only real headers (outside strings, bracket-depth 0) are considered — AND the end
+ * boundary closes on ANY top-level header line, even one `tableKeyPath` cannot normalize (e.g. a
+ * quoted key containing `]`). That fail-safe is the point: an unrecognized header is never OURS, so
+ * treating it as a boundary preserves the foreign table rather than swallowing it (round-3 finding).
+ */
+function ourRegion(lines) {
+    const states = lineStartStates(lines);
+    const isTopLevelHeaderLine = (i) => states[i].ml === null && states[i].depth === 0 && /^\s*\[/.test(lines[i]);
+    const keyAt = (i) => (isTopLevelHeaderLine(i) ? tableKeyPath(lines[i]) : null);
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const kp = keyAt(i);
+        if (kp && isOurTable(kp)) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (!isTopLevelHeaderLine(i))
+            continue;
+        const kp = tableKeyPath(lines[i]);
+        if (!(kp && isOurPrefix(kp))) {
+            end = i;
+            break;
+        } // any non-our (incl. unparseable) header closes us
+    }
+    return { start, end };
+}
+/**
+ * Merge `block` (a full `codexMcpBlock` output) into `existing`. When `existing` is null/empty the
+ * block stands alone. When our table is already present its region is REPLACED (no duplicate); when
+ * absent the block is appended after a blank-line separator. Every other line is preserved verbatim.
+ */
+function mergeCodexToml(existing, block) {
+    if (existing == null || existing.trim() === '')
+        return block;
+    const lines = existing.split('\n');
+    const region = ourRegion(lines);
+    const blockLines = block.replace(/\n$/, '').split('\n');
+    if (region) {
+        const after = lines.slice(region.end);
+        const merged = [...lines.slice(0, region.start), ...blockLines, ...after];
+        return merged.join('\n').replace(/\n*$/, '\n');
+    }
+    // Append: exactly one blank line between the user's content and our block.
+    const base = existing.replace(/\n*$/, '');
+    return `${base}\n\n${block.replace(/\n*$/, '')}\n`;
+}
+/** Strip our region from `existing`, preserving everything else. Absent → returned unchanged. */
+function removeCodexToml(existing) {
+    const lines = existing.split('\n');
+    const region = ourRegion(lines);
+    if (!region)
+        return existing;
+    const before = lines.slice(0, region.start);
+    const after = lines.slice(region.end);
+    // Drop a trailing blank line left dangling between `before` and `after` so removal is clean.
+    while (before.length > 0 && before[before.length - 1].trim() === '')
+        before.pop();
+    const merged = [...before, ...after];
+    const joined = merged.join('\n');
+    if (joined.trim() === '')
+        return '';
+    return joined.replace(/\n*$/, '\n');
+}
+/**
+ * Read `{command,args}` from our table in a config.toml — for doctor's drift check. Parses only the
+ * shape `codexMcpBlock` writes; anything it cannot read returns null (doctor then WARNs rather than
+ * translating an unreadable wiring into a pass).
+ */
+function readCodexHolmesEntry(raw) {
+    const lines = raw.split('\n');
+    const region = ourRegion(lines);
+    if (!region)
+        return null;
+    let command = null;
+    let args = null;
+    for (let i = region.start + 1; i < region.end; i++) {
+        const cmd = lines[i].match(/^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"\s*(#.*)?$/);
+        if (cmd)
+            command = unescapeToml(cmd[1]);
+        const arr = lines[i].match(/^\s*args\s*=\s*\[(.*)\]\s*(#.*)?$/);
+        if (arr)
+            args = parseTomlStringArray(arr[1]);
+    }
+    if (command === null || args === null)
+        return null;
+    return { command, args };
+}
+function unescapeToml(s) {
+    return s.replace(/\\(u[0-9a-fA-F]{4}|.)/g, (_, e) => {
+        if (e[0] === 'u')
+            return String.fromCharCode(parseInt(e.slice(1), 16));
+        const map = { n: '\n', r: '\r', t: '\t', '"': '"', '\\': '\\' };
+        return map[e] ?? e;
+    });
+}
+/** Parse a TOML inline array of basic strings: `"a", "b"` → ['a','b']. Non-conforming → []. */
+function parseTomlStringArray(inner) {
+    const out = [];
+    const re = /"((?:[^"\\]|\\.)*)"/g;
+    let mm;
+    while ((mm = re.exec(inner)) !== null)
+        out.push(unescapeToml(mm[1]));
+    return out;
+}