@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/dist/commands/mcp-registration.js

@@ -0,0 +1,2001 @@
+/**
+ * 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.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d4f678fe-c88f-5d08-b6bc-1e591ac8c4b6")}catch(e){}}();
+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 class McpRegistrationError extends Error {
+    constructor(message) {
+        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 {
+    code = 'ConfigParseError';
+}
+/**
+ * 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 {
+    code = 'ConfigPermissionError';
+}
+/**
+ * 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 {
+    code = 'McpNameCollisionError';
+}
+/**
+ * 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 {
+    code = 'CodexNotInstalledError';
+}
+/** A per-server MCP manifest failed shape/transport validation. */
+export class McpManifestError extends McpRegistrationError {
+    code = 'McpManifestError';
+}
+/**
+ * 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 {
+    code = 'PartialRegistrationError';
+    /** The backup directory the target was (or could be) restored from. */
+    backupDir;
+    constructor(message, backupDir) {
+        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. */
+    code = 'NotImplemented';
+    /** The PRD story that lands the real implementation. */
+    story;
+    constructor(message, story = 'US-007') {
+        super(message);
+        this.name = 'NotImplementedError';
+        this.story = story;
+        Object.setPrototypeOf(this, NotImplementedError.prototype);
+    }
+}
+/** Resolve the env, defaulting `home` to the real `os.homedir()` for production callers. */
+export function resolveEnv(env) {
+    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) {
+    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) {
+    return path.join(env.home, '.hq', 'logs', 'mcp-registry.log');
+}
+/**
+ * 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) {
+    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, entry, secrets = []) {
+    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) {
+    return path.join(env.home, '.codex');
+}
+/** `~/.codex/config.toml` — the GLOBAL Codex MCP config (not the project file). */
+export function codexConfigPath(env) {
+    return path.join(codexHome(env), 'config.toml');
+}
+/** True iff the Codex runtime is installed (`~/.codex` exists). Never creates it. */
+export function isCodexInstalled(env) {
+    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) {
+    return path.join(env.home, '.claude.json');
+}
+/** `~/.mcp.json` — the project-pinned Claude surface (a symlink on this host). */
+export function mcpJsonPath(env) {
+    return path.join(env.home, '.mcp.json');
+}
+/**
+ * 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 = {
+    parse(text) {
+        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;
+    },
+    serialize(doc) {
+        return `${JSON.stringify(doc, null, 2)}\n`;
+    },
+    emptyDoc() {
+        return {};
+    },
+    assertEntry() {
+        // 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(target, format) {
+    let text;
+    try {
+        text = fs.readFileSync(target, 'utf-8');
+    }
+    catch (e) {
+        const err = e;
+        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.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) {
+    // 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;
+/** The lockfile path for a target: `~/.<basename>.hqlock` (a sibling, hidden). */
+export function lockPathFor(target) {
+    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) {
+    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.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, opts = {}) {
+    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;
+            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) {
+    try {
+        fs.unlinkSync(lock.lockPath);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+}
+/** Read the PID written into a lockfile, or NaN if unreadable/garbage. */
+function readLockPid(lockPath) {
+    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) {
+    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, staleMs, isPidAlive, now) {
+    let st;
+    let originalBody;
+    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.code !== 'ENOENT')
+            return false;
+    }
+    return true;
+}
+/** Busy-sleep for `ms` (small poll intervals only — bounded by the wait deadline). */
+function sleepMs(ms) {
+    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 = new Date()) {
+    const p = (n, 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, target, pack, stamp = rescueStamp()) {
+    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.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.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, backupDir) {
+    const real = realpathOrSelf(target);
+    const absentMarker = path.join(backupDir, '.absent');
+    if (fs.existsSync(absentMarker)) {
+        try {
+            fs.unlinkSync(real);
+        }
+        catch (e) {
+            if (e.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, _depth = 0) {
+    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) {
+    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, data) {
+    const dir = path.dirname(realTarget);
+    const tmp = path.join(dir, `.${path.basename(realTarget)}.tmp.${process.pid}.${Date.now()}`);
+    let fd;
+    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) {
+    let dirFd;
+    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 */
+            }
+        }
+    }
+}
+/**
+ * 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(opts) {
+    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.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(format, doc, name, target, backupDir) {
+    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.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, backupDir) {
+    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';
+/** 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) {
+    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, resolve, secretSink) {
+    return value.replace(SECRET_REF_RE, (_match, name) => {
+        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, secrets) {
+    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 = {
+    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.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, pack, resolve, secretSink) {
+    const def = { 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, resolve, secretSink) {
+    const out = {};
+    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, b) {
+    return canonicalJson(stripProvenance(a)) === canonicalJson(stripProvenance(b));
+}
+/** A shallow copy of an object with the `_hqPack` key removed (for equality). */
+function stripProvenance(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return v;
+    const { [HQ_PACK_PROVENANCE_KEY]: _omit, ...rest } = v;
+    return rest;
+}
+/** Order-insensitive JSON for object keys (so key order never spoofs a collision). */
+function canonicalJson(v) {
+    return JSON.stringify(v, (_k, val) => {
+        if (val && typeof val === 'object' && !Array.isArray(val)) {
+            const obj = val;
+            return Object.keys(obj)
+                .sort()
+                .reduce((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, def) {
+    return (doc) => {
+        const servers = { ...(doc.mcpServers ?? {}) };
+        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 };
+    };
+}
+/** Default resolver: there is NO secret context, so any `${secret:}` ref is an error. */
+const noSecretResolver = () => 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) {
+    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) {
+    assertValidServerName(opts.name);
+    const resolve = opts.resolveSecret ?? noSecretResolver;
+    const secretSink = new Set();
+    // 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) {
+    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) {
+    // 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;
+    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;
+    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.realTarget,
+            prevHash: codexPrevHash,
+            newHash: skipped ? codexPrevHash : hashFileContents(codex.realTarget),
+            result: skipped
+                ? 'skipped'
+                : codex.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) {
+    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, names, options) {
+    // 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,
+        });
+    });
+}
+/** 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, def) {
+    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 = {
+    parse(text) {
+        // 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);
+        return { value, originalText: text };
+    },
+    serialize(doc) {
+        const pending = doc[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() {
+        return { value: {}, originalText: null };
+    },
+    assertEntry(doc, name) {
+        const servers = doc.value[CODEX_MCP_SERVERS_KEY];
+        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');
+/** Return a copy of `value` with `mcp_servers.<name> = def` set (used for fresh-file serialize). */
+function withServer(value, name, def) {
+    const servers = { ...(value[CODEX_MCP_SERVERS_KEY] ?? {}) };
+    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, name, def) {
+    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, pack, resolve, secretSink) {
+    const def = { 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) {
+    if (!tools || typeof tools !== 'object')
+        return undefined;
+    const out = {};
+    for (const [tool, spec] of Object.entries(tools)) {
+        const mode = spec?.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, def) {
+    return (doc) => {
+        const servers = doc.value[CODEX_MCP_SERVERS_KEY] ?? {};
+        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 = {
+            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) {
+    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();
+    // 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({
+            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;
+    }
+}
+/**
+ * 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) {
+    if (def === null || typeof def !== 'object' || Array.isArray(def))
+        return undefined;
+    const stamp = def[HQ_PACK_PROVENANCE_KEY];
+    return typeof stamp === 'string' ? stamp : undefined;
+}
+/**
+ * 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, pack) {
+    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, pack) {
+    return (doc) => {
+        const servers = doc.mcpServers ?? 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 };
+        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 = {
+    parse: claudeConfigFormat.parse,
+    serialize: claudeConfigFormat.serialize,
+    emptyDoc: claudeConfigFormat.emptyDoc,
+    assertEntry(doc, name) {
+        const servers = doc.mcpServers;
+        if (servers && typeof servers === 'object' && !Array.isArray(servers) && name in servers) {
+            throw new Error(`mcpServers.${name} is STILL present after removal`);
+        }
+    },
+};
+/**
+ * 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, name, pack) {
+    const { doc } = readConfigDoc(target, claudeConfigFormat);
+    const servers = doc.mcpServers ?? 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) {
+    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');
+/**
+ * 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, pack) {
+    return (doc) => {
+        const servers = doc.value[CODEX_MCP_SERVERS_KEY] ?? 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 };
+        delete nextServers[name];
+        const nextValue = { ...doc.value, [CODEX_MCP_SERVERS_KEY]: nextServers };
+        const next = {
+            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 = {
+    parse: codexConfigFormat.parse,
+    emptyDoc: codexConfigFormat.emptyDoc,
+    serialize(doc) {
+        const pending = doc[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, name) {
+        const servers = doc.value[CODEX_MCP_SERVERS_KEY];
+        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, name, pack) {
+    const { doc } = readConfigDoc(target, codexConfigFormat);
+    const servers = doc.value[CODEX_MCP_SERVERS_KEY] ?? 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) {
+    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({
+        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) {
+    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;
+    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;
+    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.realTarget,
+            prevHash: codexPrevHash,
+            newHash: skipped ? codexPrevHash : hashFileContents(codex.realTarget),
+            result: skipped ? 'skipped' : unregisterResultFor(codex.outcome),
+        });
+    }
+    return { claude, codex };
+}
+/** Map an {@link UnregisterOutcome} to the audit-log {@link AuditResult}. */
+function unregisterResultFor(outcome) {
+    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, name) {
+    // Claude first.
+    try {
+        const { doc } = readConfigDoc(claudeConfigPath(env), claudeConfigFormat);
+        const servers = doc.mcpServers;
+        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];
+            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) {
+    if (def === null || typeof def !== 'object' || Array.isArray(def))
+        return null;
+    const d = def;
+    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, names, options) {
+    return names.map((name) => {
+        assertValidServerName(name);
+        return unregisterServer({
+            name,
+            pack: pkg,
+            env: options?.env,
+            lock: options?.lock,
+            stamp: options?.stamp,
+        });
+    });
+}
+//# sourceMappingURL=mcp-registration.js.map
+//# debugId=d4f678fe-c88f-5d08-b6bc-1e591ac8c4b6