@indigoai-us/hq-cli 5.49.0 → 5.50.1

package/src/commands/mcp-registration.ts

@@ -0,0 +1,2612 @@
+/**
+ * MCP registration — the safe-write substrate for user-global config merges (US-006).
+ *
+ * Symlink contributions (workers, knowledge, skills, commands, hooks, policies,
+ * scripts) reach the host via a single `ln -s` into a well-known directory. The
+ * `mcp` key is DIFFERENT: it is `wire: 'merge'` in the single-source
+ * `CONTRIBUTION_TABLE`, meaning its per-server manifests are MERGED into the
+ * shared Claude (JSON) + Codex (TOML) agent configs rather than symlinked. A
+ * merge contribution must NEVER be symlinked — doing so would dump raw manifest
+ * JSON into a host directory instead of registering the server.
+ *
+ * This module ships the CRASH-SAFE, REVERSIBLE config-write CORE that every
+ * merge emitter (US-007 Claude/JSON, US-008 Codex/TOML, US-009 uninstall) builds
+ * on. Editing a user's `~/.claude.json` / `~/.mcp.json` / `~/.codex/config.toml`
+ * is the single highest-danger surface in the project: those files hold the
+ * user's OWN non-HQ servers (figma, paper, superhuman, vyg-internal). A botched
+ * write corrupts them and `hq rescue` cannot un-corrupt a user config (it rolls
+ * back the HQ tree, not `~/`). So the only remediation is the backup this module
+ * takes BEFORE the first byte is written.
+ *
+ * The substrate is format-agnostic: callers pass a `parse`/`serialize`/`assertEntry`
+ * triple ({@link ConfigFormat}) so the SAME read->lock->merge->write->verify
+ * machinery drives both the JSON (Claude) and TOML (Codex) emitters without
+ * duplicating the dangerous parts. {@link writeConfigAtomic} is the entry point.
+ *
+ * Safe-write algorithm (per the review-report §6.2 data-flow), run inside an
+ * advisory O_EXCL lock that is held across read->merge->write:
+ *
+ *   [0] acquire O_EXCL lock (~/.<file>.hqlock, stale-timeout + PID)
+ *   [1] backup target -> ~/.hq/backups/mcp/<iso>-<pack>/ (mode 0600), MANDATORY,
+ *       before the first write byte (reuses the hq rescue backup pattern)
+ *   [2] read(target): ENOENT -> empty doc; 0-byte/whitespace -> empty doc;
+ *       non-empty parse error -> ConfigParseError ABORT (write nothing, NEVER
+ *       regenerate-from-template); other read error -> ConfigPermissionError ABORT
+ *   [3] re-read INSIDE the lock (never carry a pre-lock parse) — closes the
+ *       concurrent-write race
+ *   [4..6] caller's merge fn transforms the doc; serialize via the format
+ *   [7] write temp file IN THE SAME DIR (mode 0600) -> fsync -> rename onto
+ *       REALPATH(target). For the ~/.mcp.json symlink: realpath FIRST, rename
+ *       onto the RESOLVED file, NEVER replace the link.
+ *   [8] verify: re-read + re-parse + assert entry present; on failure restore
+ *       from the [1] backup and raise PartialRegistrationError
+ *   [9] release lock (finally)
+ *
+ * Desired-state-convergence semantics: re-running is safe from ANY state,
+ * including PARTIAL — the merge is idempotent per surface, the backup is
+ * timestamped (never overwritten), and a crash leaves the original intact.
+ *
+ * US-007 (Claude/JSON) and US-008 (Codex/TOML) fill in the per-runtime EMITTERS
+ * on top of this core; {@link registerServer} fans one per-server manifest out
+ * across BOTH surfaces (Claude always; Codex when `~/.codex` exists, else a
+ * first-class skip), and {@link registerMcpServers} is the pack-install routing
+ * seam over it.
+ */
+
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+
+// ---------------------------------------------------------------------------
+// Named error classes (no bare catch-all anywhere in this module).
+//
+// Every failure mode the safe-write core can hit gets a distinct, instanceof-
+// checkable class with a stable `code`. The wider MCP feature surface
+// (US-007..US-013) also throws these, so they are all declared here once.
+// ---------------------------------------------------------------------------
+
+/** Base for every MCP-registration error; carries a stable machine-checkable `code`. */
+export abstract class McpRegistrationError extends Error {
+  abstract readonly code: string;
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+    // Restore the prototype chain across the TS->ES* `extends Error` downlevel so
+    // `instanceof` holds on the concrete subclass.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * A NON-EMPTY config file did not parse (hand-edited / corrupted). The safe-write
+ * core ABORTS on this — it writes NOTHING and NEVER regenerates from a template,
+ * so a user's figma/superhuman/paper entries can never be clobbered by a
+ * regenerate-on-parse-error path.
+ */
+export class ConfigParseError extends McpRegistrationError {
+  readonly code = 'ConfigParseError' as const;
+}
+
+/**
+ * A read error that is NOT ENOENT (e.g. EACCES, broken symlink, EISDIR). The
+ * safe-write core ABORTS — it does not guess, does not fabricate, does not
+ * overwrite.
+ */
+export class ConfigPermissionError extends McpRegistrationError {
+  readonly code = 'ConfigPermissionError' as const;
+}
+
+/**
+ * A server name is already present in the target config with a DIFFERENT
+ * definition than the one being merged (def-equal = idempotent no-op;
+ * def-differs = this error). Emitters (US-007/008) raise it; declared here so
+ * the whole feature shares one taxonomy.
+ */
+export class McpNameCollisionError extends McpRegistrationError {
+  readonly code = 'McpNameCollisionError' as const;
+}
+
+/**
+ * The Codex runtime is absent (`~/.codex` missing). This is a FIRST-CLASS SKIP,
+ * not a crash and NEVER a mkdir-p-fabricate. Thrown only where a caller needs to
+ * distinguish "Codex not installed" from a real error; the substrate exposes
+ * {@link codexHome} + {@link codexConfigPath} so emitters can branch on absence
+ * without ever creating the directory.
+ */
+export class CodexNotInstalledError extends McpRegistrationError {
+  readonly code = 'CodexNotInstalledError' as const;
+}
+
+/** A per-server MCP manifest failed shape/transport validation. */
+export class McpManifestError extends McpRegistrationError {
+  readonly code = 'McpManifestError' as const;
+}
+
+/**
+ * Verify-after-write found the merged entry MISSING or the file unreadable after
+ * the atomic rename — a partial/torn registration. The substrate restores the
+ * target from the pre-write backup before raising this, so the file is left in
+ * its original state, never a half-written one.
+ */
+export class PartialRegistrationError extends McpRegistrationError {
+  readonly code = 'PartialRegistrationError' as const;
+  /** The backup directory the target was (or could be) restored from. */
+  readonly backupDir: string | undefined;
+  constructor(message: string, backupDir?: string) {
+    super(message);
+    this.backupDir = backupDir;
+  }
+}
+
+/**
+ * Thrown by not-yet-implemented seams (the US-007/US-008 Claude/Codex emitters).
+ * Carries a stable `code` so callers/tests can identify it without string-
+ * matching the message, and a `story` for at-a-glance attribution. KEPT from the
+ * US-005 seam: the merge EMITTERS are still pending after US-006 (which ships the
+ * safe-write substrate beneath them).
+ */
+export class NotImplementedError extends Error {
+  /** Stable, machine-checkable discriminator. */
+  readonly code = 'NotImplemented' as const;
+  /** The PRD story that lands the real implementation. */
+  readonly story: string;
+  constructor(message: string, story = 'US-007') {
+    super(message);
+    this.name = 'NotImplementedError';
+    this.story = story;
+    Object.setPrototypeOf(this, NotImplementedError.prototype);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Injectable base paths.
+//
+// EVERY path the substrate touches derives from a single `home` (the user's
+// home directory). Production resolves it from `os.homedir()`; TESTS pass an
+// explicit tmpdir so they NEVER read, write, back up, or lock the developer's
+// real ~/.claude.json, ~/.mcp.json, or ~/.codex/config.toml. This is a hard
+// safety requirement — there is no code path that touches `~` without going
+// through a resolved `home`.
+// ---------------------------------------------------------------------------
+
+/** Roots the substrate's view of the filesystem; everything is derived from `home`. */
+export interface SafeWriteEnv {
+  /** The user home directory. Tests MUST pass a tmpdir here. */
+  home: string;
+}
+
+/** Resolve the env, defaulting `home` to the real `os.homedir()` for production callers. */
+export function resolveEnv(env?: Partial<SafeWriteEnv>): SafeWriteEnv {
+  const home = env?.home ?? os.homedir();
+  if (!home) {
+    throw new ConfigPermissionError(
+      'cannot resolve a home directory for MCP config writes (os.homedir() returned empty)',
+    );
+  }
+  return { home };
+}
+
+/** `~/.hq/backups/mcp` — the timestamped backup root (reuses the hq rescue location). */
+export function backupRoot(env: SafeWriteEnv): string {
+  return path.join(env.home, '.hq', 'backups', 'mcp');
+}
+
+// ---------------------------------------------------------------------------
+// Append-only audit log (US-011).
+//
+// Every register AND every unregister appends exactly ONE JSONL line PER SURFACE
+// acted on to `~/.hq/logs/mcp-registry.log`. The log is the durable provenance
+// trail a corrupted/PARTIAL config can be reconstructed from: each line names the
+// action, pack, server, transport, target, the file written, and a sha256 of the
+// whole config file CONTENTS before/after the write (prevHash/newHash) — which
+// proves a mutation WITHOUT leaking content. No Bearer/secret VALUE ever appears
+// in a line (the `target` field is a url or command, never a header).
+// ---------------------------------------------------------------------------
+
+/** `~/.hq/logs/mcp-registry.log` — the append-only JSONL audit log (mirrors backupRoot style). */
+export function mcpRegistryLogPath(env: SafeWriteEnv): string {
+  return path.join(env.home, '.hq', 'logs', 'mcp-registry.log');
+}
+
+/** The action recorded on an audit line. */
+export type AuditAction = 'register' | 'unregister';
+
+/**
+ * The result recorded on an audit line:
+ *   - `registered`   — a register write that changed the file.
+ *   - `unregistered` — an unregister write that removed an entry (file changed).
+ *   - `noop`         — an idempotent no-op (changed:false; prevHash === newHash).
+ *   - `skipped`      — a surface deliberately not acted on (e.g. Codex absent, or a
+ *                      foreign/unstamped entry left in place). PARTIAL is auditable.
+ *   - `error`        — the surface emit threw (the operation failed for this surface).
+ */
+export type AuditResult = 'registered' | 'unregistered' | 'noop' | 'skipped' | 'error';
+
+/**
+ * One append-only audit-log entry. EXACT shape (field order is the JSON key order):
+ *   `{ ts, action, pack, server, transport, target, file, prevHash, newHash, result }`.
+ * `target` is a url (http/sse) or command(+args) (stdio) — NEVER a header/secret.
+ * `prevHash`/`newHash` are sha256 (hex) of the config file bytes before/after the
+ * write ('' when the file is absent).
+ */
+export interface AuditLogEntry {
+  /** ISO8601 timestamp (`new Date().toISOString()`). */
+  ts: string;
+  /** `register` | `unregister`. */
+  action: AuditAction;
+  /** The pack name. */
+  pack: string;
+  /** The bare server name. */
+  server: string;
+  /** The transport (`http` | `stdio` | `sse` | `unknown`). */
+  transport: string;
+  /** url (http/sse) or command(+args joined) (stdio); '' when unknown. NEVER a secret. */
+  target: string;
+  /** The realpath the surface wrote to, or the config path for a skip; '' when none. */
+  file: string;
+  /** sha256 (hex) of the config file bytes BEFORE the write, or '' when absent. */
+  prevHash: string;
+  /** sha256 (hex) of the config file bytes AFTER the write, or '' when removed/absent. */
+  newHash: string;
+  /** registered | unregistered | noop | skipped | error. */
+  result: AuditResult;
+}
+
+/**
+ * sha256 (hex) of a file's CONTENTS, or '' when the file is absent/unreadable.
+ * Hashing the WHOLE file is intentional — it proves a mutation happened without
+ * leaking any content into the audit log.
+ */
+export function hashFileContents(target: string): string {
+  try {
+    const data = fs.readFileSync(realpathOrSelf(target));
+    return crypto.createHash('sha256').update(data).digest('hex');
+  } catch {
+    // ENOENT (and any read failure) => no hash. Best-effort by design.
+    return '';
+  }
+}
+
+/**
+ * Append EXACTLY ONE JSON line (`JSON.stringify(entry) + '\n'`) to
+ * `~/.hq/logs/mcp-registry.log`, creating `~/.hq/logs/` as needed. BEST-EFFORT /
+ * NEVER-THROWS: a logging failure must NEVER break (or corrupt) the real
+ * register/unregister operation, so every error is swallowed. The `target` field
+ * is defensively passed through {@link redactSecrets} against the supplied
+ * `secrets` set (normally empty — `target` is a url/command, never a header).
+ *
+ * @param env     the resolved env (tests pass a tmpdir home).
+ * @param entry   the {@link AuditLogEntry} to append.
+ * @param secrets resolved secret plaintexts to defensively redact from `target`.
+ */
+export function appendAuditLog(
+  env: SafeWriteEnv,
+  entry: AuditLogEntry,
+  secrets: Iterable<string> = [],
+): void {
+  try {
+    const safeTarget = redactSecrets(entry.target, secrets);
+    const line = `${JSON.stringify({ ...entry, target: safeTarget })}\n`;
+    const logPath = mcpRegistryLogPath(env);
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    // 0600 file mode (nice-to-have): the audit log records pack/server/file paths.
+    fs.appendFileSync(logPath, line, { mode: 0o600 });
+  } catch {
+    // Best-effort: a broken log must never corrupt the real operation. Swallow.
+  }
+}
+
+/** `~/.codex` — its ABSENCE is a first-class skip signal (never fabricated). */
+export function codexHome(env: SafeWriteEnv): string {
+  return path.join(env.home, '.codex');
+}
+
+/** `~/.codex/config.toml` — the GLOBAL Codex MCP config (not the project file). */
+export function codexConfigPath(env: SafeWriteEnv): string {
+  return path.join(codexHome(env), 'config.toml');
+}
+
+/** True iff the Codex runtime is installed (`~/.codex` exists). Never creates it. */
+export function isCodexInstalled(env: SafeWriteEnv): boolean {
+  try {
+    return fs.statSync(codexHome(env)).isDirectory();
+  } catch {
+    // ENOENT (and any stat failure) => treat as not installed; never fabricate.
+    return false;
+  }
+}
+
+/** `~/.claude.json` — the PINNED single Claude surface (top-level mcpServers). */
+export function claudeConfigPath(env: SafeWriteEnv): string {
+  return path.join(env.home, '.claude.json');
+}
+
+/** `~/.mcp.json` — the project-pinned Claude surface (a symlink on this host). */
+export function mcpJsonPath(env: SafeWriteEnv): string {
+  return path.join(env.home, '.mcp.json');
+}
+
+// ---------------------------------------------------------------------------
+// Read path (the SHADOW cases from review-report §6.2).
+// ---------------------------------------------------------------------------
+
+/** Outcome of {@link readConfigDoc}: a parsed doc plus whether the file pre-existed. */
+export interface ReadConfigResult<T> {
+  /** The parsed doc, or the `emptyDoc` when the file is absent/empty. */
+  doc: T;
+  /** False when the file did not exist (ENOENT) or was 0-byte/whitespace. */
+  existed: boolean;
+}
+
+/**
+ * A config format: how to parse a file's text into a doc, serialize a doc back
+ * to text, and assert a named entry is present after a write. Lets the SAME
+ * safe-write core drive JSON (Claude) and TOML (Codex) without duplicating the
+ * dangerous read/lock/backup/verify parts.
+ *
+ * `parse` MUST throw on malformed NON-EMPTY input (the core maps that throw to
+ * {@link ConfigParseError} and ABORTS). `emptyDoc` is the doc to use when the
+ * file is absent or blank.
+ */
+export interface ConfigFormat<T> {
+  /** Parse non-empty file text into a doc; throw on malformed input. */
+  parse: (text: string) => T;
+  /** Serialize a doc back to file text. */
+  serialize: (doc: T) => string;
+  /** The doc representing an empty/new container (ENOENT or blank file). */
+  emptyDoc: () => T;
+  /** Throw iff `name` is NOT present (and well-formed) in `doc` — drives verify-after-write. */
+  assertEntry: (doc: T, name: string) => void;
+}
+
+/**
+ * Built-in JSON {@link ConfigFormat} for the Claude surfaces. Pretty-prints with
+ * a trailing newline; an empty doc is `{}`. Parsing the empty string is the
+ * caller's responsibility (the core normalizes blank files to `emptyDoc` BEFORE
+ * calling `parse`), so `parse` here always sees non-empty text.
+ */
+export const jsonFormat: ConfigFormat<Record<string, unknown>> = {
+  parse(text: string): Record<string, unknown> {
+    const v = JSON.parse(text);
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+      throw new Error('top-level JSON value must be an object');
+    }
+    return v as Record<string, unknown>;
+  },
+  serialize(doc: Record<string, unknown>): string {
+    return `${JSON.stringify(doc, null, 2)}\n`;
+  },
+  emptyDoc(): Record<string, unknown> {
+    return {};
+  },
+  assertEntry(): void {
+    // Default: presence is asserted by the caller-supplied format for a real
+    // emitter. The base JSON format is structure-only; emitters (US-007) pass a
+    // format whose assertEntry checks `doc.mcpServers[name]`.
+    throw new Error('jsonFormat.assertEntry is a placeholder — emitters supply a real one');
+  },
+};
+
+/**
+ * Read + parse a config file, normalizing the SHADOW cases (review-report §6.2):
+ *
+ *   - SHADOW A: ENOENT -> { doc: emptyDoc, existed: false }   (fresh host / Codex absent)
+ *   - SHADOW B: 0-byte / whitespace-only -> { doc: emptyDoc, existed: false }
+ *   - SHADOW C: NON-EMPTY + parse error -> throw {@link ConfigParseError} (ABORT,
+ *               write nothing, never regenerate-from-template)
+ *   - SHADOW D: any OTHER read error (EACCES, EISDIR, broken symlink) ->
+ *               throw {@link ConfigPermissionError} (ABORT)
+ *
+ * @param target the config file path (a symlink is read THROUGH transparently)
+ * @param format the {@link ConfigFormat} (parser + empty-doc factory)
+ */
+export function readConfigDoc<T>(target: string, format: ConfigFormat<T>): ReadConfigResult<T> {
+  let text: string;
+  try {
+    text = fs.readFileSync(target, 'utf-8');
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === 'ENOENT') {
+      // SHADOW A: fresh host / Codex absent — a new, empty container.
+      return { doc: format.emptyDoc(), existed: false };
+    }
+    // SHADOW D: EACCES / EISDIR / ELOOP (broken symlink) / anything else — ABORT.
+    throw new ConfigPermissionError(
+      `cannot read config ${target}: ${err.code ?? 'read error'} (${err.message})`,
+    );
+  }
+
+  // SHADOW B: 0-byte or whitespace-only — normalize to the empty doc.
+  if (text.trim().length === 0) {
+    return { doc: format.emptyDoc(), existed: false };
+  }
+
+  // SHADOW C: non-empty but unparseable — ABORT, never clobber.
+  try {
+    return { doc: format.parse(text), existed: true };
+  } catch (e) {
+    // SECURITY (US-013, HIGH-finding fix): a parser's error message can embed the
+    // OFFENDING SOURCE LINES of the file (a context snippet). `smol-toml` does
+    // EXACTLY this — `Invalid TOML document: <reason>\n\nN:  <source line>\n    ^`.
+    // Those embedded source lines can contain arbitrary on-disk bytes, INCLUDING a
+    // PRE-EXISTING user secret we cannot enumerate (it is not one of the secrets we
+    // are registering, so the register-path `redactSecrets(e.message, secretSink)`
+    // cannot scrub it — `secretSink` holds only the CURRENTLY-registering secrets).
+    // This message propagates to stderr/logs, so echoing it verbatim leaks the
+    // on-disk secret. We sanitize at the construction site: keep only the
+    // STRUCTURAL reason (parser error type/position), drop the quoted source-context
+    // snippet entirely. Secrecy WINS over diagnostics. (JSON.parse does not echo
+    // file content, so the Claude surface was already safe; this hardens BOTH.)
+    throw new ConfigParseError(
+      `refusing to write: existing config ${target} is not valid and would be clobbered ` +
+        `(parse failed: ${sanitizeParserMessage((e as Error).message)}). Fix or remove the file ` +
+        'by hand; HQ will not regenerate it from a template.',
+    );
+  }
+}
+
+/**
+ * Strip a parser error message down to its STRUCTURAL reason, dropping any embedded
+ * SOURCE-CONTEXT lines so on-disk file bytes (which may include an unenumerable
+ * pre-existing secret) can never leak into a {@link ConfigParseError} message.
+ *
+ * `smol-toml` formats its error as:
+ *
+ *   Invalid TOML document: <structural reason>
+ *   <blank line>
+ *   <N>:  <verbatim source line>            ← can contain a secret
+ *   <M>:  <verbatim source line>            ← can contain a secret
+ *       ^                                   ← caret pointer
+ *
+ * We keep ONLY the lines up to the first blank line (the structural reason, e.g.
+ * `Invalid TOML document: only letter, numbers, dashes and underscores are allowed
+ * in keys`) and discard the source snippet + caret. As belt-and-suspenders, any
+ * surviving line that still looks like quoted content or a `Bearer <token>` value
+ * is redacted, so even a parser whose reason inlines a value (rather than a
+ * separate snippet block) cannot leak. The result never contains raw file content.
+ */
+export function sanitizeParserMessage(message: string): string {
+  // 1. Cut at the first blank line: smol-toml's source-context snippet (and caret)
+  //    always follows a blank-line separator, so everything before it is the
+  //    structural reason and everything after is verbatim file bytes.
+  const beforeBlank = message.split(/\n[ \t]*\n/, 1)[0] ?? message;
+  // 2. Additionally drop any line that looks like a quoted source line
+  //    (`N:  ...` numbered context) in case a parser omits the blank separator.
+  const structural = beforeBlank
+    .split('\n')
+    .filter((line) => !/^\s*\d+:\s/.test(line) && line.trim() !== '^')
+    .join(' ')
+    .trim();
+  // 3. Belt-and-suspenders: redact any `Bearer <token>` or quoted-string-shaped
+  //    substring that survived, so a value inlined into the reason cannot leak.
+  const redactedBearer = structural.replace(
+    /\bBearer\s+\S+/gi,
+    `Bearer ${SECRET_REDACTION}`,
+  );
+  const redactedQuoted = redactedBearer.replace(/"[^"]*"/g, `"${SECRET_REDACTION}"`);
+  return redactedQuoted.length > 0 ? redactedQuoted : 'parse error (details withheld)';
+}
+
+// ---------------------------------------------------------------------------
+// Advisory O_EXCL lock (held across read->merge->write).
+// ---------------------------------------------------------------------------
+
+/** Default stale-lock timeout — a lock older than this whose PID is dead is broken. */
+export const DEFAULT_LOCK_STALE_MS = 30_000;
+
+/** Default total time to wait for a held lock before giving up. */
+export const DEFAULT_LOCK_WAIT_MS = 10_000;
+
+/** A held advisory lock; release with {@link releaseLock} (idempotent). */
+export interface ConfigLock {
+  /** The lockfile path (`~/.<basename>.hqlock`). */
+  lockPath: string;
+}
+
+/** Options for {@link acquireLock} — overridable so tests can use tiny timeouts. */
+export interface AcquireLockOptions {
+  /** Age beyond which a dead-PID lock is considered stale + breakable. */
+  staleMs?: number;
+  /** Total time to spin waiting for a live lock before throwing. */
+  waitMs?: number;
+  /** Poll interval while waiting. */
+  pollMs?: number;
+  /** Injectable "is this PID alive?" check (tests stub it; prod uses `kill -0`). */
+  isPidAlive?: (pid: number) => boolean;
+  /** Injectable clock (tests). */
+  now?: () => number;
+}
+
+/** The lockfile path for a target: `~/.<basename>.hqlock` (a sibling, hidden). */
+export function lockPathFor(target: string): string {
+  const dir = path.dirname(target);
+  const base = path.basename(target);
+  // `~/.claude.json` -> `~/..claude.json.hqlock` is ugly; collapse a leading dot
+  // so the lock for a dotfile reads `~/.claude.json.hqlock`.
+  const stem = base.startsWith('.') ? base.slice(1) : base;
+  return path.join(dir, `.${stem}.hqlock`);
+}
+
+/** Default PID-liveness check (Unix `kill(pid, 0)` semantics via `process.kill`). */
+function defaultIsPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // ESRCH = no such process (dead); EPERM = alive but not ours (still alive).
+    return (e as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/**
+ * Acquire an advisory O_EXCL lock for `target`, held across the whole
+ * read->merge->write cycle so a concurrent register cannot interleave and lose a
+ * write. Behavior:
+ *
+ *   - `O_EXCL | O_CREAT` create-or-fail; on EEXIST another holder exists.
+ *   - A held lock whose PID is DEAD and whose mtime is older than `staleMs` is
+ *     broken (unlinked) and re-acquired.
+ *   - A held lock whose PID is ALIVE (or fresh) is waited on up to `waitMs`; if
+ *     it never frees, this throws (the concurrent register ABORTS rather than
+ *     racing — the first writer's work is preserved).
+ *
+ * The lockfile body is the holder's PID + an ISO timestamp (diagnostic).
+ */
+export function acquireLock(target: string, opts: AcquireLockOptions = {}): ConfigLock {
+  const lockPath = lockPathFor(target);
+  const staleMs = opts.staleMs ?? DEFAULT_LOCK_STALE_MS;
+  const waitMs = opts.waitMs ?? DEFAULT_LOCK_WAIT_MS;
+  const pollMs = opts.pollMs ?? 50;
+  const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
+  const now = opts.now ?? Date.now;
+
+  const deadline = now() + waitMs;
+  const body = `${process.pid}\n${new Date().toISOString()}\n`;
+
+  // Spin until we win the O_EXCL create, break a stale lock, or time out.
+  for (;;) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx', 0o600); // wx = O_CREAT|O_EXCL|O_WRONLY
+      try {
+        fs.writeSync(fd, body);
+      } finally {
+        fs.closeSync(fd);
+      }
+      return { lockPath };
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code !== 'EEXIST') {
+        // A real failure creating the lock (e.g. EACCES on the dir) — surface it.
+        throw new ConfigPermissionError(
+          `cannot acquire lock ${lockPath}: ${err.code ?? 'open error'} (${err.message})`,
+        );
+      }
+      // EEXIST: a lock is held. Decide stale-break vs wait.
+      if (tryBreakStaleLock(lockPath, staleMs, isPidAlive, now)) {
+        continue; // broke it — retry the create immediately.
+      }
+      if (now() >= deadline) {
+        const holder = readLockHolder(lockPath);
+        throw new ConfigPermissionError(
+          `config ${target} is locked by ${holder} and did not release within ${waitMs}ms; ` +
+            'aborting rather than racing a concurrent registration (the in-flight write is preserved).',
+        );
+      }
+      sleepMs(pollMs);
+    }
+  }
+}
+
+/** Release a held lock. Idempotent — a missing lockfile is not an error. */
+export function releaseLock(lock: ConfigLock): void {
+  try {
+    fs.unlinkSync(lock.lockPath);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e;
+  }
+}
+
+/** Read the PID written into a lockfile, or NaN if unreadable/garbage. */
+function readLockPid(lockPath: string): number {
+  try {
+    const first = fs.readFileSync(lockPath, 'utf-8').split('\n', 1)[0]?.trim() ?? '';
+    return Number.parseInt(first, 10);
+  } catch {
+    return Number.NaN;
+  }
+}
+
+/** A human-readable "pid N (since …)" description of the current lock holder. */
+function readLockHolder(lockPath: string): string {
+  try {
+    const [pidLine, tsLine] = fs.readFileSync(lockPath, 'utf-8').split('\n');
+    return `pid ${pidLine?.trim() || '?'}${tsLine ? ` (since ${tsLine.trim()})` : ''}`;
+  } catch {
+    return 'an unknown process';
+  }
+}
+
+/**
+ * If the lock at `lockPath` is stale (holder PID dead AND mtime older than
+ * `staleMs`), unlink it and return true. Otherwise return false. A dead PID with
+ * a FRESH mtime is NOT broken (the holder may have just started and not yet
+ * recorded a live PID under our liveness check), guarding against TOCTOU.
+ */
+function tryBreakStaleLock(
+  lockPath: string,
+  staleMs: number,
+  isPidAlive: (pid: number) => boolean,
+  now: () => number,
+): boolean {
+  let st: fs.Stats;
+  let originalBody: string;
+  try {
+    st = fs.statSync(lockPath);
+    // Capture the exact bytes we are judging. The lock body (pid + ISO timestamp)
+    // is unique per acquisition — a reuse-proof identity for THIS lock. Inode
+    // numbers alone are NOT: Linux recycles a just-freed inode on the next create,
+    // so an inode-only recheck can mistake a fresh lock for the stale one we
+    // inspected and unlink it (passes on macOS, fails on Linux CI).
+    originalBody = fs.readFileSync(lockPath, 'utf-8');
+  } catch {
+    // Vanished between EEXIST and here — the create will now succeed.
+    return true;
+  }
+  const age = now() - st.mtimeMs;
+  const pid = readLockPid(lockPath);
+  const holderAlive = Number.isFinite(pid) && isPidAlive(pid);
+  if (holderAlive) return false; // live holder — must wait, never steal.
+  if (age < staleMs) return false; // dead PID but fresh — be conservative, wait.
+  // Dead holder + stale mtime: break it — but IDENTITY-SAFELY. `unlinkSync(path)`
+  // is not atomic with the stat/read that justified breaking it: between them a
+  // third contender may have removed the stale lock and created a FRESH, valid
+  // one at the same path (and, on Linux, the same recycled inode). Re-read and
+  // require BOTH (inode+dev) AND the exact body to still match before unlinking,
+  // so we only ever remove the precise stale lock we inspected — never an
+  // unrelated fresh one. (The O_EXCL re-create is still the true mutual-exclusion
+  // guard; this just prevents a spurious break of someone else's lock.)
+  try {
+    const recheck = fs.statSync(lockPath);
+    const currentBody = fs.readFileSync(lockPath, 'utf-8');
+    if (
+      recheck.ino !== st.ino ||
+      recheck.dev !== st.dev ||
+      currentBody !== originalBody
+    ) {
+      // The lock at this path is no longer the one we judged stale — leave it.
+      return false;
+    }
+    fs.unlinkSync(lockPath);
+  } catch (e) {
+    // ENOENT => already gone (a concurrent breaker won); the create will succeed.
+    if ((e as NodeJS.ErrnoException).code !== 'ENOENT') return false;
+  }
+  return true;
+}
+
+/** Busy-sleep for `ms` (small poll intervals only — bounded by the wait deadline). */
+function sleepMs(ms: number): void {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    // Atomics.wait on a throwaway buffer yields a real, CPU-cheap sleep without
+    // making the function async (the lock loop is synchronous by design).
+    try {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(1, end - Date.now()));
+      return;
+    } catch {
+      // SharedArrayBuffer unavailable — fall back to a tight spin (rare).
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Backup (reuses the hq rescue backup pattern: ~/.hq/backups/<stamp>-<tag>/).
+// ---------------------------------------------------------------------------
+
+/** UTC `YYYY-MM-DDTHH-MM-SSZ` (dash-separated) — the hq rescue timestamp format. */
+export function rescueStamp(d: Date = new Date()): string {
+  const p = (n: number, w = 2) => String(n).padStart(w, '0');
+  return (
+    `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())}` +
+    `T${p(d.getUTCHours())}-${p(d.getUTCMinutes())}-${p(d.getUTCSeconds())}Z`
+  );
+}
+
+/**
+ * Back up `target` into `~/.hq/backups/mcp/<iso>-<pack>/` BEFORE the first write
+ * byte, mirroring the hq rescue snapshot. The backup copy is mode 0600. Returns
+ * the backup DIRECTORY (the restore target for verify-after-write).
+ *
+ * If `target` does not exist (fresh host), the backup dir is still created (so
+ * the restore path is always valid) but holds a `.absent` marker instead of a
+ * copy — restoring "absent" means unlinking the target.
+ *
+ * The backup is taken on the REALPATH of the target so a symlink (`~/.mcp.json`)
+ * is backed up by its resolved contents, never the link.
+ */
+export function backupConfig(
+  env: SafeWriteEnv,
+  target: string,
+  pack: string,
+  stamp: string = rescueStamp(),
+): string {
+  const safePack = pack.replace(/[^a-zA-Z0-9._@-]/g, '_') || 'pack';
+  const dir = path.join(backupRoot(env), `${stamp}-${safePack}`);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const real = realpathOrSelf(target);
+  const dest = path.join(dir, path.basename(real));
+  try {
+    const data = fs.readFileSync(real);
+    fs.writeFileSync(dest, data, { mode: 0o600 });
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+      // Nothing to copy — record absence so restore knows to unlink.
+      fs.writeFileSync(path.join(dir, '.absent'), `${real}\n`, { mode: 0o600 });
+    } else {
+      throw new ConfigPermissionError(
+        `cannot back up ${real} before write: ${(e as Error).message}`,
+      );
+    }
+  }
+  return dir;
+}
+
+/**
+ * Restore `target` from a {@link backupConfig} directory. If the backup recorded
+ * absence (the `.absent` marker), the target is unlinked (returning it to "did
+ * not exist"); otherwise the backed-up bytes are written back atomically onto
+ * the realpath. Used by verify-after-write on failure.
+ */
+export function restoreFromBackup(target: string, backupDir: string): void {
+  const real = realpathOrSelf(target);
+  const absentMarker = path.join(backupDir, '.absent');
+  if (fs.existsSync(absentMarker)) {
+    try {
+      fs.unlinkSync(real);
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e;
+    }
+    return;
+  }
+  const src = path.join(backupDir, path.basename(real));
+  const data = fs.readFileSync(src);
+  atomicReplace(real, data);
+}
+
+// ---------------------------------------------------------------------------
+// Atomic write (temp-in-same-dir + fsync + rename onto REALPATH).
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve `p` to its canonical real path. If `p` (or a path component) does not
+ * exist, fall back to `p` unchanged (a brand-new file has no realpath yet but we
+ * still write at its intended location). A symlink whose TARGET is missing
+ * (broken link) resolves the link itself to its dangling target so we never
+ * replace the link.
+ */
+export function realpathOrSelf(p: string, _depth = 0): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    // The file itself may not exist yet, but if it's a symlink we still want to
+    // write onto its TARGET, never replace the link. Resolve the link target by
+    // hand when the final component is a symlink with a dangling target.
+    //
+    // Depth guard: a CYCLIC broken chain (a -> b -> a) would otherwise recurse
+    // forever and blow the stack. Cap at a generous hop count and, on overflow,
+    // fall back to canonicalizing the literal path's parent.
+    if (_depth < 40) {
+      try {
+        const lst = fs.lstatSync(p);
+        if (lst.isSymbolicLink()) {
+          const linkTarget = fs.readlinkSync(p);
+          const resolved = path.isAbsolute(linkTarget)
+            ? linkTarget
+            : path.join(path.dirname(p), linkTarget);
+          // RECURSE so an N-hop (possibly partially-broken) chain is followed all
+          // the way to the final real target — we must rename onto that target,
+          // never onto an intermediate link.
+          return realpathOrSelf(resolved, _depth + 1);
+        }
+      } catch {
+        // Not a symlink (or unreadable) — write at the literal path.
+      }
+    }
+    return realpathParentOf(p);
+  }
+}
+
+/** Canonicalize a path's PARENT dir (which must exist) and re-append the basename. */
+function realpathParentOf(p: string): string {
+  try {
+    const parent = fs.realpathSync(path.dirname(p));
+    return path.join(parent, path.basename(p));
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Atomically replace `realTarget` with `data`: write a temp file IN THE SAME DIR
+ * (mode 0600), fsync the FILE, rename onto `realTarget`, then fsync the
+ * DIRECTORY. The temp lives in the same directory so the rename is a same-
+ * filesystem atomic operation — a crash either leaves the original wholly intact
+ * or the new file wholly in place, never a torn write. The trailing directory
+ * fsync persists the rename itself: without it, a power-loss can lose the rename
+ * metadata even though the file bytes were flushed, silently reverting the write.
+ *
+ * `realTarget` MUST already be a realpath (caller resolves symlinks first) so we
+ * rename onto the RESOLVED file and NEVER replace a symlink with a regular file.
+ */
+export function atomicReplace(realTarget: string, data: string | Buffer): void {
+  const dir = path.dirname(realTarget);
+  const tmp = path.join(dir, `.${path.basename(realTarget)}.tmp.${process.pid}.${Date.now()}`);
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o600); // O_CREAT|O_EXCL — never clobber a stray temp.
+    fs.writeSync(fd, typeof data === 'string' ? Buffer.from(data, 'utf-8') : data);
+    fs.fsyncSync(fd); // durability: flush bytes before the rename commits.
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(tmp, realTarget); // atomic same-FS commit.
+    fsyncDir(dir); // persist the rename metadata so a crash can't lose it.
+  } catch (e) {
+    // Clean up the temp on any failure so a crashed write leaves no litter.
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* already closed */
+      }
+    }
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* temp may not exist */
+    }
+    throw e;
+  }
+}
+
+/**
+ * fsync a DIRECTORY so a rename into it is durable. Best-effort: some platforms
+ * (notably Windows, and some network filesystems) reject `fsync` on a directory
+ * fd with EISDIR/EBADF/EPERM/EINVAL — in that case the rename is still committed
+ * to the FS as far as the OS allows, so we swallow the error rather than abort an
+ * otherwise-good write. Never throws.
+ */
+function fsyncDir(dir: string): void {
+  let dirFd: number | undefined;
+  try {
+    dirFd = fs.openSync(dir, 'r');
+    fs.fsyncSync(dirFd);
+  } catch {
+    // Directory fsync unsupported on this platform/FS — best-effort only.
+  } finally {
+    if (dirFd !== undefined) {
+      try {
+        fs.closeSync(dirFd);
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// writeConfigAtomic — the full safe-write entry point ([0]..[9]).
+// ---------------------------------------------------------------------------
+
+/** Options for {@link writeConfigAtomic}. */
+export interface WriteConfigOptions<T> {
+  /** The config file to merge into (a symlink is resolved before the rename). */
+  target: string;
+  /** The pack name — labels the backup directory. */
+  pack: string;
+  /** The format (parser/serializer/assertEntry) for `target`. */
+  format: ConfigFormat<T>;
+  /**
+   * Pure merge: receive the current doc, return the NEXT doc. MUST NOT mutate the
+   * input in a way that survives a throw — the substrate re-reads inside the lock
+   * and calls this on the locked doc, so it should be deterministic. Throwing
+   * (e.g. {@link McpNameCollisionError}) aborts the write cleanly.
+   */
+  merge: (doc: T) => T;
+  /** The server name to assert present after the write (verify-after-write). */
+  assertName: string;
+  /** Injectable env (tests pass a tmpdir home). */
+  env?: Partial<SafeWriteEnv>;
+  /** Lock tuning (tests use tiny timeouts). */
+  lock?: AcquireLockOptions;
+  /** Backup timestamp override (tests / deterministic naming). */
+  stamp?: string;
+}
+
+/** Result of a successful {@link writeConfigAtomic}. */
+export interface WriteConfigResult {
+  /** Whether the file changed (false = idempotent no-op; the merge returned an equal doc). */
+  changed: boolean;
+  /** The backup directory taken before the write (restore target). */
+  backupDir: string;
+  /** The realpath the bytes were written to (resolved symlink). */
+  realTarget: string;
+}
+
+/**
+ * Crash-safe, reversible, lock-guarded merge-write of one entry into a
+ * user-global agent config. Implements the full review-report §6.2 algorithm:
+ * lock -> backup -> read (shadow-normalized) -> RE-READ in lock -> merge ->
+ * serialize -> atomic temp+fsync+rename onto realpath -> verify -> restore on
+ * failure. Releases the lock in `finally`.
+ *
+ * Idempotent: if `merge` returns a doc byte-identical (post-serialize) to the
+ * current file, no write happens (`changed: false`) — re-runs from ANY state,
+ * including PARTIAL, are safe.
+ *
+ * @throws ConfigParseError       existing non-empty file is unparseable (ABORT, nothing written)
+ * @throws ConfigPermissionError  read/lock failure other than ENOENT (ABORT)
+ * @throws PartialRegistrationError verify-after-write failed; target restored from backup
+ * @throws (whatever `merge` throws, e.g. McpNameCollisionError) — aborts before any write
+ */
+export function writeConfigAtomic<T>(opts: WriteConfigOptions<T>): WriteConfigResult {
+  const env = resolveEnv(opts.env);
+  const { target, pack, format, merge, assertName } = opts;
+
+  // [0] acquire the advisory lock — held across read->merge->write.
+  const lock = acquireLock(target, opts.lock);
+  try {
+    // [1] backup BEFORE the first write byte (mandatory; the only remediation).
+    const backupDir = backupConfig(env, target, pack, opts.stamp);
+
+    // [2]+[3] read INSIDE the lock (never carry a pre-lock parse). The shadow
+    // cases (ENOENT/blank/parse-error/permission) are handled by readConfigDoc.
+    const { doc: current } = readConfigDoc(target, format);
+    const currentText = format.serialize(current);
+
+    // [4..6] merge + serialize. A throw here (e.g. collision) aborts cleanly —
+    // nothing has been written, the lock releases in finally, backup is harmless.
+    const next = merge(current);
+    const nextText = format.serialize(next);
+
+    // Idempotent no-op: identical post-serialize output => do not touch the file.
+    // (Still validates the entry is present so a PARTIAL prior state self-heals.)
+    if (nextText === currentText) {
+      // The entry must actually be present for a true no-op; if the merge claims
+      // no change yet the entry is absent, the doc is inconsistent — surface it
+      // rather than silently "succeeding".
+      assertEntryOrThrow(format, next, assertName, target, backupDir);
+      return { changed: false, backupDir, realTarget: realpathOrSelf(target) };
+    }
+
+    // [7] atomic write onto the REALPATH (resolve the ~/.mcp.json symlink first,
+    // rename onto the resolved file, NEVER replace the link).
+    const realTarget = realpathOrSelf(target);
+    // The resolved parent must exist for the temp+rename; create it for a fresh
+    // NON-symlink target whose dir is missing (e.g. a brand-new file). We never
+    // mkdir for a Codex-absent host — that's gated upstream by isCodexInstalled.
+    fs.mkdirSync(path.dirname(realTarget), { recursive: true });
+    atomicReplace(realTarget, nextText);
+
+    // [8] verify-after-write: re-read, re-parse, assert the entry is present. On
+    // ANY failure, restore from the [1] backup and raise PartialRegistrationError.
+    try {
+      const reread = readConfigDoc(realTarget, format);
+      format.assertEntry(reread.doc, assertName);
+    } catch (verifyErr) {
+      const restored = restoreSafely(realTarget, backupDir);
+      const tail = restored
+        ? `restored from backup ${backupDir}`
+        : `RESTORE FAILED — file is in the HQ-written state; the original is recoverable ` +
+          `at ${backupDir}`;
+      throw new PartialRegistrationError(
+        `verify-after-write failed for ${realTarget} (entry "${assertName}" not confirmed: ` +
+          `${(verifyErr as Error).message}); ${tail}`,
+        backupDir,
+      );
+    }
+
+    return { changed: true, backupDir, realTarget };
+  } finally {
+    // [9] always release the lock, even on abort/throw.
+    releaseLock(lock);
+  }
+}
+
+/** assertEntry wrapper that maps a verify failure to a restore + PartialRegistrationError. */
+function assertEntryOrThrow<T>(
+  format: ConfigFormat<T>,
+  doc: T,
+  name: string,
+  target: string,
+  backupDir: string,
+): void {
+  try {
+    format.assertEntry(doc, name);
+  } catch (e) {
+    throw new PartialRegistrationError(
+      `post-merge invariant failed for ${target}: entry "${name}" is not present in a ` +
+        `supposedly-unchanged config (${(e as Error).message})`,
+      backupDir,
+    );
+  }
+}
+
+/**
+ * Restore from backup. Returns true iff the restore succeeded; on failure returns
+ * false WITHOUT throwing, so the caller can report accurately (the file is left in
+ * the HQ-written state, the backupDir remains on disk for manual recovery, and we
+ * never mask the PartialRegistrationError with a secondary restore error).
+ */
+function restoreSafely(realTarget: string, backupDir: string): boolean {
+  try {
+    restoreFromBackup(realTarget, backupDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ===========================================================================
+// US-007 — Claude/JSON merge emit (consumes the US-006 safe-write core).
+//
+// This is the FIRST of the two per-runtime emitters that {@link registerServer}
+// fans a single per-server manifest out onto. It takes one pack's per-server MCP
+// manifest ({type,url,headers,…} — already shape-validated by US-005's
+// `validateMcpManifest`), resolves any `${secret:NAME}` header references AT EMIT
+// (never persisting the reference, never echoing the resolved value), stamps a
+// `_hqPack` provenance marker so US-009 uninstall can find ONLY our entries, and
+// merges exactly ONE `mcpServers.<name>` entry into the PINNED single Claude
+// surface (top-level `~/.claude.json` `mcpServers`) via {@link writeConfigAtomic}.
+//
+// The Codex/TOML emitter is US-008; this story does NOT implement it. The
+// {@link registerServer} fan-out wires the Claude arm and leaves the Codex arm a
+// FIRST-CLASS SKIP (the substrate's {@link isCodexInstalled} branch) — never a
+// crash, never a fabricated `~/.codex`. So a re-run after US-008 lands simply
+// gains the second surface; US-007 already self-heals per surface (US-006
+// desired-state-convergence).
+//
+// SECRET SAFETY (the hard rule from the PRD authModel / US-002 AC):
+//   - `${secret:NAME}` resolves ONLY here, at emit, via the injected
+//     {@link SecretResolver} (production = the AES-256-GCM `secrets-cache.ts`).
+//   - The RESOLVED value lands in `~/.claude.json` — a 0600 user-global file that
+//     is NOT synced/committed — because the runtime needs the real header to work.
+//   - The resolved value is REDACTED from every return value and never echoed; we
+//     never write the literal back to a synced artifact (the pack repo keeps only
+//     the `${secret:}` reference). {@link redactSecrets} enforces the no-echo rule
+//     on anything a caller might log.
+// ===========================================================================
+
+/** Server-name charset gate: load-bearing as the `mcp__<name>__*` tool namespace. */
+export const MCP_SERVER_NAME_RE = /^[a-z0-9_-]+$/;
+
+/** The provenance key stamped onto every HQ-registered server (US-009 uninstall scope). */
+export const HQ_PACK_PROVENANCE_KEY = '_hqPack';
+
+/**
+ * A per-server MCP manifest as shipped in a pack (`mcp/<name>.json`). The shape is
+ * validated upstream by US-005's `validateMcpManifest`; here we treat it as a
+ * read-only record and only touch `headers`/`env` for secret resolution. `type`
+ * and the transport fields pass through to the emitted Claude server def verbatim.
+ */
+export interface McpManifest {
+  type: 'http' | 'stdio' | 'sse';
+  url?: string;
+  headers?: Record<string, string>;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  tools?: Record<string, unknown>;
+}
+
+/**
+ * Resolve a `${secret:NAME}` reference to its plaintext value, or return `null`
+ * when the secret is unavailable (un-minted / TTL-expired / no company context).
+ * Production binds this to `secrets-cache.ts` (`readCache(companyUid, NAME)`,
+ * AES-256-GCM, 0600, 5-min TTL); TESTS inject a pure map so they NEVER read the
+ * real encrypted cache. Returning `null` for a referenced secret is a hard error
+ * at emit (we refuse to write a broken header), distinct from a name with no
+ * reference at all.
+ */
+export type SecretResolver = (name: string) => string | null;
+
+/** Matches every `${secret:NAME}` reference in a string (global, for replace). */
+const SECRET_REF_RE = /\$\{secret:([A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]+)*)\}/g;
+
+/** A single `${secret:NAME}` for membership tests (non-global). */
+const SECRET_REF_TEST_RE = /\$\{secret:[A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]+)*\}/;
+
+/** True iff `value` contains at least one `${secret:NAME}` reference. */
+export function hasSecretRef(value: string): boolean {
+  return SECRET_REF_TEST_RE.test(value);
+}
+
+/**
+ * Replace every `${secret:NAME}` in `value` with its resolved plaintext, tracking
+ * each resolved literal so the caller can REDACT it from any output. Throws
+ * {@link McpManifestError} if a referenced secret cannot be resolved (we refuse to
+ * emit a half-resolved header — better a clear failure than a silently-broken
+ * server). A string with no reference passes through untouched.
+ *
+ * @param value     the header/env value (e.g. `"Bearer ${secret:VYG_API_KEY}"`)
+ * @param resolve   the {@link SecretResolver}
+ * @param secretSink accumulates every resolved plaintext (for redaction); may be
+ *                   the SAME set across many values so one `redactSecrets` call
+ *                   scrubs them all.
+ */
+export function resolveSecretRefs(
+  value: string,
+  resolve: SecretResolver,
+  secretSink: Set<string>,
+): string {
+  return value.replace(SECRET_REF_RE, (_match, name: string) => {
+    const resolved = resolve(name);
+    if (resolved === null || resolved === undefined) {
+      throw new McpManifestError(
+        `cannot resolve \${secret:${name}} at emit — the secret is not in the cache ` +
+          '(mint it via the pack onboarding / `hq run`, then re-install). HQ refuses to ' +
+          'write a half-resolved header.',
+      );
+    }
+    if (resolved.length > 0) secretSink.add(resolved);
+    return resolved;
+  });
+}
+
+/** The redaction marker substituted for any resolved secret value in output. */
+export const SECRET_REDACTION = '«redacted»';
+
+/**
+ * Scrub every resolved secret plaintext out of `text`, replacing it with
+ * {@link SECRET_REDACTION}. Use on ANYTHING that might be logged/echoed/returned
+ * after an emit — the no-echo rule is absolute. Longest-first replacement avoids a
+ * shorter secret unmasking a longer one that contains it.
+ */
+export function redactSecrets(text: string, secrets: Iterable<string>): string {
+  let out = text;
+  const sorted = [...secrets].filter((s) => s.length > 0).sort((a, b) => b.length - a.length);
+  for (const s of sorted) {
+    out = out.split(s).join(SECRET_REDACTION);
+  }
+  return out;
+}
+
+/**
+ * The Claude `ConfigFormat` for the top-level `~/.claude.json` surface: the doc is
+ * the whole `~/.claude.json` object, the entry we assert is `mcpServers.<name>`.
+ * Reuses {@link jsonFormat}'s parse/serialize (object-rooted JSON, pretty-printed
+ * with a trailing newline) so existing servers — and every UNRELATED top-level key
+ * in `~/.claude.json` (projects, userID, tipsHistory, …) — round-trip byte-for-byte.
+ */
+export const claudeConfigFormat: ConfigFormat<Record<string, unknown>> = {
+  parse: jsonFormat.parse,
+  serialize: jsonFormat.serialize,
+  // A fresh `~/.claude.json` is just `{}` — we do NOT presume an `mcpServers` key;
+  // the merge fn creates it on demand so we never rewrite a user's whole file.
+  emptyDoc: () => ({}),
+  assertEntry(doc, name) {
+    const servers = (doc as { mcpServers?: Record<string, unknown> }).mcpServers;
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers) || !(name in servers)) {
+      throw new Error(`mcpServers.${name} not present after write`);
+    }
+  },
+};
+
+/**
+ * Build the Claude server definition emitted into `mcpServers.<name>` from a
+ * manifest: pass the transport fields through, resolve `${secret:}` in every
+ * header/env value (recording the plaintexts in `secretSink` for redaction), and
+ * stamp `_hqPack` provenance. The output object's key order is deterministic so a
+ * re-run produces a byte-identical def (idempotency depends on stable serialize).
+ */
+export function buildClaudeServerDef(
+  manifest: McpManifest,
+  pack: string,
+  resolve: SecretResolver,
+  secretSink: Set<string>,
+): Record<string, unknown> {
+  const def: Record<string, unknown> = { type: manifest.type };
+  if (manifest.url !== undefined) def.url = manifest.url;
+  if (manifest.command !== undefined) def.command = manifest.command;
+  if (manifest.args !== undefined) def.args = manifest.args;
+  if (manifest.headers !== undefined) {
+    def.headers = resolveStringMap(manifest.headers, resolve, secretSink);
+  }
+  if (manifest.env !== undefined) {
+    def.env = resolveStringMap(manifest.env, resolve, secretSink);
+  }
+  if (manifest.tools !== undefined) def.tools = manifest.tools;
+  // Provenance LAST so it is visibly an HQ annotation; US-009 keys off it.
+  def[HQ_PACK_PROVENANCE_KEY] = pack;
+  return def;
+}
+
+/** Resolve `${secret:}` in every value of a string map, recording plaintexts. */
+function resolveStringMap(
+  map: Record<string, string>,
+  resolve: SecretResolver,
+  secretSink: Set<string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(map)) {
+    out[k] = resolveSecretRefs(v, resolve, secretSink);
+  }
+  return out;
+}
+
+/**
+ * Compare two server defs for COLLISION purposes, ignoring the `_hqPack`
+ * provenance stamp (a user-created server has no stamp; an HQ re-install carries
+ * one — neither difference is a real definitional conflict). Returns true iff the
+ * transport-relevant content is identical. Used to distinguish def-equal (no-op)
+ * from def-differs (abort) when a name is already present.
+ */
+export function serverDefsEqual(a: unknown, b: unknown): boolean {
+  return canonicalJson(stripProvenance(a)) === canonicalJson(stripProvenance(b));
+}
+
+/** A shallow copy of an object with the `_hqPack` key removed (for equality). */
+function stripProvenance(v: unknown): unknown {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return v;
+  const { [HQ_PACK_PROVENANCE_KEY]: _omit, ...rest } = v as Record<string, unknown>;
+  return rest;
+}
+
+/** Order-insensitive JSON for object keys (so key order never spoofs a collision). */
+function canonicalJson(v: unknown): string {
+  return JSON.stringify(v, (_k, val) => {
+    if (val && typeof val === 'object' && !Array.isArray(val)) {
+      const obj = val as Record<string, unknown>;
+      return Object.keys(obj)
+        .sort()
+        .reduce<Record<string, unknown>>((acc, k) => {
+          acc[k] = obj[k];
+          return acc;
+        }, {});
+    }
+    return val;
+  });
+}
+
+/**
+ * The merge fn for the Claude surface: insert/converge `mcpServers.<name> = def`.
+ *
+ *   - name ABSENT       -> insert (creating `mcpServers` if needed).
+ *   - name PRESENT, def-equal (provenance-ignored) -> NO-OP (idempotent re-install
+ *     / PARTIAL self-heal). The provenance stamp is (re)applied so an entry the
+ *     user happened to define identically becomes HQ-owned only when we truly own
+ *     it — but byte-equality of the rest means {@link writeConfigAtomic} writes
+ *     nothing unless the stamp itself is the only delta, which we treat as a no-op
+ *     by returning the original doc.
+ *   - name PRESENT, def-DIFFERS -> {@link McpNameCollisionError} ABORT.
+ *
+ * Never touches any OTHER server entry or any other top-level key.
+ */
+export function mergeClaudeServer(
+  name: string,
+  def: Record<string, unknown>,
+): (doc: Record<string, unknown>) => Record<string, unknown> {
+  return (doc) => {
+    const servers = { ...((doc.mcpServers as Record<string, unknown>) ?? {}) };
+    const existing = servers[name];
+    if (existing !== undefined) {
+      if (serverDefsEqual(existing, def)) {
+        // Idempotent: the meaningful definition matches. Return the doc UNCHANGED
+        // (do not re-stamp) so a re-install is a true byte-for-byte no-op.
+        return doc;
+      }
+      throw new McpNameCollisionError(
+        `MCP server "${name}" is already defined in ~/.claude.json with a different ` +
+          'definition — refusing to overwrite. Remove or rename the existing server, ' +
+          'or uninstall the conflicting pack, then re-install.',
+      );
+    }
+    servers[name] = def;
+    return { ...doc, mcpServers: servers };
+  };
+}
+
+/** Options for {@link registerServer} / {@link registerClaudeServer}. */
+export interface RegisterServerOptions {
+  /** The bare server name (the `mcpServers` key + `mcp__<name>__*` namespace). */
+  name: string;
+  /** The shape-validated per-server manifest (`mcp/<name>.json`). */
+  manifest: McpManifest;
+  /** The pack name — stamped as `_hqPack` provenance + labels the backup dir. */
+  pack: string;
+  /** Resolves `${secret:NAME}` at emit. Defaults to a no-secret resolver (errors on any ref). */
+  resolveSecret?: SecretResolver;
+  /** Injectable env (tests pass a tmpdir home so the real ~/.claude.json is untouched). */
+  env?: Partial<SafeWriteEnv>;
+  /** Lock tuning (tests use tiny timeouts). */
+  lock?: AcquireLockOptions;
+  /** Backup timestamp override (deterministic tests). */
+  stamp?: string;
+  /**
+   * Append an audit-log line per surface (default true). The AC requires every
+   * register to log; this exists ONLY to suppress logging in narrow unit tests
+   * (e.g. {@link registerClaudeServer}/{@link registerCodexServer} are called
+   * directly there and do their own thing). The audit append goes through the
+   * injected `env.home`, so in tests it lands in the tmpdir — never the real ~/.
+   */
+  audit?: boolean;
+}
+
+/** Outcome of registering one server into one surface. */
+export interface RegisterSurfaceResult {
+  /** Whether the surface's file actually changed (false = idempotent no-op). */
+  changed: boolean;
+  /** The realpath the bytes were written to (resolved symlink). */
+  realTarget: string;
+}
+
+/** A surface that was deliberately not acted on (e.g. Codex-absent host). */
+export interface RegisterSurfaceSkip {
+  /** Discriminant: this surface was skipped, not written. */
+  skipped: true;
+  /** Human-readable reason (e.g. "Codex runtime absent"). */
+  reason: string;
+}
+
+/** Outcome of {@link registerServer} — one entry per runtime surface acted on. */
+export interface RegisterServerResult {
+  /** The Claude/JSON surface result (always present — US-007). */
+  claude: RegisterSurfaceResult;
+  /**
+   * The Codex/TOML surface result (US-008), or a first-class SKIP when the Codex
+   * runtime is absent (`~/.codex` missing — never fabricated).
+   */
+  codex: RegisterSurfaceResult | RegisterSurfaceSkip;
+}
+
+/** Default resolver: there is NO secret context, so any `${secret:}` ref is an error. */
+const noSecretResolver: SecretResolver = () => null;
+
+/**
+ * Validate a server name against {@link MCP_SERVER_NAME_RE} BEFORE it is ever
+ * interpolated into a JSON key (or, in US-008, a TOML header). A bad name is an
+ * injection vector (the name is load-bearing as the tool namespace), so this is a
+ * hard pre-flight gate. Throws {@link McpManifestError}.
+ */
+export function assertValidServerName(name: string): void {
+  if (typeof name !== 'string' || !MCP_SERVER_NAME_RE.test(name)) {
+    throw new McpManifestError(
+      `invalid MCP server name ${JSON.stringify(name)} — must match ${MCP_SERVER_NAME_RE} ` +
+        '(lowercase letters, digits, underscore, hyphen). The name is the `mcp__<name>__*` ' +
+        'tool namespace and a JSON/TOML key, so it is charset-validated before any interpolation.',
+    );
+  }
+}
+
+/**
+ * Emit ONE server into the PINNED single Claude surface (top-level
+ * `~/.claude.json` `mcpServers`) via {@link writeConfigAtomic}. Resolves
+ * `${secret:}` headers at emit, stamps provenance, and is idempotent per surface
+ * (re-install no-ops; a PARTIAL state self-heals). Existing servers and every
+ * unrelated `~/.claude.json` key are preserved byte-for-byte by the merge.
+ *
+ * @returns the surface result (changed?, realTarget). Any error message the caller
+ *          surfaces MUST be passed through {@link redactSecrets} — the resolved
+ *          secret plaintexts are collected internally and never returned.
+ * @throws McpManifestError       invalid server name or unresolvable `${secret:}`
+ * @throws McpNameCollisionError  the name exists with a different definition
+ * @throws ConfigParseError / ConfigPermissionError / PartialRegistrationError (from the core)
+ */
+export function registerClaudeServer(opts: RegisterServerOptions): RegisterSurfaceResult {
+  assertValidServerName(opts.name);
+  const resolve = opts.resolveSecret ?? noSecretResolver;
+  const secretSink = new Set<string>();
+
+  // Resolve secrets + build the def BEFORE entering the lock so a resolution
+  // failure aborts without taking a backup or touching the file.
+  const def = buildClaudeServerDef(opts.manifest, opts.pack, resolve, secretSink);
+
+  try {
+    const res = writeConfigAtomic({
+      target: claudeConfigPath2(opts.env),
+      pack: opts.pack,
+      format: claudeConfigFormat,
+      merge: mergeClaudeServer(opts.name, def),
+      assertName: opts.name,
+      env: opts.env,
+      lock: opts.lock,
+      stamp: opts.stamp,
+    });
+    return { changed: res.changed, realTarget: res.realTarget };
+  } catch (e) {
+    // Redact any resolved secret that might have leaked into an error message
+    // (e.g. a verify error echoing file content). Re-throw the SAME class.
+    if (secretSink.size > 0 && e instanceof Error) {
+      e.message = redactSecrets(e.message, secretSink);
+    }
+    throw e;
+  }
+}
+
+/**
+ * Resolve the Claude target path from a (partial) env, mirroring
+ * {@link claudeConfigPath} but tolerating an undefined env (production default).
+ */
+function claudeConfigPath2(env?: Partial<SafeWriteEnv>): string {
+  return claudeConfigPath(resolveEnv(env));
+}
+
+/**
+ * Fan ONE server out across the per-runtime surfaces. US-007 wires the Claude/JSON
+ * arm ({@link registerClaudeServer}); US-008 wires the Codex/TOML arm
+ * ({@link registerCodexServer}). Each arm registers ONE server into its surface via
+ * {@link writeConfigAtomic} and is idempotent per surface (re-install no-ops; a
+ * PARTIAL state — one runtime wired, the other not — self-heals on re-run).
+ *
+ * The Codex arm is a FIRST-CLASS SKIP when the Codex runtime is absent (`~/.codex`
+ * missing): no crash, no fabricated directory. So a Claude-only host still registers
+ * Claude cleanly, and a re-run after a Codex install fills the second surface.
+ *
+ * ORDERING: Claude is emitted FIRST. If the Codex emit then throws, Claude is
+ * already durably registered and a re-run self-heals only the missing Codex surface
+ * (desired-state convergence) — the user is never left with NOTHING wired.
+ *
+ * Pre-flight collision spanning BOTH targets is enforced PER SURFACE by each
+ * emitter's merge (def-equal = no-op, def-differs = {@link McpNameCollisionError}).
+ */
+export function registerServer(opts: RegisterServerOptions): RegisterServerResult {
+  // Name validation is the very first gate (before any interpolation / IO).
+  assertValidServerName(opts.name);
+
+  const env = resolveEnv(opts.env);
+  const audit = opts.audit ?? true;
+  const transport = opts.manifest.type;
+  const target = manifestTarget(opts.manifest);
+  const claudeTarget = claudeConfigPath(env);
+  const codexTarget = codexConfigPath(env);
+
+  // Claude FIRST so a Codex failure never leaves the user with nothing wired.
+  // Capture prevHash BEFORE the emit (which does the write internally), newHash
+  // AFTER (off the realTarget the surface reports). An emit THROW still logs a
+  // line with result:'error' so the failed attempt is auditable, then re-throws.
+  const claudePrevHash = audit ? hashFileContents(claudeTarget) : '';
+  let claude: RegisterSurfaceResult;
+  try {
+    claude = registerClaudeServer(opts);
+  } catch (e) {
+    if (audit) {
+      appendAuditLog(env, {
+        ts: new Date().toISOString(),
+        action: 'register',
+        pack: opts.pack,
+        server: opts.name,
+        transport,
+        target,
+        file: claudeTarget,
+        prevHash: claudePrevHash,
+        newHash: hashFileContents(claudeTarget),
+        result: 'error',
+      });
+    }
+    throw e;
+  }
+  if (audit) {
+    appendAuditLog(env, {
+      ts: new Date().toISOString(),
+      action: 'register',
+      pack: opts.pack,
+      server: opts.name,
+      transport,
+      target,
+      file: claude.realTarget,
+      prevHash: claudePrevHash,
+      newHash: hashFileContents(claude.realTarget),
+      result: claude.changed ? 'registered' : 'noop',
+    });
+  }
+
+  // Codex/TOML emit (US-008). A Codex-absent host is a first-class skip — never a
+  // crash, never a fabricated ~/.codex. The emitter resolves the same manifest +
+  // secrets and merges ONE [mcp_servers.<name>] table into ~/.codex/config.toml.
+  const codexPrevHash = audit ? hashFileContents(codexTarget) : '';
+  let codex: RegisterSurfaceResult | RegisterSurfaceSkip;
+  try {
+    codex = registerCodexServer(opts);
+  } catch (e) {
+    if (audit) {
+      appendAuditLog(env, {
+        ts: new Date().toISOString(),
+        action: 'register',
+        pack: opts.pack,
+        server: opts.name,
+        transport,
+        target,
+        file: codexTarget,
+        prevHash: codexPrevHash,
+        newHash: hashFileContents(codexTarget),
+        result: 'error',
+      });
+    }
+    throw e;
+  }
+  if (audit) {
+    const skipped = 'skipped' in codex && codex.skipped === true;
+    appendAuditLog(env, {
+      ts: new Date().toISOString(),
+      action: 'register',
+      pack: opts.pack,
+      server: opts.name,
+      transport,
+      target,
+      file: skipped ? codexTarget : (codex as RegisterSurfaceResult).realTarget,
+      prevHash: codexPrevHash,
+      newHash: skipped ? codexPrevHash : hashFileContents((codex as RegisterSurfaceResult).realTarget),
+      result: skipped
+        ? 'skipped'
+        : (codex as RegisterSurfaceResult).changed
+          ? 'registered'
+          : 'noop',
+    });
+  }
+
+  return { claude, codex };
+}
+
+/**
+ * Derive the audit-log `target` field from a manifest: the url for http/sse, or
+ * `command` (plus space-joined args) for stdio. NEVER a header/secret. Returns ''
+ * when neither a url nor a command is present.
+ */
+export function manifestTarget(manifest: McpManifest): string {
+  if (manifest.type === 'http' || manifest.type === 'sse') {
+    return manifest.url ?? '';
+  }
+  // stdio (or anything else): command + args.
+  if (manifest.command !== undefined) {
+    const args = manifest.args && manifest.args.length > 0 ? ` ${manifest.args.join(' ')}` : '';
+    return `${manifest.command}${args}`;
+  }
+  return manifest.url ?? '';
+}
+
+/**
+ * Register one pack's MCP servers into the shared agent configs (the public seam
+ * `pack-install` routes `wire:'merge'` keys to). For each declared server name it
+ * loads + shape-checks the manifest, then fans out via {@link registerServer}.
+ *
+ * US-007 wires the Claude/JSON surface; the Codex/TOML surface (US-008) is a
+ * first-class skip until that story lands. Manifests are loaded with a caller-
+ * supplied loader so this stays decoupled from `pack-install`'s payload layout and
+ * fully testable in isolation.
+ *
+ * @param pkg     the pack name (e.g. `hq-pack-vyg-shopify`) — stamped as provenance
+ * @param names   the bare server names from `contributes.mcp`
+ * @param options manifest loader + secret resolver + injectable env (all optional;
+ *                without a loader this throws, since US-007 has no payload-dir context)
+ * @returns one {@link RegisterServerResult} per server, in `names` order
+ */
+export function registerMcpServers(
+  pkg: string,
+  names: string[],
+  options?: {
+    /** Load a server's shape-validated manifest by bare name (pack-install supplies this). */
+    loadManifest?: (name: string) => McpManifest;
+    /** Resolve `${secret:NAME}` at emit (defaults to the no-secret resolver). */
+    resolveSecret?: SecretResolver;
+    /** Injectable env (tests pass a tmpdir home). */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning + backup stamp passthrough (tests). */
+    lock?: AcquireLockOptions;
+    stamp?: string;
+  },
+): RegisterServerResult[] {
+  // OPERATOR KILL-SWITCH (US-012): HQ_DISABLE_MCP_REGISTRATION=1 short-circuits ALL
+  // MCP registration — no server is written to either runtime config — while symlink
+  // contributions for OTHER keys still wire (this only short-circuits the mcp MERGE
+  // path, never the symlink path, which lives in pack-install/pack-contributions).
+  //
+  // ORDERING: this is checked FIRST, BEFORE the loadManifest programmer-error guard
+  // below. The kill-switch is a USER/OPERATOR condition; the missing-loadManifest
+  // throw is a PROGRAMMER error. An operator who set the kill-switch must never hit a
+  // spurious McpManifestError, so the operator path wins. We read process.env directly
+  // (not options.env — that's the SafeWriteEnv home-path injector, NOT process env);
+  // tests set/unset process.env.HQ_DISABLE_MCP_REGISTRATION around the call.
+  //
+  // Returns an empty RegisterServerResult[] (`[]`) — the correct "no servers
+  // registered" semantic — so callers (pack-install) consume it gracefully. The skip
+  // NOTICE is emitted exactly once per registerMcpServers call.
+  if (process.env.HQ_DISABLE_MCP_REGISTRATION === '1') {
+    process.stderr.write('MCP registration skipped (HQ_DISABLE_MCP_REGISTRATION=1)\n');
+    return [];
+  }
+  const loadManifest = options?.loadManifest;
+  if (!loadManifest) {
+    // Without a manifest loader there is no payload context to emit from. This is
+    // a programmer error at the call site, not a user-facing condition — keep it a
+    // named error so callers (pack-install) wire the loader explicitly.
+    throw new McpManifestError(
+      'registerMcpServers requires a manifest loader (options.loadManifest) to resolve ' +
+        'each declared contributes.mcp server to its mcp/<name>.json definition',
+    );
+  }
+  return names.map((name) => {
+    assertValidServerName(name);
+    const manifest = loadManifest(name);
+    return registerServer({
+      name,
+      manifest,
+      pack: pkg,
+      resolveSecret: options?.resolveSecret,
+      env: options?.env,
+      lock: options?.lock,
+      stamp: options?.stamp,
+    });
+  });
+}
+
+// ===========================================================================
+// US-008 — Codex/TOML merge emit (consumes the US-006 safe-write core).
+//
+// The SECOND per-runtime emitter {@link registerServer} fans a single per-server
+// manifest out onto. It mirrors the US-007 Claude/JSON emitter but writes ONE
+// `[mcp_servers.<name>]` TOML table into the GLOBAL Codex config
+// (`~/.codex/config.toml`, NOT the project file) via {@link writeConfigAtomic},
+// reusing the EXACT same read->lock->backup->merge->write->verify machinery —
+// only the {@link ConfigFormat} (parse/serialize/assertEntry) differs.
+//
+// TOML ROUND-TRIP via a REAL library: `smol-toml` (a spec-compliant TOML 1.0
+// parser/serializer; throws `TomlError` on malformed input, which the substrate's
+// read path maps to {@link ConfigParseError} → FAIL-CLOSED, preserving the file).
+// It is NOT a hand-rolled string splice: existing tables (`superhuman`,
+// `node_repl`, …) and their sub-tables (`.env`, `.tools.<t>.approval_mode`) are
+// preserved across the round-trip.
+//
+// COMMENT-PRESERVATION LIMITATION (documented, per the story's fallback clause):
+// no production JS TOML library (`smol-toml` nor `@iarna/toml`) round-trips
+// COMMENTS through a parse→value→serialize cycle — both are value parsers, not
+// CST/format-preserving editors. So a naïve serialize-the-whole-doc emit would
+// DROP every comment in the user's config. To honor the "preserves comments" AC
+// for the realistic case, this emitter NEVER re-serializes the existing file: it
+// only ever ADDS one new server table (collision on an existing name ABORTS, it
+// never mutates an existing table), so when the file pre-existed we APPEND the
+// new table's serialized text to the ORIGINAL bytes verbatim. The original — with
+// every comment and every existing table/sub-table — is preserved byte-for-byte;
+// only the appended block is library-serialized. A from-scratch file (Codex just
+// installed, empty/absent config) is fully serialized (there is nothing to
+// preserve). See {@link CodexTomlDoc} / {@link codexConfigFormat.serialize}.
+//
+// CODEX-ABSENT = FIRST-CLASS SKIP: {@link registerCodexServer} branches on
+// {@link isCodexInstalled} and returns a {@link RegisterSurfaceSkip} when `~/.codex`
+// is missing — never a crash, never a `mkdir -p` fabrication.
+//
+// SECRET SAFETY: identical to US-007 — `${secret:}` resolves ONLY here at emit via
+// the injected {@link SecretResolver}; the resolved value lands in the 0600,
+// never-synced `~/.codex/config.toml` (the runtime needs the real header) and is
+// REDACTED from every error/return value, never echoed.
+// ===========================================================================
+
+/** smol-toml's value-table type (its `parse` return + `stringify` input). */
+type TomlTable = Record<string, unknown>;
+
+/**
+ * The Codex doc threaded through the safe-write core. We carry BOTH the parsed
+ * value (`value`, for the merge fn + verify) AND the ORIGINAL file text
+ * (`originalText`, `null` for a fresh/empty file). {@link codexConfigFormat.serialize}
+ * uses `originalText` to APPEND the one new table without re-serializing — and so
+ * without dropping — the user's existing comments and tables. This is the seam that
+ * makes "preserves comments" honest within a value-only TOML library.
+ */
+export interface CodexTomlDoc {
+  /** The parsed TOML table (the whole `~/.codex/config.toml` as a value). */
+  value: TomlTable;
+  /** The original file text, or `null` when the file was absent/empty. */
+  originalText: string | null;
+}
+
+/** The Codex `[mcp_servers]` super-table key (the global Codex MCP registry). */
+export const CODEX_MCP_SERVERS_KEY = 'mcp_servers';
+
+/**
+ * Serialize EXACTLY ONE server table (`[mcp_servers.<name>]` + its sub-tables)
+ * by wrapping the def under `mcp_servers.<name>` and round-tripping it through
+ * smol-toml. Used both for the append path (preserve-comments) and for the
+ * collision/equality comparison. The output is deterministic for a given def so a
+ * re-install produces byte-identical text (idempotency depends on it).
+ */
+export function serializeOneCodexServer(name: string, def: TomlTable): string {
+  return stringifyToml({ [CODEX_MCP_SERVERS_KEY]: { [name]: def } });
+}
+
+/**
+ * The Codex `ConfigFormat`. `parse` round-trips the file through smol-toml
+ * (throwing `TomlError` on malformed NON-empty input → the substrate maps it to
+ * {@link ConfigParseError}, FAIL-CLOSED). `serialize` is comment-preserving: when
+ * the doc carries `originalText` (the file pre-existed) it APPENDS the new
+ * `mcp_servers.<name>` table to the original bytes rather than re-serializing the
+ * whole value; only when there is no original (`null`) does it serialize the full
+ * value from scratch. `assertEntry` checks `mcp_servers.<name>` is present.
+ *
+ * Because `serialize` needs the merged value to know WHICH server to append, the
+ * merge fn ({@link mergeCodexServer}) records the just-added server on the doc; the
+ * append path reads it back. For an idempotent no-op (server already present,
+ * def-equal) the merge returns the doc UNCHANGED with no pending append, so
+ * `serialize` reproduces the original text exactly (no write happens).
+ */
+export const codexConfigFormat: ConfigFormat<CodexTomlDoc> = {
+  parse(text: string): CodexTomlDoc {
+    // smol-toml throws TomlError on malformed input; the substrate's readConfigDoc
+    // wraps this throw into ConfigParseError and ABORTS (fail-closed, file kept).
+    const value = parseToml(text) as TomlTable;
+    return { value, originalText: text };
+  },
+  serialize(doc: CodexTomlDoc): string {
+    const pending = (doc as CodexTomlDocWithPending)[PENDING_APPEND];
+    if (doc.originalText !== null && pending) {
+      // APPEND path: keep the original bytes verbatim (comments + every existing
+      // table/sub-table preserved), then append the one new server table.
+      return appendCodexTable(doc.originalText, pending.name, pending.def);
+    }
+    if (doc.originalText !== null && !pending) {
+      // No-op (idempotent / no pending add): reproduce the original byte-for-byte
+      // so writeConfigAtomic sees an unchanged file and writes nothing.
+      return doc.originalText;
+    }
+    // FRESH file (no original to preserve): serialize the whole value. If there is a
+    // pending add, fold it into the value first so a from-scratch write includes it.
+    const value = pending
+      ? withServer(doc.value, pending.name, pending.def)
+      : doc.value;
+    return stringifyToml(value);
+  },
+  emptyDoc(): CodexTomlDoc {
+    return { value: {}, originalText: null };
+  },
+  assertEntry(doc: CodexTomlDoc, name: string): void {
+    const servers = doc.value[CODEX_MCP_SERVERS_KEY] as TomlTable | undefined;
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers) || !(name in servers)) {
+      throw new Error(`mcp_servers.${name} not present after write`);
+    }
+  },
+};
+
+/** Symbol carrying the pending append on a {@link CodexTomlDoc} (merge → serialize). */
+const PENDING_APPEND = Symbol('hqPendingCodexAppend');
+
+/** A {@link CodexTomlDoc} that may carry a pending append for {@link codexConfigFormat.serialize}. */
+type CodexTomlDocWithPending = CodexTomlDoc & {
+  [PENDING_APPEND]?: { name: string; def: TomlTable };
+};
+
+/** Return a copy of `value` with `mcp_servers.<name> = def` set (used for fresh-file serialize). */
+function withServer(value: TomlTable, name: string, def: TomlTable): TomlTable {
+  const servers = { ...((value[CODEX_MCP_SERVERS_KEY] as TomlTable | undefined) ?? {}) };
+  servers[name] = def;
+  return { ...value, [CODEX_MCP_SERVERS_KEY]: servers };
+}
+
+/**
+ * Append a `[mcp_servers.<name>]` table to existing TOML text, preserving the
+ * original bytes (and thus all comments + existing tables). Ensures exactly one
+ * blank-line separator between the original content and the appended block so the
+ * result is well-formed regardless of the original's trailing whitespace.
+ */
+export function appendCodexTable(originalText: string, name: string, def: TomlTable): string {
+  const block = serializeOneCodexServer(name, def);
+  const trimmed = originalText.replace(/\s*$/, '');
+  if (trimmed.length === 0) {
+    // Original was whitespace-only — emit just the block (no leading blank lines).
+    return block.endsWith('\n') ? block : `${block}\n`;
+  }
+  const body = block.endsWith('\n') ? block : `${block}\n`;
+  return `${trimmed}\n\n${body}`;
+}
+
+/**
+ * Build the Codex server table emitted as `[mcp_servers.<name>]`: pass the
+ * transport fields through, resolve `${secret:}` in every header/env value
+ * (recording plaintexts in `secretSink` for redaction), stamp `_hqPack` provenance,
+ * and write the per-tool `approval_mode` from the manifest where present (the Codex-
+ * specific field — `[mcp_servers.<name>.tools.<t>]` with `approval_mode = "…"`).
+ *
+ * Key insertion order is deterministic so a re-install serializes byte-identically.
+ */
+export function buildCodexServerDef(
+  manifest: McpManifest,
+  pack: string,
+  resolve: SecretResolver,
+  secretSink: Set<string>,
+): TomlTable {
+  const def: TomlTable = { type: manifest.type };
+  if (manifest.url !== undefined) def.url = manifest.url;
+  if (manifest.command !== undefined) def.command = manifest.command;
+  if (manifest.args !== undefined) def.args = manifest.args;
+  if (manifest.headers !== undefined) {
+    def.headers = resolveStringMap(manifest.headers, resolve, secretSink);
+  }
+  if (manifest.env !== undefined) {
+    def.env = resolveStringMap(manifest.env, resolve, secretSink);
+  }
+  // Per-tool approval_mode (Codex-specific): manifest `tools.<t>.approval_mode`
+  // → `[mcp_servers.<name>.tools.<t>] approval_mode = "…"`. Only emit a tools
+  // sub-table when at least one tool actually declares an approval_mode, so we
+  // never write an empty `[…tools]` table.
+  const tools = buildCodexToolsTable(manifest.tools);
+  if (tools !== undefined) def.tools = tools;
+  // Provenance LAST so it reads as an HQ annotation; US-009 uninstall keys off it.
+  def[HQ_PACK_PROVENANCE_KEY] = pack;
+  return def;
+}
+
+/**
+ * Extract the per-tool `approval_mode` sub-table from a manifest's `tools` map.
+ * The manifest `tools` is `Record<tool, { approval_mode?: string, … }>`; we emit
+ * `{ <tool>: { approval_mode } }` ONLY for tools that declare an approval_mode
+ * (the field the Codex emitter is responsible for). Returns `undefined` when no
+ * tool declares one (so no empty tools table is written).
+ */
+export function buildCodexToolsTable(tools: McpManifest['tools']): TomlTable | undefined {
+  if (!tools || typeof tools !== 'object') return undefined;
+  const out: TomlTable = {};
+  for (const [tool, spec] of Object.entries(tools)) {
+    const mode = (spec as { approval_mode?: unknown } | undefined)?.approval_mode;
+    if (typeof mode === 'string') {
+      out[tool] = { approval_mode: mode };
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * The merge fn for the Codex surface: insert/converge `mcp_servers.<name> = def`.
+ *
+ *   - name ABSENT       → insert (creating `mcp_servers` if needed) and record a
+ *     PENDING append so {@link codexConfigFormat.serialize} can preserve comments
+ *     by appending to the original bytes.
+ *   - name PRESENT, def-equal (provenance-ignored) → NO-OP (idempotent re-install /
+ *     PARTIAL self-heal): return the doc UNCHANGED with no pending append, so the
+ *     original text round-trips byte-for-byte.
+ *   - name PRESENT, def-DIFFERS → {@link McpNameCollisionError} ABORT (never mutate
+ *     an existing table — which is also what keeps the comment-preserving append
+ *     sound: we only ever ADD).
+ *
+ * Never touches any OTHER server table or any other top-level table.
+ */
+export function mergeCodexServer(
+  name: string,
+  def: TomlTable,
+): (doc: CodexTomlDoc) => CodexTomlDoc {
+  return (doc) => {
+    const servers = (doc.value[CODEX_MCP_SERVERS_KEY] as TomlTable | undefined) ?? {};
+    const existing = servers[name];
+    if (existing !== undefined) {
+      if (serverDefsEqual(existing, def)) {
+        // Idempotent: meaningful def matches. Return UNCHANGED (no pending append)
+        // so serialize reproduces the original text exactly.
+        return doc;
+      }
+      throw new McpNameCollisionError(
+        `MCP server "${name}" is already defined in ~/.codex/config.toml with a different ` +
+          'definition — refusing to overwrite. Remove or rename the existing server, ' +
+          'or uninstall the conflicting pack, then re-install.',
+      );
+    }
+    // Insert into the value (for verify-after-write) AND record the pending append
+    // (for comment-preserving serialize).
+    const nextValue = withServer(doc.value, name, def);
+    const next: CodexTomlDocWithPending = {
+      value: nextValue,
+      originalText: doc.originalText,
+      [PENDING_APPEND]: { name, def },
+    };
+    return next;
+  };
+}
+
+/**
+ * Emit ONE server into the GLOBAL Codex surface (`~/.codex/config.toml`
+ * `[mcp_servers.<name>]`) via {@link writeConfigAtomic}. A FIRST-CLASS SKIP when the
+ * Codex runtime is absent (`~/.codex` missing — never fabricated). Resolves
+ * `${secret:}` headers/env at emit, stamps provenance, writes per-tool
+ * `approval_mode`, and is idempotent per surface. Existing tables + sub-tables (and
+ * comments) are preserved.
+ *
+ * @returns the surface result, or a {@link RegisterSurfaceSkip} (Codex absent).
+ * @throws McpManifestError       invalid server name or unresolvable `${secret:}`
+ * @throws McpNameCollisionError  the name exists with a different definition
+ * @throws ConfigParseError       existing config.toml is malformed (fail-closed)
+ * @throws ConfigPermissionError / PartialRegistrationError (from the core)
+ */
+export function registerCodexServer(
+  opts: RegisterServerOptions,
+): RegisterSurfaceResult | RegisterSurfaceSkip {
+  assertValidServerName(opts.name);
+  const env = resolveEnv(opts.env);
+
+  // FIRST-CLASS SKIP: no Codex runtime → do not write, do not fabricate ~/.codex.
+  if (!isCodexInstalled(env)) {
+    return {
+      skipped: true,
+      reason: 'Codex runtime absent (~/.codex missing) — first-class skip, Codex not registered',
+    };
+  }
+
+  const resolve = opts.resolveSecret ?? noSecretResolver;
+  const secretSink = new Set<string>();
+
+  // Resolve secrets + build the def BEFORE entering the lock so a resolution
+  // failure aborts without taking a backup or touching the file.
+  const def = buildCodexServerDef(opts.manifest, opts.pack, resolve, secretSink);
+
+  try {
+    const res = writeConfigAtomic<CodexTomlDoc>({
+      target: codexConfigPath(env),
+      pack: opts.pack,
+      format: codexConfigFormat,
+      merge: mergeCodexServer(opts.name, def),
+      assertName: opts.name,
+      env: opts.env,
+      lock: opts.lock,
+      stamp: opts.stamp,
+    });
+    return { changed: res.changed, realTarget: res.realTarget };
+  } catch (e) {
+    // Redact any resolved secret that could have leaked into an error message.
+    if (secretSink.size > 0 && e instanceof Error) {
+      e.message = redactSecrets(e.message, secretSink);
+    }
+    throw e;
+  }
+}
+
+// ===========================================================================
+// US-009 — Uninstall un-registration (the MIRROR IMAGE of register).
+//
+// Register (US-007/008) ADDS one provenance-stamped server per surface; uninstall
+// REMOVES exactly the entries THIS pack added, and NOTHING else. The single hard
+// rule that makes uninstall safe is PROVENANCE SCOPING: every HQ-registered server
+// carries `_hqPack: '<pkg>'` ({@link HQ_PACK_PROVENANCE_KEY}). Uninstall deletes a
+// `mcpServers.<name>` / `[mcp_servers.<name>]` entry IFF its stamp === this pack.
+// An entry whose stamp is ABSENT (user-created) or DIFFERENT (another pack) is
+// NEVER deleted — it is SKIPPED-AND-WARNED, mirroring `unwirePack`'s foreign-link
+// philosophy (leave anything we do not provably own). There is NO bare name-match
+// delete anywhere in this module.
+//
+// The three invariants this block upholds (US-009 AC):
+//   1. provenance-scoped removal + skip-and-warn on foreign/unstamped (never bare
+//      name-match delete);
+//   2. surgical key removal preserving siblings + comments + `.tools.<t>.approval_mode`
+//      sub-tables (TOML), tolerant of an absent runtime config (Codex-less host or a
+//      missing file → first-class skip / no-op), and IDEMPOTENT (removing an already-
+//      gone / never-installed server is a clean no-op);
+//   3. removal goes THROUGH {@link writeConfigAtomic} (backup + atomic + lock +
+//      verify) — the SAME safe-write path register uses, never a hand-rolled write.
+//
+// VERIFY-AFTER-WRITE INVERSION (the load-bearing seam): {@link writeConfigAtomic}
+// calls `format.assertEntry(reread.doc, assertName)` to confirm the entry is
+// PRESENT after a write. For REMOVAL we need the opposite — assert the entry is
+// ABSENT. So the removal path passes a REMOVAL FORMAT ({@link claudeRemovalFormat}
+// / {@link codexRemovalFormat}) that reuses the SAME parse/serialize but flips
+// `assertEntry` to "throw IFF `name` is STILL present". This also makes the
+// idempotent no-op-when-absent path clean: when the server is already gone the
+// merge returns the doc unchanged, `writeConfigAtomic`'s `nextText === currentText`
+// branch fires and runs the removal format's `assertEntry` (already-absent ⇒
+// passes ⇒ `changed: false`), with NO spurious {@link PartialRegistrationError}.
+//
+// CODEX COMMENT-DROP ON REMOVAL (documented limitation, same root cause US-008
+// documented for the add path): US-008's append-only `codexConfigFormat.serialize`
+// can ADD a table by appending to the original bytes (comments preserved) but
+// CANNOT express a key REMOVAL by appending. To remove a table we must RE-SERIALIZE
+// the modified parsed value via `smol-toml stringifyToml`, and no production JS TOML
+// library round-trips COMMENTS through parse→value→serialize. So a Codex removal
+// that actually deletes a table DROPS the file's comments (the data — sibling tables
+// and every `.tools.<t>.approval_mode` sub-table — is preserved, just not comments).
+// A NO-OP removal (server absent / foreign) reproduces `originalText` byte-for-byte
+// (no write, comments intact). This is the unavoidable cost of value-only TOML libs.
+// ===========================================================================
+
+/** Discriminates an un-registration outcome on one surface. */
+export type UnregisterOutcome =
+  /** The provenance-stamped entry was found and removed (file changed). */
+  | 'removed'
+  /** The entry was already absent / never installed — a clean idempotent no-op. */
+  | 'absent'
+  /** The entry exists but its provenance does NOT match this pack (foreign / user-created) — left in place. */
+  | 'skipped-foreign';
+
+/** Outcome of un-registering one server from one surface. */
+export interface UnregisterSurfaceResult {
+  /** What happened: removed / absent(no-op) / skipped(foreign-or-unstamped). */
+  outcome: UnregisterOutcome;
+  /** Whether the surface's file actually changed (true only for `removed`). */
+  changed: boolean;
+  /** The realpath acted on (resolved symlink), when a file was present. */
+  realTarget: string;
+  /** A human-readable note for the `skipped-foreign` case (suitable for a warning). */
+  reason?: string;
+}
+
+/** A surface deliberately not acted on (e.g. Codex-absent host, or the file never existed). */
+export interface UnregisterSurfaceSkip {
+  /** Discriminant: this surface was skipped, not inspected. */
+  skipped: true;
+  /** Human-readable reason (e.g. "Codex runtime absent"). */
+  reason: string;
+}
+
+/** Outcome of {@link unregisterServer} — one entry per runtime surface. */
+export interface UnregisterServerResult {
+  /** The Claude/JSON surface result (always inspected — Claude is always present). */
+  claude: UnregisterSurfaceResult;
+  /**
+   * The Codex/TOML surface result, or a first-class SKIP when the Codex runtime is
+   * absent (`~/.codex` missing — never fabricated).
+   */
+  codex: UnregisterSurfaceResult | UnregisterSurfaceSkip;
+}
+
+/**
+ * Read `_hqPack` off a server def (Claude object OR Codex TOML table). Returns the
+ * stamp string, or `undefined` when the entry is unstamped (user-created) — the two
+ * cases the skip-and-warn branch treats identically (anything we do not provably own
+ * is left alone).
+ */
+function provenanceOf(def: unknown): string | undefined {
+  if (def === null || typeof def !== 'object' || Array.isArray(def)) return undefined;
+  const stamp = (def as Record<string, unknown>)[HQ_PACK_PROVENANCE_KEY];
+  return typeof stamp === 'string' ? stamp : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Removal-decision helper (shared by both surfaces).
+//
+// A pure classifier over "the entry currently at <name>" + "the pack we are
+// uninstalling", returning ONE of: remove (provenance matches), skip-foreign
+// (present but provenance mismatched/absent), or absent (no entry). Centralizing
+// this keeps the Claude + Codex merge fns identical in policy and gives the tests
+// a single seam to exercise the provenance rule.
+// ---------------------------------------------------------------------------
+
+/** What a removal merge should do with the entry currently sitting at a name. */
+type RemovalDecision = 'remove' | 'skip-foreign' | 'absent';
+
+/**
+ * Classify the entry at a name against the pack being uninstalled. PROVENANCE IS
+ * THE ONLY KEY — never the name alone:
+ *   - no entry            → `absent` (idempotent no-op);
+ *   - entry, stamp===pack → `remove`;
+ *   - entry, stamp≠pack OR unstamped → `skip-foreign` (leave it; warn).
+ */
+function classifyRemoval(existing: unknown, pack: string): RemovalDecision {
+  if (existing === undefined) return 'absent';
+  return provenanceOf(existing) === pack ? 'remove' : 'skip-foreign';
+}
+
+// ---------------------------------------------------------------------------
+// Claude/JSON un-registration.
+// ---------------------------------------------------------------------------
+
+/**
+ * The merge fn for REMOVING one server from the Claude surface, scoped by
+ * provenance. Returns `(doc) => doc'`:
+ *
+ *   - `mcpServers.<name>` ABSENT → return the doc UNCHANGED (idempotent no-op).
+ *   - present AND `_hqPack === pack` → delete that ONE key from a SHALLOW COPY of
+ *     `mcpServers`, preserving every sibling server and every other top-level
+ *     `~/.claude.json` key byte-for-byte. If `mcpServers` becomes empty we LEAVE an
+ *     empty `mcpServers: {}` (it round-trips cleanly and is idempotent — a second
+ *     uninstall sees the name already absent and no-ops; we do NOT delete the
+ *     `mcpServers` key itself so the surface shape stays stable across re-runs).
+ *   - present AND `_hqPack !== pack` (or unstamped) → return the doc UNCHANGED and
+ *     do NOT delete (skip-and-warn; the caller reports it). NEVER a bare name-match
+ *     delete.
+ *
+ * Never touches any OTHER server entry or any other top-level key.
+ */
+export function removeClaudeServer(
+  name: string,
+  pack: string,
+): (doc: Record<string, unknown>) => Record<string, unknown> {
+  return (doc) => {
+    const servers = (doc.mcpServers as Record<string, unknown> | undefined) ?? undefined;
+    const existing = servers ? servers[name] : undefined;
+    const decision = classifyRemoval(existing, pack);
+    if (decision !== 'remove') {
+      // absent OR skip-foreign → leave the doc untouched (idempotent / foreign-safe).
+      return doc;
+    }
+    // remove: shallow-copy mcpServers, drop ONLY this key, keep every sibling +
+    // every other top-level key. Leave an empty `mcpServers: {}` if it empties out.
+    const nextServers = { ...(servers as Record<string, unknown>) };
+    delete nextServers[name];
+    return { ...doc, mcpServers: nextServers };
+  };
+}
+
+/**
+ * A {@link ConfigFormat} for the Claude REMOVAL path: same parse/serialize/emptyDoc
+ * as {@link claudeConfigFormat}, but `assertEntry` is INVERTED — it throws IFF the
+ * name is STILL present after the write. {@link writeConfigAtomic} runs this in its
+ * verify-after-write step (and in the no-op `nextText === currentText` branch), so a
+ * successful removal verifies the entry is GONE rather than present.
+ */
+export const claudeRemovalFormat: ConfigFormat<Record<string, unknown>> = {
+  parse: claudeConfigFormat.parse,
+  serialize: claudeConfigFormat.serialize,
+  emptyDoc: claudeConfigFormat.emptyDoc,
+  assertEntry(doc, name) {
+    const servers = (doc as { mcpServers?: Record<string, unknown> }).mcpServers;
+    if (servers && typeof servers === 'object' && !Array.isArray(servers) && name in servers) {
+      throw new Error(`mcpServers.${name} is STILL present after removal`);
+    }
+  },
+};
+
+/** Options for {@link unregisterServer} / {@link unregisterClaudeServer} / {@link unregisterCodexServer}. */
+export interface UnregisterServerOptions {
+  /** The bare server name to remove (the `mcpServers` / `mcp_servers` key). */
+  name: string;
+  /** The pack being uninstalled — ONLY entries stamped with this `_hqPack` are removed. */
+  pack: string;
+  /** Injectable env (tests pass a tmpdir home so the real configs are untouched). */
+  env?: Partial<SafeWriteEnv>;
+  /** Lock tuning (tests use tiny timeouts). */
+  lock?: AcquireLockOptions;
+  /** Backup timestamp override (deterministic tests). */
+  stamp?: string;
+  /**
+   * Append an audit-log line per surface (default true). The AC requires every
+   * unregister to log; this exists ONLY to suppress logging in narrow unit tests
+   * that call {@link unregisterClaudeServer}/{@link unregisterCodexServer} directly.
+   */
+  audit?: boolean;
+}
+
+/**
+ * Classify the CURRENT on-disk entry for a name WITHOUT writing — used to decide the
+ * outcome (`removed` / `absent` / `skipped-foreign`) and to short-circuit the
+ * skip-foreign case (no write, no backup) before entering {@link writeConfigAtomic}.
+ * Reads through the same {@link ConfigFormat} the write path uses so the parse is
+ * consistent (a malformed file surfaces as {@link ConfigParseError} here too — we do
+ * not silently treat an unparseable config as "absent").
+ */
+function classifyClaudeOnDisk(
+  target: string,
+  name: string,
+  pack: string,
+): { decision: RemovalDecision; realTarget: string } {
+  const { doc } = readConfigDoc(target, claudeConfigFormat);
+  const servers = (doc.mcpServers as Record<string, unknown> | undefined) ?? undefined;
+  const existing = servers ? servers[name] : undefined;
+  return { decision: classifyRemoval(existing, pack), realTarget: realpathOrSelf(target) };
+}
+
+/**
+ * Un-register ONE server from the PINNED single Claude surface (top-level
+ * `~/.claude.json` `mcpServers`), provenance-scoped, via {@link writeConfigAtomic}.
+ *
+ *   - stamp matches this pack → REMOVE (through the safe-write path: backup + atomic
+ *     + lock + verify-ABSENT), `outcome: 'removed'`.
+ *   - entry absent → clean no-op, `outcome: 'absent'` (no write).
+ *   - entry present but foreign/unstamped → SKIP-AND-WARN, `outcome: 'skipped-foreign'`
+ *     (no write; the caller surfaces `reason`).
+ *
+ * Tolerates an absent / blank `~/.claude.json` (treated as "nothing to remove" →
+ * `absent`). Idempotent: a second uninstall of the same server sees it already gone
+ * → `absent`.
+ *
+ * @throws ConfigParseError       existing non-empty `~/.claude.json` is unparseable (ABORT)
+ * @throws ConfigPermissionError  read/lock failure other than ENOENT (ABORT)
+ * @throws PartialRegistrationError verify-after-write found the entry STILL present
+ */
+export function unregisterClaudeServer(opts: UnregisterServerOptions): UnregisterSurfaceResult {
+  assertValidServerName(opts.name);
+  const target = claudeConfigPath2(opts.env);
+
+  // Pre-classify WITHOUT writing so a foreign/absent entry never takes a backup or
+  // touches the file. (writeConfigAtomic re-reads inside the lock; the merge fn
+  // re-applies the SAME provenance policy, so this is a fast-path, not the guard.)
+  const { decision } = classifyClaudeOnDisk(target, opts.name, opts.pack);
+  if (decision === 'skip-foreign') {
+    return {
+      outcome: 'skipped-foreign',
+      changed: false,
+      realTarget: realpathOrSelf(target),
+      reason:
+        `MCP server "${opts.name}" in ~/.claude.json is not owned by pack "${opts.pack}" ` +
+        '(no matching _hqPack provenance) — left in place (skip-and-warn).',
+    };
+  }
+
+  // absent OR remove → go through the safe-write path with the REMOVAL format (which
+  // verifies ABSENCE). For `absent`, the merge returns the doc unchanged →
+  // writeConfigAtomic's nextText===currentText branch runs assertEntry (already
+  // absent ⇒ passes) ⇒ changed:false. For `remove`, the key is dropped + verified gone.
+  const res = writeConfigAtomic({
+    target,
+    pack: opts.pack,
+    format: claudeRemovalFormat,
+    merge: removeClaudeServer(opts.name, opts.pack),
+    assertName: opts.name,
+    env: opts.env,
+    lock: opts.lock,
+    stamp: opts.stamp,
+  });
+  return {
+    outcome: res.changed ? 'removed' : 'absent',
+    changed: res.changed,
+    realTarget: res.realTarget,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Codex/TOML un-registration.
+// ---------------------------------------------------------------------------
+
+/** Symbol marking a pending REMOVAL on a {@link CodexTomlDoc} (merge → serialize). */
+const PENDING_REMOVE = Symbol('hqPendingCodexRemove');
+
+/** A {@link CodexTomlDoc} that may carry a pending removal for {@link codexRemovalFormat.serialize}. */
+type CodexTomlDocWithRemove = CodexTomlDoc & {
+  [PENDING_REMOVE]?: { name: string };
+};
+
+/**
+ * The merge fn for REMOVING one server from the Codex surface, scoped by provenance.
+ *
+ *   - `mcp_servers.<name>` ABSENT → return the doc UNCHANGED with NO pending removal,
+ *     so {@link codexRemovalFormat.serialize} reproduces `originalText` byte-for-byte
+ *     (no write, comments intact) — idempotent no-op.
+ *   - present AND `_hqPack === pack` → drop the key from a copy of the parsed `value`
+ *     AND record a PENDING_REMOVE marker so `serialize` knows it must RE-SERIALIZE the
+ *     value (the append-only path cannot express a removal). Sibling tables and every
+ *     `.tools.<t>.approval_mode` sub-table survive (they live in the re-serialized
+ *     value); COMMENTS are dropped on this write (documented value-only-TOML limit).
+ *   - present AND `_hqPack !== pack` (or unstamped) → return the doc UNCHANGED, no
+ *     pending removal (skip-and-warn). NEVER a bare name-match delete.
+ *
+ * Never touches any OTHER server table or any other top-level table.
+ */
+export function removeCodexServer(
+  name: string,
+  pack: string,
+): (doc: CodexTomlDoc) => CodexTomlDoc {
+  return (doc) => {
+    const servers = (doc.value[CODEX_MCP_SERVERS_KEY] as TomlTable | undefined) ?? undefined;
+    const existing = servers ? servers[name] : undefined;
+    const decision = classifyRemoval(existing, pack);
+    if (decision !== 'remove') {
+      // absent OR skip-foreign → unchanged doc, no pending removal → serialize
+      // reproduces originalText byte-for-byte (no write; comments preserved).
+      return doc;
+    }
+    // remove: drop the key from a COPY of the servers table inside a COPY of value.
+    const nextServers = { ...(servers as TomlTable) };
+    delete nextServers[name];
+    const nextValue: TomlTable = { ...doc.value, [CODEX_MCP_SERVERS_KEY]: nextServers };
+    const next: CodexTomlDocWithRemove = {
+      value: nextValue,
+      originalText: doc.originalText,
+      [PENDING_REMOVE]: { name },
+    };
+    return next;
+  };
+}
+
+/**
+ * A {@link ConfigFormat} for the Codex REMOVAL path. It REUSES `parse`/`emptyDoc`
+ * from {@link codexConfigFormat} but supplies its OWN `serialize` + an INVERTED
+ * `assertEntry`:
+ *
+ *   - `serialize`: when a PENDING_REMOVE is present the key was actually dropped, so
+ *     we RE-SERIALIZE the modified `value` via smol-toml `stringifyToml` (this is the
+ *     only way to express a removal; it DROPS comments — documented). With NO pending
+ *     removal (no-op / foreign) we reproduce `originalText` byte-for-byte (or
+ *     `stringifyToml(value)` for a fresh doc with no original), so an unchanged doc
+ *     round-trips and `writeConfigAtomic` writes nothing.
+ *   - `assertEntry`: throws IFF `mcp_servers.<name>` is STILL present (verify-ABSENT).
+ */
+export const codexRemovalFormat: ConfigFormat<CodexTomlDoc> = {
+  parse: codexConfigFormat.parse,
+  emptyDoc: codexConfigFormat.emptyDoc,
+  serialize(doc: CodexTomlDoc): string {
+    const pending = (doc as CodexTomlDocWithRemove)[PENDING_REMOVE];
+    if (pending) {
+      // A key was actually removed — re-serialize the value (comments are dropped;
+      // sibling tables + .tools.<t>.approval_mode sub-tables are preserved as DATA).
+      return stringifyToml(doc.value);
+    }
+    if (doc.originalText !== null) {
+      // No-op removal (absent / foreign) → reproduce the original bytes exactly.
+      return doc.originalText;
+    }
+    // No original (fresh/empty doc) and nothing pending → serialize the value as-is.
+    return stringifyToml(doc.value);
+  },
+  assertEntry(doc: CodexTomlDoc, name: string): void {
+    const servers = doc.value[CODEX_MCP_SERVERS_KEY] as TomlTable | undefined;
+    if (servers && typeof servers === 'object' && !Array.isArray(servers) && name in servers) {
+      throw new Error(`mcp_servers.${name} is STILL present after removal`);
+    }
+  },
+};
+
+/**
+ * Classify the CURRENT on-disk Codex entry for a name WITHOUT writing — mirror of
+ * {@link classifyClaudeOnDisk}. A malformed config surfaces as {@link ConfigParseError}
+ * (fail-closed; we never treat an unparseable file as "absent").
+ */
+function classifyCodexOnDisk(
+  target: string,
+  name: string,
+  pack: string,
+): { decision: RemovalDecision; realTarget: string } {
+  const { doc } = readConfigDoc(target, codexConfigFormat);
+  const servers = (doc.value[CODEX_MCP_SERVERS_KEY] as TomlTable | undefined) ?? undefined;
+  const existing = servers ? servers[name] : undefined;
+  return { decision: classifyRemoval(existing, pack), realTarget: realpathOrSelf(target) };
+}
+
+/**
+ * Un-register ONE server from the GLOBAL Codex surface (`~/.codex/config.toml`
+ * `[mcp_servers.<name>]`), provenance-scoped, via {@link writeConfigAtomic}. A
+ * FIRST-CLASS SKIP when the Codex runtime is absent (`~/.codex` missing — never
+ * fabricated): nothing to un-register, no crash.
+ *
+ *   - stamp matches this pack → REMOVE (safe-write path; verify-ABSENT). The removal
+ *     write RE-SERIALIZES the value, which DROPS comments (documented limitation) but
+ *     preserves sibling tables + `.tools.<t>.approval_mode` sub-tables.
+ *   - entry absent → clean no-op, `outcome: 'absent'` (no write; comments intact).
+ *   - entry present but foreign/unstamped → SKIP-AND-WARN, `outcome: 'skipped-foreign'`.
+ *
+ * @returns the surface result, or a {@link UnregisterSurfaceSkip} (Codex absent).
+ * @throws ConfigParseError       existing config.toml is malformed (fail-closed)
+ * @throws ConfigPermissionError / PartialRegistrationError (from the core)
+ */
+export function unregisterCodexServer(
+  opts: UnregisterServerOptions,
+): UnregisterSurfaceResult | UnregisterSurfaceSkip {
+  assertValidServerName(opts.name);
+  const env = resolveEnv(opts.env);
+
+  // FIRST-CLASS SKIP: no Codex runtime → nothing to remove, do not fabricate ~/.codex.
+  if (!isCodexInstalled(env)) {
+    return {
+      skipped: true,
+      reason: 'Codex runtime absent (~/.codex missing) — first-class skip, nothing to un-register',
+    };
+  }
+
+  const target = codexConfigPath(env);
+
+  // Pre-classify WITHOUT writing (mirror of the Claude arm).
+  const { decision } = classifyCodexOnDisk(target, opts.name, opts.pack);
+  if (decision === 'skip-foreign') {
+    return {
+      outcome: 'skipped-foreign',
+      changed: false,
+      realTarget: realpathOrSelf(target),
+      reason:
+        `MCP server "${opts.name}" in ~/.codex/config.toml is not owned by pack "${opts.pack}" ` +
+        '(no matching _hqPack provenance) — left in place (skip-and-warn).',
+    };
+  }
+
+  const res = writeConfigAtomic<CodexTomlDoc>({
+    target,
+    pack: opts.pack,
+    format: codexRemovalFormat,
+    merge: removeCodexServer(opts.name, opts.pack),
+    assertName: opts.name,
+    env: opts.env,
+    lock: opts.lock,
+    stamp: opts.stamp,
+  });
+  return {
+    outcome: res.changed ? 'removed' : 'absent',
+    changed: res.changed,
+    realTarget: res.realTarget,
+  };
+}
+
+/**
+ * Fan ONE server's un-registration out across BOTH per-runtime surfaces — the mirror
+ * of {@link registerServer}. Claude is inspected first (consistent with register's
+ * ordering, though for removal the ordering is less critical: each surface is
+ * independent and idempotent). The Codex arm is a FIRST-CLASS SKIP when `~/.codex` is
+ * absent. Each arm is provenance-scoped and skip-and-warns on a foreign entry —
+ * neither surface aborts the other.
+ */
+export function unregisterServer(opts: UnregisterServerOptions): UnregisterServerResult {
+  assertValidServerName(opts.name);
+
+  const env = resolveEnv(opts.env);
+  const audit = opts.audit ?? true;
+  const claudeTarget = claudeConfigPath(env);
+  const codexTarget = codexConfigPath(env);
+
+  // Derive transport/target from the on-disk def BEFORE removal (no manifest at
+  // unregister time). If neither surface has the def, fall back to unknown/'' —
+  // the hashes + action + server + pack are the load-bearing audit fields.
+  const onDisk = audit
+    ? readOnDiskTransportTarget(env, opts.name)
+    : { transport: 'unknown', target: '' };
+
+  // Claude arm: capture prevHash, emit, log per outcome.
+  const claudePrevHash = audit ? hashFileContents(claudeTarget) : '';
+  let claude: UnregisterSurfaceResult;
+  try {
+    claude = unregisterClaudeServer(opts);
+  } catch (e) {
+    if (audit) {
+      appendAuditLog(env, {
+        ts: new Date().toISOString(),
+        action: 'unregister',
+        pack: opts.pack,
+        server: opts.name,
+        transport: onDisk.transport,
+        target: onDisk.target,
+        file: claudeTarget,
+        prevHash: claudePrevHash,
+        newHash: hashFileContents(claudeTarget),
+        result: 'error',
+      });
+    }
+    throw e;
+  }
+  if (audit) {
+    appendAuditLog(env, {
+      ts: new Date().toISOString(),
+      action: 'unregister',
+      pack: opts.pack,
+      server: opts.name,
+      transport: onDisk.transport,
+      target: onDisk.target,
+      file: claude.realTarget,
+      prevHash: claudePrevHash,
+      newHash: hashFileContents(claude.realTarget),
+      result: unregisterResultFor(claude.outcome),
+    });
+  }
+
+  // Codex arm: capture prevHash, emit, log per outcome (or a skip line).
+  const codexPrevHash = audit ? hashFileContents(codexTarget) : '';
+  let codex: UnregisterSurfaceResult | UnregisterSurfaceSkip;
+  try {
+    codex = unregisterCodexServer(opts);
+  } catch (e) {
+    if (audit) {
+      appendAuditLog(env, {
+        ts: new Date().toISOString(),
+        action: 'unregister',
+        pack: opts.pack,
+        server: opts.name,
+        transport: onDisk.transport,
+        target: onDisk.target,
+        file: codexTarget,
+        prevHash: codexPrevHash,
+        newHash: hashFileContents(codexTarget),
+        result: 'error',
+      });
+    }
+    throw e;
+  }
+  if (audit) {
+    const skipped = 'skipped' in codex && codex.skipped === true;
+    appendAuditLog(env, {
+      ts: new Date().toISOString(),
+      action: 'unregister',
+      pack: opts.pack,
+      server: opts.name,
+      transport: onDisk.transport,
+      target: onDisk.target,
+      file: skipped ? codexTarget : (codex as UnregisterSurfaceResult).realTarget,
+      prevHash: codexPrevHash,
+      newHash: skipped ? codexPrevHash : hashFileContents((codex as UnregisterSurfaceResult).realTarget),
+      result: skipped ? 'skipped' : unregisterResultFor((codex as UnregisterSurfaceResult).outcome),
+    });
+  }
+
+  return { claude, codex };
+}
+
+/** Map an {@link UnregisterOutcome} to the audit-log {@link AuditResult}. */
+function unregisterResultFor(outcome: UnregisterOutcome): AuditResult {
+  if (outcome === 'removed') return 'unregistered';
+  if (outcome === 'absent') return 'noop';
+  return 'skipped'; // skipped-foreign — the entry was left in place.
+}
+
+/**
+ * Read the transport + target off the on-disk server def (for the audit line at
+ * UNREGISTER time, where there is no manifest). Prefers the Claude def, falls back
+ * to the Codex def, and returns `{ transport:'unknown', target:'' }` when neither
+ * surface has the server or a config is absent/unparseable. NEVER reads or echoes
+ * a header/secret. Best-effort: any error degrades to unknown/'' (never throws).
+ */
+function readOnDiskTransportTarget(
+  env: SafeWriteEnv,
+  name: string,
+): { transport: string; target: string } {
+  // Claude first.
+  try {
+    const { doc } = readConfigDoc(claudeConfigPath(env), claudeConfigFormat);
+    const servers = doc.mcpServers as Record<string, unknown> | undefined;
+    const def = servers?.[name];
+    const tt = transportTargetOfDef(def);
+    if (tt) return tt;
+  } catch {
+    // Unparseable/absent Claude config — fall through to Codex.
+  }
+  // Codex fallback.
+  if (isCodexInstalled(env)) {
+    try {
+      const { doc } = readConfigDoc(codexConfigPath(env), codexConfigFormat);
+      const servers = doc.value[CODEX_MCP_SERVERS_KEY] as Record<string, unknown> | undefined;
+      const def = servers?.[name];
+      const tt = transportTargetOfDef(def);
+      if (tt) return tt;
+    } catch {
+      // Unparseable/absent Codex config — fall through to unknown.
+    }
+  }
+  return { transport: 'unknown', target: '' };
+}
+
+/**
+ * Extract `{ transport, target }` from a server def object (Claude JSON or Codex
+ * TOML table). `target` is the url (http/sse) or command(+args) (stdio) — NEVER a
+ * header/secret. Returns `null` when `def` is not an object (so the caller can
+ * fall through to the other surface).
+ */
+function transportTargetOfDef(def: unknown): { transport: string; target: string } | null {
+  if (def === null || typeof def !== 'object' || Array.isArray(def)) return null;
+  const d = def as Record<string, unknown>;
+  const type = typeof d.type === 'string' ? d.type : 'unknown';
+  let target = '';
+  if ((type === 'http' || type === 'sse') && typeof d.url === 'string') {
+    target = d.url;
+  } else if (typeof d.command === 'string') {
+    const args = Array.isArray(d.args) && d.args.length > 0 ? ` ${d.args.join(' ')}` : '';
+    target = `${d.command}${args}`;
+  } else if (typeof d.url === 'string') {
+    target = d.url;
+  }
+  return { transport: type, target };
+}
+
+/**
+ * Un-register one pack's MCP servers from the shared agent configs — the public seam
+ * the UNINSTALL path calls, mirroring {@link registerMcpServers}. Unlike register, it
+ * needs NO manifest loader: removal keys off the server NAME + the pack's PROVENANCE
+ * stamp on the on-disk entry, not the manifest. So the signature is simpler:
+ * `(pkg, names, { env?, lock?, stamp? })`.
+ *
+ * For each name it fans out via {@link unregisterServer} (Claude + Codex), removing
+ * ONLY entries stamped `_hqPack === pkg` and skip-and-warning on any foreign/unstamped
+ * same-named entry. Tolerant of an absent Codex runtime / absent config files, and
+ * idempotent (uninstalling an already-removed pack is a clean no-op).
+ *
+ * @param pkg   the pack name being uninstalled (the provenance to match)
+ * @param names the bare server names from `contributes.mcp`
+ * @returns one {@link UnregisterServerResult} per server, in `names` order
+ */
+export function unregisterMcpServers(
+  pkg: string,
+  names: string[],
+  options?: {
+    /** Injectable env (tests pass a tmpdir home). */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning + backup stamp passthrough (tests). */
+    lock?: AcquireLockOptions;
+    stamp?: string;
+  },
+): UnregisterServerResult[] {
+  return names.map((name) => {
+    assertValidServerName(name);
+    return unregisterServer({
+      name,
+      pack: pkg,
+      env: options?.env,
+      lock: options?.lock,
+      stamp: options?.stamp,
+    });
+  });
+}