@agfpd/iapeer-memory 0.1.13 → 0.2.0

package/src/surfaces/claude.ts

@@ -0,0 +1,494 @@
+/**
+ * Direct claude session surfaces — ADR-009 v1.2 (решение Артура 10.06:
+ * прямые per-peer поверхности вместо плагина-розетки). Three surfaces are
+ * merged into the PEER's cwd; nothing is written host-globally (требование
+ * №3) and nothing of the user's is ever clobbered (требование №1 — only our
+ * own keys/entries are read-merge-written, atomically):
+ *
+ *   1. hooks  — entries merged into `<cwd>/.claude/settings.json`
+ *               (PostToolUse Write|Edit|MultiEdit + SessionStart). The hook
+ *               command is the ABSOLUTE path of our materialised shim —
+ *               ownership lives IN THE DATA (boris design input): an entry
+ *               whose command path contains `/iapeer-memory/hooks/` is ours,
+ *               everything else in the file is somebody else's (the file
+ *               also carries statusline-injector, totp-presence, the core's
+ *               autoMemoryEnabled — the «last writer rolls back» class is
+ *               closed by patching ONLY our entries);
+ *   2. mcp    — `mcpServers["iapeer-memory"]` merged into `<cwd>/.mcp.json`,
+ *               LITERAL url + identity header (the BATTLE-TESTED direct form:
+ *               the core's writeClaudeMcpConfig writes the same shape for its
+ *               own 8765 server on the whole fleet; the plugin's env-
+ *               substitution form has NO live precedent in the direct project
+ *               scope — D1's env-form decision was reversed on this fact);
+ *   3. skills — `<cwd>/.claude/skills/iapeer-memory-<name>/SKILL.md`
+ *               (embedded bodies, bytes-compare; the directory prefix is OUR
+ *               namespace — unprovision removes every match).
+ *
+ * Pickup semantics (documented, boris design input): a live session does NOT
+ * re-read these files — surfaces land on the peer's NEXT session start
+ * (same semantics the plugin form had).
+ *
+ * Idempotent by construction: same version re-run → `already` on every
+ * surface; drift (a mangled/deleted entry) → re-written. The remove path is
+ * the exact mirror: our entries/keys/directories only, empty containers are
+ * swept (an empty `hooks: {}` left behind would be OUR litter in the user's
+ * file).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { SKILL_BODIES, SKILL_DIR_PREFIX, SKILL_NAMES } from "../templates/skills.js";
+
+export const MCP_SERVER_KEY = "iapeer-memory";
+/**
+ * In-data ownership of our hook entries — the namespace lives in the shim
+ * FILE NAME (`iapeer-memory.<verb>.sh`), NOT in the directory path. D4 live
+ * catch 11.06: the first form keyed on the `/iapeer-memory/hooks/` directory
+ * segment, which is DERIVED from the config-file location — a custom
+ * IAPEER_MEMORY_CONFIG_FILE produced a hooksDir without the segment, so our
+ * own entries read as foreign (duplicated on every update, false drift on
+ * every check). A basename namespace is invariant under EVERY path
+ * configuration by construction. Matching is deliberately WIDER than the
+ * current expected path: an entry pointing at a STALE shim location is
+ * still ours — drift to repair, not a foreign entry to preserve.
+ */
+export const HOOK_SHIM_PREFIX = "iapeer-memory.";
+
+export function isOurHookCommand(command: string): boolean {
+  const base = command.split("/").pop() ?? "";
+  return base.startsWith(HOOK_SHIM_PREFIX) && base.endsWith(".sh");
+}
+
+export type SurfaceAction = "written" | "already" | "removed" | "absent" | "failed";
+export type SurfaceOutcome = {
+  surface: "hooks" | "mcp" | "skills";
+  action: SurfaceAction;
+  path: string;
+  detail?: string;
+};
+
+// ── shims (fail-open bash, materialised into OUR territory) ──────────────────
+
+function shimContent(verb: "post-write" | "session-start"): string {
+  return [
+    "#!/usr/bin/env bash",
+    `# iapeer-memory hook shim — ALL logic lives in the package CLI`,
+    `# (\`iapeer-memory hook ${verb}\`; testable TS, ADR-009 v1.2 direct form).`,
+    "# Fail-open: no CLI on this host → silent exit 0.",
+    "set -euo pipefail",
+    'CLI="$(command -v iapeer-memory || true)"',
+    '[ -n "$CLI" ] || CLI="$HOME/.local/bin/iapeer-memory"',
+    '[ -x "$CLI" ] || exit 0',
+    `exec "$CLI" hook ${verb}`,
+    "",
+  ].join("\n");
+}
+
+function writeFileAtomic(filePath: string, content: string, mode?: number): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, content, "utf-8");
+  if (mode !== undefined) fs.chmodSync(tmp, mode);
+  fs.renameSync(tmp, filePath);
+}
+
+/** Materialise both hook shims (package-owned, bytes-compare). provision
+ *  always runs this first — the merged settings entries must never point at
+ *  a void (the core's birth-hook may call provision-peer on a host where
+ *  init ran long ago and the shims were swept by hand). */
+export function shimPath(hooksDir: string, verb: "post-write" | "session-start"): string {
+  return path.join(hooksDir, `${HOOK_SHIM_PREFIX}${verb}.sh`); // namespace IN the basename
+}
+
+export function materialiseShims(hooksDir: string): "written" | "identical" {
+  let wrote = false;
+  for (const verb of ["post-write", "session-start"] as const) {
+    const p = shimPath(hooksDir, verb);
+    const content = shimContent(verb);
+    try {
+      if (fs.readFileSync(p, "utf-8") === content) continue;
+    } catch {
+      // missing → write
+    }
+    writeFileAtomic(p, content, 0o755);
+    wrote = true;
+  }
+  return wrote ? "written" : "identical";
+}
+
+// ── expected forms ───────────────────────────────────────────────────────────
+
+/** LITERAL url + identity header — byte-isomorphic to the core's own battle
+ *  form (writeClaudeMcpConfig: every fleet peer carries
+ *  `"X-IAPeer-Identity": "claude-<personality>"` against the 8765 daemon,
+ *  proven live at cold-start 08.06). Port and personality are HOST FACTS
+ *  baked at provision time; drift (port change, peer rename) is repaired by
+ *  the update/verify sweep against fleet.json (требование №2). */
+export function expectedMcpEntry(opts: {
+  port: number;
+  personality: string;
+}): Record<string, unknown> {
+  return {
+    type: "http",
+    url: `http://127.0.0.1:${opts.port}/mcp`,
+    headers: {
+      "X-IAPeer-Identity": `claude-${opts.personality}`,
+    },
+  };
+}
+
+type HookEntry = {
+  matcher?: string;
+  hooks: Array<{ type: string; command: string }>;
+};
+
+export function expectedHookEntries(
+  hooksDir: string,
+): Record<"PostToolUse" | "SessionStart", HookEntry> {
+  return {
+    PostToolUse: {
+      matcher: "Write|Edit|MultiEdit",
+      hooks: [{ type: "command", command: shimPath(hooksDir, "post-write") }],
+    },
+    SessionStart: {
+      hooks: [{ type: "command", command: shimPath(hooksDir, "session-start") }],
+    },
+  };
+}
+
+// ── json plumbing ────────────────────────────────────────────────────────────
+
+type JsonObject = Record<string, unknown>;
+
+/** null = unreadable-as-object (refuse to clobber); {} when absent. */
+function readJsonObject(filePath: string): JsonObject | null | "absent" {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return "absent";
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed as JsonObject;
+  } catch {
+    return null;
+  }
+}
+
+function sameJson(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function isOurHookEntry(entry: unknown): boolean {
+  if (!entry || typeof entry !== "object") return false;
+  const hooks = (entry as HookEntry).hooks;
+  if (!Array.isArray(hooks)) return false;
+  return hooks.some(
+    (h) => typeof h?.command === "string" && isOurHookCommand(h.command),
+  );
+}
+
+// ── hooks surface ────────────────────────────────────────────────────────────
+
+export function mergeClaudeHooks(opts: {
+  cwd: string;
+  hooksDir: string;
+}): SurfaceOutcome {
+  const settingsPath = path.join(opts.cwd, ".claude", "settings.json");
+  const current = readJsonObject(settingsPath);
+  if (current === null) {
+    return {
+      surface: "hooks",
+      action: "failed",
+      path: settingsPath,
+      detail: "settings.json is not a JSON object — refusing to clobber",
+    };
+  }
+  const obj: JsonObject = current === "absent" ? {} : current;
+  const hooksRaw = obj.hooks;
+  if (hooksRaw !== undefined && (typeof hooksRaw !== "object" || Array.isArray(hooksRaw) || hooksRaw === null)) {
+    return {
+      surface: "hooks",
+      action: "failed",
+      path: settingsPath,
+      detail: "settings.json `hooks` is not an object — refusing to clobber",
+    };
+  }
+  const hooks: JsonObject = (hooksRaw as JsonObject | undefined) ?? {};
+  const expected = expectedHookEntries(opts.hooksDir);
+  let changed = false;
+  for (const event of ["PostToolUse", "SessionStart"] as const) {
+    const listRaw = hooks[event];
+    const list: unknown[] = Array.isArray(listRaw) ? listRaw : [];
+    const ours = list.filter(isOurHookEntry);
+    if (ours.length === 1 && sameJson(ours[0], expected[event])) continue;
+    const foreign = list.filter((e) => !isOurHookEntry(e));
+    hooks[event] = [...foreign, expected[event]];
+    changed = true;
+  }
+  if (!changed) {
+    return { surface: "hooks", action: "already", path: settingsPath };
+  }
+  obj.hooks = hooks;
+  writeFileAtomic(settingsPath, `${JSON.stringify(obj, null, 2)}\n`);
+  return { surface: "hooks", action: "written", path: settingsPath };
+}
+
+export function removeClaudeHooks(opts: { cwd: string }): SurfaceOutcome {
+  const settingsPath = path.join(opts.cwd, ".claude", "settings.json");
+  const current = readJsonObject(settingsPath);
+  if (current === "absent") {
+    return { surface: "hooks", action: "absent", path: settingsPath };
+  }
+  if (current === null) {
+    return {
+      surface: "hooks",
+      action: "failed",
+      path: settingsPath,
+      detail: "settings.json is not a JSON object — refusing to touch",
+    };
+  }
+  const hooksRaw = current.hooks;
+  if (!hooksRaw || typeof hooksRaw !== "object" || Array.isArray(hooksRaw)) {
+    return { surface: "hooks", action: "absent", path: settingsPath };
+  }
+  const hooks = hooksRaw as JsonObject;
+  let changed = false;
+  for (const event of Object.keys(hooks)) {
+    const list = hooks[event];
+    if (!Array.isArray(list)) continue;
+    const kept = list
+      .map((entry) => {
+        if (!isOurHookEntry(entry)) return entry;
+        // an entry may THEORETICALLY mix our hook with a foreign one in the
+        // same matcher block — strip only our hook elements, keep the rest
+        const e = entry as HookEntry;
+        const foreignHooks = e.hooks.filter(
+          (h) => !(typeof h?.command === "string" && isOurHookCommand(h.command)),
+        );
+        if (foreignHooks.length === 0) return null; // entirely ours → drop
+        return { ...e, hooks: foreignHooks };
+      })
+      .filter((e): e is NonNullable<typeof e> => e !== null);
+    if (kept.length !== list.length || !sameJson(kept, list)) changed = true;
+    if (kept.length === 0) {
+      delete hooks[event];
+    } else {
+      hooks[event] = kept;
+    }
+  }
+  if (!changed) {
+    return { surface: "hooks", action: "absent", path: settingsPath };
+  }
+  if (Object.keys(hooks).length === 0) {
+    delete current.hooks; // our litter, not the user's — sweep the container
+  }
+  writeFileAtomic(settingsPath, `${JSON.stringify(current, null, 2)}\n`);
+  return { surface: "hooks", action: "removed", path: settingsPath };
+}
+
+// ── mcp surface ──────────────────────────────────────────────────────────────
+
+export function mergeClaudeMcp(opts: {
+  cwd: string;
+  port: number;
+  personality: string;
+}): SurfaceOutcome {
+  const mcpPath = path.join(opts.cwd, ".mcp.json");
+  const current = readJsonObject(mcpPath);
+  if (current === null) {
+    return {
+      surface: "mcp",
+      action: "failed",
+      path: mcpPath,
+      detail: ".mcp.json is not a JSON object — refusing to clobber",
+    };
+  }
+  const obj: JsonObject = current === "absent" ? {} : current;
+  const serversRaw = obj.mcpServers;
+  if (serversRaw !== undefined && (typeof serversRaw !== "object" || Array.isArray(serversRaw) || serversRaw === null)) {
+    return {
+      surface: "mcp",
+      action: "failed",
+      path: mcpPath,
+      detail: ".mcp.json `mcpServers` is not an object — refusing to clobber",
+    };
+  }
+  const servers: JsonObject = (serversRaw as JsonObject | undefined) ?? {};
+  const expected = expectedMcpEntry({ port: opts.port, personality: opts.personality });
+  if (sameJson(servers[MCP_SERVER_KEY], expected)) {
+    return { surface: "mcp", action: "already", path: mcpPath };
+  }
+  servers[MCP_SERVER_KEY] = expected;
+  obj.mcpServers = servers;
+  writeFileAtomic(mcpPath, `${JSON.stringify(obj, null, 2)}\n`);
+  return { surface: "mcp", action: "written", path: mcpPath };
+}
+
+export function removeClaudeMcp(opts: { cwd: string }): SurfaceOutcome {
+  const mcpPath = path.join(opts.cwd, ".mcp.json");
+  const current = readJsonObject(mcpPath);
+  if (current === "absent") {
+    return { surface: "mcp", action: "absent", path: mcpPath };
+  }
+  if (current === null) {
+    return {
+      surface: "mcp",
+      action: "failed",
+      path: mcpPath,
+      detail: ".mcp.json is not a JSON object — refusing to touch",
+    };
+  }
+  const servers = current.mcpServers;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers) ||
+      !(MCP_SERVER_KEY in (servers as JsonObject))) {
+    return { surface: "mcp", action: "absent", path: mcpPath };
+  }
+  delete (servers as JsonObject)[MCP_SERVER_KEY];
+  const serversEmpty = Object.keys(servers as JsonObject).length === 0;
+  const onlyServersKey = Object.keys(current).length === 1;
+  if (serversEmpty && onlyServersKey) {
+    // semantically empty file — with our key gone it says nothing; a file we
+    // most likely created. Removing it leaves the cwd exactly as found.
+    fs.unlinkSync(mcpPath);
+    return { surface: "mcp", action: "removed", path: mcpPath, detail: "file removed (empty after our key)" };
+  }
+  writeFileAtomic(mcpPath, `${JSON.stringify(current, null, 2)}\n`);
+  return { surface: "mcp", action: "removed", path: mcpPath };
+}
+
+// ── skills surface ───────────────────────────────────────────────────────────
+
+export function mergeClaudeSkills(opts: { cwd: string }): SurfaceOutcome {
+  const skillsDir = path.join(opts.cwd, ".claude", "skills");
+  let wrote = 0;
+  try {
+    for (const name of SKILL_NAMES) {
+      const p = path.join(skillsDir, name, "SKILL.md");
+      const body = SKILL_BODIES[name];
+      try {
+        if (fs.readFileSync(p, "utf-8") === body) continue;
+      } catch {
+        // missing → write
+      }
+      writeFileAtomic(p, body);
+      wrote++;
+    }
+  } catch (err) {
+    return { surface: "skills", action: "failed", path: skillsDir, detail: String(err) };
+  }
+  return wrote
+    ? { surface: "skills", action: "written", path: skillsDir, detail: `${wrote}/${SKILL_NAMES.length} skill(s) written` }
+    : { surface: "skills", action: "already", path: skillsDir };
+}
+
+export function removeClaudeSkills(opts: { cwd: string }): SurfaceOutcome {
+  const skillsDir = path.join(opts.cwd, ".claude", "skills");
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(skillsDir);
+  } catch {
+    return { surface: "skills", action: "absent", path: skillsDir };
+  }
+  // the `iapeer-memory-` prefix is OUR namespace (the naming promise): every
+  // matching directory is ours — including stale names of older versions
+  const ours = entries.filter((e) => e.startsWith(SKILL_DIR_PREFIX));
+  if (ours.length === 0) {
+    return { surface: "skills", action: "absent", path: skillsDir };
+  }
+  for (const e of ours) {
+    fs.rmSync(path.join(skillsDir, e), { recursive: true, force: true });
+  }
+  // sweep empty containers we may have created (skills/ then .claude/)
+  for (const dir of [skillsDir, path.dirname(skillsDir)]) {
+    try {
+      if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+    } catch {
+      break;
+    }
+  }
+  return { surface: "skills", action: "removed", path: skillsDir, detail: `${ours.length} skill dir(s) removed` };
+}
+
+// ── the per-peer verbs ───────────────────────────────────────────────────────
+
+export function provisionClaudePeer(opts: {
+  cwd: string;
+  hooksDir: string;
+  port: number;
+  personality: string;
+}): SurfaceOutcome[] {
+  materialiseShims(opts.hooksDir);
+  return [
+    mergeClaudeHooks({ cwd: opts.cwd, hooksDir: opts.hooksDir }),
+    mergeClaudeMcp({ cwd: opts.cwd, port: opts.port, personality: opts.personality }),
+    mergeClaudeSkills({ cwd: opts.cwd }),
+  ];
+}
+
+export function unprovisionClaudePeer(opts: { cwd: string }): SurfaceOutcome[] {
+  return [
+    removeClaudeHooks({ cwd: opts.cwd }),
+    removeClaudeMcp({ cwd: opts.cwd }),
+    removeClaudeSkills({ cwd: opts.cwd }),
+  ];
+}
+
+/** Read-only drift check of one peer's claude surfaces (verify's eye; D3
+ *  wires it into `verify [--repair]` across the fleet map). */
+export function checkClaudePeer(opts: {
+  cwd: string;
+  hooksDir: string;
+  port: number;
+  personality: string;
+}): Array<{ surface: SurfaceOutcome["surface"]; ok: boolean; detail: string }> {
+  const out: Array<{ surface: SurfaceOutcome["surface"]; ok: boolean; detail: string }> = [];
+
+  const settingsPath = path.join(opts.cwd, ".claude", "settings.json");
+  const settings = readJsonObject(settingsPath);
+  const expected = expectedHookEntries(opts.hooksDir);
+  if (settings === "absent" || settings === null) {
+    out.push({ surface: "hooks", ok: false, detail: `no readable settings at ${settingsPath}` });
+  } else {
+    const hooks = (settings.hooks ?? {}) as JsonObject;
+    const missing = (["PostToolUse", "SessionStart"] as const).filter((event) => {
+      const list = Array.isArray(hooks[event]) ? (hooks[event] as unknown[]) : [];
+      const ours = list.filter(isOurHookEntry);
+      return !(ours.length === 1 && sameJson(ours[0], expected[event]));
+    });
+    out.push(
+      missing.length === 0
+        ? { surface: "hooks", ok: true, detail: "both hook entries in place" }
+        : { surface: "hooks", ok: false, detail: `drifted/missing: ${missing.join(", ")}` },
+    );
+  }
+
+  const mcp = readJsonObject(path.join(opts.cwd, ".mcp.json"));
+  const entry =
+    mcp !== "absent" && mcp !== null
+      ? ((mcp.mcpServers as JsonObject | undefined) ?? {})[MCP_SERVER_KEY]
+      : undefined;
+  out.push(
+    sameJson(entry, expectedMcpEntry({ port: opts.port, personality: opts.personality }))
+      ? { surface: "mcp", ok: true, detail: `${MCP_SERVER_KEY} server entry in place` }
+      : { surface: "mcp", ok: false, detail: `mcpServers["${MCP_SERVER_KEY}"] missing or drifted in ${opts.cwd}/.mcp.json` },
+  );
+
+  const skillsDir = path.join(opts.cwd, ".claude", "skills");
+  const drifted = SKILL_NAMES.filter((name) => {
+    try {
+      return fs.readFileSync(path.join(skillsDir, name, "SKILL.md"), "utf-8") !== SKILL_BODIES[name];
+    } catch {
+      return true;
+    }
+  });
+  out.push(
+    drifted.length === 0
+      ? { surface: "skills", ok: true, detail: `${SKILL_NAMES.length} skills in place` }
+      : { surface: "skills", ok: false, detail: `missing/drifted: ${drifted.join(", ")}` },
+  );
+
+  return out;
+}

package/src/surfaces/codex.ts

@@ -0,0 +1,155 @@
+/**
+ * Direct codex session surface — per-peer MCP via the PROJECT-LOCAL
+ * `<cwd>/.codex/config.toml` (ADR-009 v1.2; требование Артура №3 «глобально
+ * не класть» — proven satisfiable by the iapeer smoke 10.06 ~18:40: a
+ * project-local `[mcp_servers]` block in a TRUSTED cwd is read by
+ * `codex mcp list` AND imported end-to-end into exec sessions; the trust
+ * record is written by the core's provision, keyed on the realpath).
+ *
+ * Block form mirrors the core's PROVEN host-wide `[mcp_servers.iapeer]`
+ * block (iapeer src/init/index.ts writeCodexMcpConfig — live on the whole
+ * codex fleet), pointed at memoryd:
+ *
+ *   - `url` — the memoryd HTTP-MCP endpoint. TOML carries no env
+ *     substitution: the LITERAL port is baked at provision time from the
+ *     host config (IAPEER_MEMORY_MCP_PORT, default 8766); a port change is
+ *     re-baked by the update/verify sweep;
+ *   - `default_tools_approval_mode = "approve"` — no per-tool dialog;
+ *   - `bearer_token_env_var = "IAPEER_BEARER"` — flips codex's authStatus
+ *     so the tools import (#21532/#4707 workaround); the value is the
+ *     NON-SECRET dummy the core's launch exports to EVERY codex peer;
+ *   - `env_http_headers."X-IAPeer-Identity" = "PEER_IDENTITY"` — per-peer
+ *     identity from the launch env (`codex-<personality>`; memoryd's parser
+ *     strips the runtime prefix). A codex session started OUTSIDE an iapeer
+ *     launch carries no PEER_IDENTITY — same unattributed fallback the
+ *     claude env form has.
+ *
+ * The file CARRIES FOREIGN CONTENT — the core's native-memory lever writes
+ * `[features] memories = false` here, the operator may keep own sections.
+ * Merge = line-based section surgery on OUR header namespace only
+ * (`[mcp_servers.iapeer-memory]` + its subsections), atomic write; unlike
+ * the core's append-if-absent we REPLACE a drifted block (repair duty,
+ * требование №2). Hooks/skills for codex are the P5 experiment — MCP is
+ * deliberately the only codex surface here.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { SurfaceOutcome } from "./claude.js";
+
+export const CODEX_MCP_SECTION = "mcp_servers.iapeer-memory";
+const SECTION_HEADER_RE = /^\s*\[/;
+const OUR_HEADER_RE = /^\s*\[mcp_servers\.iapeer-memory(\.[A-Za-z0-9_.-]+)?\]\s*$/;
+
+export function codexConfigPath(cwd: string): string {
+  return path.join(cwd, ".codex", "config.toml");
+}
+
+export function expectedCodexBlock(port: number): string {
+  return [
+    `[${CODEX_MCP_SECTION}]`,
+    `url = "http://127.0.0.1:${port}/mcp"`,
+    `default_tools_approval_mode = "approve"`,
+    `bearer_token_env_var = "IAPEER_BEARER"`,
+    "",
+    `[${CODEX_MCP_SECTION}.env_http_headers]`,
+    `"X-IAPeer-Identity" = "PEER_IDENTITY"`,
+    "",
+  ].join("\n");
+}
+
+function writeFileAtomic(filePath: string, content: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, content, "utf-8");
+  fs.renameSync(tmp, filePath);
+}
+
+/** Strip every section under OUR header namespace; foreign lines unchanged. */
+function withoutOurSections(lines: string[]): string[] {
+  const kept: string[] = [];
+  let inOurs = false;
+  for (const line of lines) {
+    if (SECTION_HEADER_RE.test(line)) inOurs = OUR_HEADER_RE.test(line);
+    if (!inOurs) kept.push(line);
+  }
+  // drop the trailing blank run our removal may have exposed
+  while (kept.length > 0 && kept[kept.length - 1].trim() === "") kept.pop();
+  return kept;
+}
+
+function hasOurSection(text: string): boolean {
+  return text.split("\n").some((l) => OUR_HEADER_RE.test(l));
+}
+
+export function mergeCodexMcp(opts: { cwd: string; port: number }): SurfaceOutcome {
+  const configPath = codexConfigPath(opts.cwd);
+  let text = "";
+  try {
+    text = fs.readFileSync(configPath, "utf-8");
+  } catch {
+    // no config yet → create
+  }
+  const lines = text.length ? text.split("\n") : [];
+  const foreign = withoutOurSections(lines);
+  const next =
+    (foreign.length ? `${foreign.join("\n")}\n\n` : "") + expectedCodexBlock(opts.port);
+  if (next === text) {
+    return { surface: "mcp", action: "already", path: configPath };
+  }
+  writeFileAtomic(configPath, next);
+  return { surface: "mcp", action: "written", path: configPath };
+}
+
+export function removeCodexMcp(opts: { cwd: string }): SurfaceOutcome {
+  const configPath = codexConfigPath(opts.cwd);
+  let text: string;
+  try {
+    text = fs.readFileSync(configPath, "utf-8");
+  } catch {
+    return { surface: "mcp", action: "absent", path: configPath };
+  }
+  if (!hasOurSection(text)) {
+    return { surface: "mcp", action: "absent", path: configPath };
+  }
+  const foreign = withoutOurSections(text.split("\n"));
+  if (foreign.every((l) => l.trim() === "")) {
+    // nothing but our block lived here — leave the cwd exactly as found
+    fs.unlinkSync(configPath);
+    return { surface: "mcp", action: "removed", path: configPath, detail: "file removed (empty after our block)" };
+  }
+  writeFileAtomic(configPath, `${foreign.join("\n")}\n`);
+  return { surface: "mcp", action: "removed", path: configPath };
+}
+
+export function provisionCodexPeer(opts: { cwd: string; port: number }): SurfaceOutcome[] {
+  return [mergeCodexMcp(opts)];
+}
+
+export function unprovisionCodexPeer(opts: { cwd: string }): SurfaceOutcome[] {
+  return [removeCodexMcp(opts)];
+}
+
+/** Read-only drift check (verify's eye, D3): the expected block must sit in
+ *  the project-local config byte-exact. */
+export function checkCodexPeer(opts: {
+  cwd: string;
+  port: number;
+}): Array<{ surface: SurfaceOutcome["surface"]; ok: boolean; detail: string }> {
+  const configPath = codexConfigPath(opts.cwd);
+  let text: string;
+  try {
+    text = fs.readFileSync(configPath, "utf-8");
+  } catch {
+    return [{ surface: "mcp", ok: false, detail: `no codex config at ${configPath}` }];
+  }
+  const expected = expectedCodexBlock(opts.port);
+  const ok = text.includes(expected);
+  return [
+    ok
+      ? { surface: "mcp", ok: true, detail: `[${CODEX_MCP_SECTION}] block in place` }
+      : hasOurSection(text)
+        ? { surface: "mcp", ok: false, detail: `[${CODEX_MCP_SECTION}] block drifted in ${configPath}` }
+        : { surface: "mcp", ok: false, detail: `[${CODEX_MCP_SECTION}] block missing in ${configPath}` },
+  ];
+}