@indigoai-us/hq-cli 5.49.0 → 5.50.1

package/dist/commands/mcp-registration.d.ts

@@ -0,0 +1,905 @@
+/**
+ * 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.
+ */
+/** Base for every MCP-registration error; carries a stable machine-checkable `code`. */
+export declare abstract class McpRegistrationError extends Error {
+    abstract readonly code: string;
+    constructor(message: string);
+}
+/**
+ * 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 declare class ConfigParseError extends McpRegistrationError {
+    readonly 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 declare class ConfigPermissionError extends McpRegistrationError {
+    readonly 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 declare class McpNameCollisionError extends McpRegistrationError {
+    readonly 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 declare class CodexNotInstalledError extends McpRegistrationError {
+    readonly code: "CodexNotInstalledError";
+}
+/** A per-server MCP manifest failed shape/transport validation. */
+export declare class McpManifestError extends McpRegistrationError {
+    readonly 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 declare class PartialRegistrationError extends McpRegistrationError {
+    readonly code: "PartialRegistrationError";
+    /** The backup directory the target was (or could be) restored from. */
+    readonly backupDir: string | undefined;
+    constructor(message: string, backupDir?: string);
+}
+/**
+ * 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 declare class NotImplementedError extends Error {
+    /** Stable, machine-checkable discriminator. */
+    readonly code: "NotImplemented";
+    /** The PRD story that lands the real implementation. */
+    readonly story: string;
+    constructor(message: string, story?: string);
+}
+/** Roots the substrate's view of the filesystem; everything is derived from `home`. */
+export interface SafeWriteEnv {
+    /** The user home directory. Tests MUST pass a tmpdir here. */
+    home: string;
+}
+/** Resolve the env, defaulting `home` to the real `os.homedir()` for production callers. */
+export declare function resolveEnv(env?: Partial<SafeWriteEnv>): SafeWriteEnv;
+/** `~/.hq/backups/mcp` — the timestamped backup root (reuses the hq rescue location). */
+export declare function backupRoot(env: SafeWriteEnv): string;
+/** `~/.hq/logs/mcp-registry.log` — the append-only JSONL audit log (mirrors backupRoot style). */
+export declare function mcpRegistryLogPath(env: SafeWriteEnv): string;
+/** The action recorded on an audit line. */
+export type AuditAction = 'register' | 'unregister';
+/**
+ * The result recorded on an audit line:
+ *   - `registered`   — a register write that changed the file.
+ *   - `unregistered` — an unregister write that removed an entry (file changed).
+ *   - `noop`         — an idempotent no-op (changed:false; prevHash === newHash).
+ *   - `skipped`      — a surface deliberately not acted on (e.g. Codex absent, or a
+ *                      foreign/unstamped entry left in place). PARTIAL is auditable.
+ *   - `error`        — the surface emit threw (the operation failed for this surface).
+ */
+export type AuditResult = 'registered' | 'unregistered' | 'noop' | 'skipped' | 'error';
+/**
+ * One append-only audit-log entry. EXACT shape (field order is the JSON key order):
+ *   `{ ts, action, pack, server, transport, target, file, prevHash, newHash, result }`.
+ * `target` is a url (http/sse) or command(+args) (stdio) — NEVER a header/secret.
+ * `prevHash`/`newHash` are sha256 (hex) of the config file bytes before/after the
+ * write ('' when the file is absent).
+ */
+export interface AuditLogEntry {
+    /** ISO8601 timestamp (`new Date().toISOString()`). */
+    ts: string;
+    /** `register` | `unregister`. */
+    action: AuditAction;
+    /** The pack name. */
+    pack: string;
+    /** The bare server name. */
+    server: string;
+    /** The transport (`http` | `stdio` | `sse` | `unknown`). */
+    transport: string;
+    /** url (http/sse) or command(+args joined) (stdio); '' when unknown. NEVER a secret. */
+    target: string;
+    /** The realpath the surface wrote to, or the config path for a skip; '' when none. */
+    file: string;
+    /** sha256 (hex) of the config file bytes BEFORE the write, or '' when absent. */
+    prevHash: string;
+    /** sha256 (hex) of the config file bytes AFTER the write, or '' when removed/absent. */
+    newHash: string;
+    /** registered | unregistered | noop | skipped | error. */
+    result: AuditResult;
+}
+/**
+ * sha256 (hex) of a file's CONTENTS, or '' when the file is absent/unreadable.
+ * Hashing the WHOLE file is intentional — it proves a mutation happened without
+ * leaking any content into the audit log.
+ */
+export declare function hashFileContents(target: string): string;
+/**
+ * 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 declare function appendAuditLog(env: SafeWriteEnv, entry: AuditLogEntry, secrets?: Iterable<string>): void;
+/** `~/.codex` — its ABSENCE is a first-class skip signal (never fabricated). */
+export declare function codexHome(env: SafeWriteEnv): string;
+/** `~/.codex/config.toml` — the GLOBAL Codex MCP config (not the project file). */
+export declare function codexConfigPath(env: SafeWriteEnv): string;
+/** True iff the Codex runtime is installed (`~/.codex` exists). Never creates it. */
+export declare function isCodexInstalled(env: SafeWriteEnv): boolean;
+/** `~/.claude.json` — the PINNED single Claude surface (top-level mcpServers). */
+export declare function claudeConfigPath(env: SafeWriteEnv): string;
+/** `~/.mcp.json` — the project-pinned Claude surface (a symlink on this host). */
+export declare function mcpJsonPath(env: SafeWriteEnv): string;
+/** Outcome of {@link readConfigDoc}: a parsed doc plus whether the file pre-existed. */
+export interface ReadConfigResult<T> {
+    /** The parsed doc, or the `emptyDoc` when the file is absent/empty. */
+    doc: T;
+    /** False when the file did not exist (ENOENT) or was 0-byte/whitespace. */
+    existed: boolean;
+}
+/**
+ * A config format: how to parse a file's text into a doc, serialize a doc back
+ * to text, and assert a named entry is present after a write. Lets the SAME
+ * safe-write core drive JSON (Claude) and TOML (Codex) without duplicating the
+ * dangerous read/lock/backup/verify parts.
+ *
+ * `parse` MUST throw on malformed NON-EMPTY input (the core maps that throw to
+ * {@link ConfigParseError} and ABORTS). `emptyDoc` is the doc to use when the
+ * file is absent or blank.
+ */
+export interface ConfigFormat<T> {
+    /** Parse non-empty file text into a doc; throw on malformed input. */
+    parse: (text: string) => T;
+    /** Serialize a doc back to file text. */
+    serialize: (doc: T) => string;
+    /** The doc representing an empty/new container (ENOENT or blank file). */
+    emptyDoc: () => T;
+    /** Throw iff `name` is NOT present (and well-formed) in `doc` — drives verify-after-write. */
+    assertEntry: (doc: T, name: string) => void;
+}
+/**
+ * Built-in JSON {@link ConfigFormat} for the Claude surfaces. Pretty-prints with
+ * a trailing newline; an empty doc is `{}`. Parsing the empty string is the
+ * caller's responsibility (the core normalizes blank files to `emptyDoc` BEFORE
+ * calling `parse`), so `parse` here always sees non-empty text.
+ */
+export declare const jsonFormat: ConfigFormat<Record<string, unknown>>;
+/**
+ * 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 declare function readConfigDoc<T>(target: string, format: ConfigFormat<T>): ReadConfigResult<T>;
+/**
+ * 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 declare function sanitizeParserMessage(message: string): string;
+/** Default stale-lock timeout — a lock older than this whose PID is dead is broken. */
+export declare const DEFAULT_LOCK_STALE_MS = 30000;
+/** Default total time to wait for a held lock before giving up. */
+export declare const DEFAULT_LOCK_WAIT_MS = 10000;
+/** A held advisory lock; release with {@link releaseLock} (idempotent). */
+export interface ConfigLock {
+    /** The lockfile path (`~/.<basename>.hqlock`). */
+    lockPath: string;
+}
+/** Options for {@link acquireLock} — overridable so tests can use tiny timeouts. */
+export interface AcquireLockOptions {
+    /** Age beyond which a dead-PID lock is considered stale + breakable. */
+    staleMs?: number;
+    /** Total time to spin waiting for a live lock before throwing. */
+    waitMs?: number;
+    /** Poll interval while waiting. */
+    pollMs?: number;
+    /** Injectable "is this PID alive?" check (tests stub it; prod uses `kill -0`). */
+    isPidAlive?: (pid: number) => boolean;
+    /** Injectable clock (tests). */
+    now?: () => number;
+}
+/** The lockfile path for a target: `~/.<basename>.hqlock` (a sibling, hidden). */
+export declare function lockPathFor(target: string): string;
+/**
+ * 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 declare function acquireLock(target: string, opts?: AcquireLockOptions): ConfigLock;
+/** Release a held lock. Idempotent — a missing lockfile is not an error. */
+export declare function releaseLock(lock: ConfigLock): void;
+/** UTC `YYYY-MM-DDTHH-MM-SSZ` (dash-separated) — the hq rescue timestamp format. */
+export declare function rescueStamp(d?: Date): string;
+/**
+ * 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 declare function backupConfig(env: SafeWriteEnv, target: string, pack: string, stamp?: string): string;
+/**
+ * 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 declare function restoreFromBackup(target: string, backupDir: string): void;
+/**
+ * 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 declare function realpathOrSelf(p: string, _depth?: number): string;
+/**
+ * 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 declare function atomicReplace(realTarget: string, data: string | Buffer): void;
+/** Options for {@link writeConfigAtomic}. */
+export interface WriteConfigOptions<T> {
+    /** The config file to merge into (a symlink is resolved before the rename). */
+    target: string;
+    /** The pack name — labels the backup directory. */
+    pack: string;
+    /** The format (parser/serializer/assertEntry) for `target`. */
+    format: ConfigFormat<T>;
+    /**
+     * Pure merge: receive the current doc, return the NEXT doc. MUST NOT mutate the
+     * input in a way that survives a throw — the substrate re-reads inside the lock
+     * and calls this on the locked doc, so it should be deterministic. Throwing
+     * (e.g. {@link McpNameCollisionError}) aborts the write cleanly.
+     */
+    merge: (doc: T) => T;
+    /** The server name to assert present after the write (verify-after-write). */
+    assertName: string;
+    /** Injectable env (tests pass a tmpdir home). */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning (tests use tiny timeouts). */
+    lock?: AcquireLockOptions;
+    /** Backup timestamp override (tests / deterministic naming). */
+    stamp?: string;
+}
+/** Result of a successful {@link writeConfigAtomic}. */
+export interface WriteConfigResult {
+    /** Whether the file changed (false = idempotent no-op; the merge returned an equal doc). */
+    changed: boolean;
+    /** The backup directory taken before the write (restore target). */
+    backupDir: string;
+    /** The realpath the bytes were written to (resolved symlink). */
+    realTarget: string;
+}
+/**
+ * Crash-safe, reversible, lock-guarded merge-write of one entry into a
+ * user-global agent config. Implements the full review-report §6.2 algorithm:
+ * lock -> backup -> read (shadow-normalized) -> RE-READ in lock -> merge ->
+ * serialize -> atomic temp+fsync+rename onto realpath -> verify -> restore on
+ * failure. Releases the lock in `finally`.
+ *
+ * Idempotent: if `merge` returns a doc byte-identical (post-serialize) to the
+ * current file, no write happens (`changed: false`) — re-runs from ANY state,
+ * including PARTIAL, are safe.
+ *
+ * @throws ConfigParseError       existing non-empty file is unparseable (ABORT, nothing written)
+ * @throws ConfigPermissionError  read/lock failure other than ENOENT (ABORT)
+ * @throws PartialRegistrationError verify-after-write failed; target restored from backup
+ * @throws (whatever `merge` throws, e.g. McpNameCollisionError) — aborts before any write
+ */
+export declare function writeConfigAtomic<T>(opts: WriteConfigOptions<T>): WriteConfigResult;
+/** Server-name charset gate: load-bearing as the `mcp__<name>__*` tool namespace. */
+export declare const MCP_SERVER_NAME_RE: RegExp;
+/** The provenance key stamped onto every HQ-registered server (US-009 uninstall scope). */
+export declare const HQ_PACK_PROVENANCE_KEY = "_hqPack";
+/**
+ * A per-server MCP manifest as shipped in a pack (`mcp/<name>.json`). The shape is
+ * validated upstream by US-005's `validateMcpManifest`; here we treat it as a
+ * read-only record and only touch `headers`/`env` for secret resolution. `type`
+ * and the transport fields pass through to the emitted Claude server def verbatim.
+ */
+export interface McpManifest {
+    type: 'http' | 'stdio' | 'sse';
+    url?: string;
+    headers?: Record<string, string>;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    tools?: Record<string, unknown>;
+}
+/**
+ * Resolve a `${secret:NAME}` reference to its plaintext value, or return `null`
+ * when the secret is unavailable (un-minted / TTL-expired / no company context).
+ * Production binds this to `secrets-cache.ts` (`readCache(companyUid, NAME)`,
+ * AES-256-GCM, 0600, 5-min TTL); TESTS inject a pure map so they NEVER read the
+ * real encrypted cache. Returning `null` for a referenced secret is a hard error
+ * at emit (we refuse to write a broken header), distinct from a name with no
+ * reference at all.
+ */
+export type SecretResolver = (name: string) => string | null;
+/** True iff `value` contains at least one `${secret:NAME}` reference. */
+export declare function hasSecretRef(value: string): boolean;
+/**
+ * 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 declare function resolveSecretRefs(value: string, resolve: SecretResolver, secretSink: Set<string>): string;
+/** The redaction marker substituted for any resolved secret value in output. */
+export declare const SECRET_REDACTION = "\u00ABredacted\u00BB";
+/**
+ * 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 declare function redactSecrets(text: string, secrets: Iterable<string>): string;
+/**
+ * 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 declare const claudeConfigFormat: ConfigFormat<Record<string, unknown>>;
+/**
+ * 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 declare function buildClaudeServerDef(manifest: McpManifest, pack: string, resolve: SecretResolver, secretSink: Set<string>): Record<string, unknown>;
+/**
+ * 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 declare function serverDefsEqual(a: unknown, b: unknown): boolean;
+/**
+ * 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 declare function mergeClaudeServer(name: string, def: Record<string, unknown>): (doc: Record<string, unknown>) => Record<string, unknown>;
+/** Options for {@link registerServer} / {@link registerClaudeServer}. */
+export interface RegisterServerOptions {
+    /** The bare server name (the `mcpServers` key + `mcp__<name>__*` namespace). */
+    name: string;
+    /** The shape-validated per-server manifest (`mcp/<name>.json`). */
+    manifest: McpManifest;
+    /** The pack name — stamped as `_hqPack` provenance + labels the backup dir. */
+    pack: string;
+    /** Resolves `${secret:NAME}` at emit. Defaults to a no-secret resolver (errors on any ref). */
+    resolveSecret?: SecretResolver;
+    /** Injectable env (tests pass a tmpdir home so the real ~/.claude.json is untouched). */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning (tests use tiny timeouts). */
+    lock?: AcquireLockOptions;
+    /** Backup timestamp override (deterministic tests). */
+    stamp?: string;
+    /**
+     * Append an audit-log line per surface (default true). The AC requires every
+     * register to log; this exists ONLY to suppress logging in narrow unit tests
+     * (e.g. {@link registerClaudeServer}/{@link registerCodexServer} are called
+     * directly there and do their own thing). The audit append goes through the
+     * injected `env.home`, so in tests it lands in the tmpdir — never the real ~/.
+     */
+    audit?: boolean;
+}
+/** Outcome of registering one server into one surface. */
+export interface RegisterSurfaceResult {
+    /** Whether the surface's file actually changed (false = idempotent no-op). */
+    changed: boolean;
+    /** The realpath the bytes were written to (resolved symlink). */
+    realTarget: string;
+}
+/** A surface that was deliberately not acted on (e.g. Codex-absent host). */
+export interface RegisterSurfaceSkip {
+    /** Discriminant: this surface was skipped, not written. */
+    skipped: true;
+    /** Human-readable reason (e.g. "Codex runtime absent"). */
+    reason: string;
+}
+/** Outcome of {@link registerServer} — one entry per runtime surface acted on. */
+export interface RegisterServerResult {
+    /** The Claude/JSON surface result (always present — US-007). */
+    claude: RegisterSurfaceResult;
+    /**
+     * The Codex/TOML surface result (US-008), or a first-class SKIP when the Codex
+     * runtime is absent (`~/.codex` missing — never fabricated).
+     */
+    codex: RegisterSurfaceResult | RegisterSurfaceSkip;
+}
+/**
+ * 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 declare function assertValidServerName(name: string): void;
+/**
+ * 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 declare function registerClaudeServer(opts: RegisterServerOptions): RegisterSurfaceResult;
+/**
+ * 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 declare function registerServer(opts: RegisterServerOptions): RegisterServerResult;
+/**
+ * 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 declare function manifestTarget(manifest: McpManifest): string;
+/**
+ * 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 declare function registerMcpServers(pkg: string, names: string[], options?: {
+    /** Load a server's shape-validated manifest by bare name (pack-install supplies this). */
+    loadManifest?: (name: string) => McpManifest;
+    /** Resolve `${secret:NAME}` at emit (defaults to the no-secret resolver). */
+    resolveSecret?: SecretResolver;
+    /** Injectable env (tests pass a tmpdir home). */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning + backup stamp passthrough (tests). */
+    lock?: AcquireLockOptions;
+    stamp?: string;
+}): RegisterServerResult[];
+/** smol-toml's value-table type (its `parse` return + `stringify` input). */
+type TomlTable = Record<string, unknown>;
+/**
+ * The Codex doc threaded through the safe-write core. We carry BOTH the parsed
+ * value (`value`, for the merge fn + verify) AND the ORIGINAL file text
+ * (`originalText`, `null` for a fresh/empty file). {@link codexConfigFormat.serialize}
+ * uses `originalText` to APPEND the one new table without re-serializing — and so
+ * without dropping — the user's existing comments and tables. This is the seam that
+ * makes "preserves comments" honest within a value-only TOML library.
+ */
+export interface CodexTomlDoc {
+    /** The parsed TOML table (the whole `~/.codex/config.toml` as a value). */
+    value: TomlTable;
+    /** The original file text, or `null` when the file was absent/empty. */
+    originalText: string | null;
+}
+/** The Codex `[mcp_servers]` super-table key (the global Codex MCP registry). */
+export declare 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 declare function serializeOneCodexServer(name: string, def: TomlTable): string;
+/**
+ * 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 declare const codexConfigFormat: ConfigFormat<CodexTomlDoc>;
+/**
+ * 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 declare function appendCodexTable(originalText: string, name: string, def: TomlTable): string;
+/**
+ * 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 declare function buildCodexServerDef(manifest: McpManifest, pack: string, resolve: SecretResolver, secretSink: Set<string>): TomlTable;
+/**
+ * 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 declare function buildCodexToolsTable(tools: McpManifest['tools']): TomlTable | 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 declare function mergeCodexServer(name: string, def: TomlTable): (doc: CodexTomlDoc) => CodexTomlDoc;
+/**
+ * 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 declare function registerCodexServer(opts: RegisterServerOptions): RegisterSurfaceResult | RegisterSurfaceSkip;
+/** Discriminates an un-registration outcome on one surface. */
+export type UnregisterOutcome = 
+/** The provenance-stamped entry was found and removed (file changed). */
+'removed'
+/** The entry was already absent / never installed — a clean idempotent no-op. */
+ | 'absent'
+/** The entry exists but its provenance does NOT match this pack (foreign / user-created) — left in place. */
+ | 'skipped-foreign';
+/** Outcome of un-registering one server from one surface. */
+export interface UnregisterSurfaceResult {
+    /** What happened: removed / absent(no-op) / skipped(foreign-or-unstamped). */
+    outcome: UnregisterOutcome;
+    /** Whether the surface's file actually changed (true only for `removed`). */
+    changed: boolean;
+    /** The realpath acted on (resolved symlink), when a file was present. */
+    realTarget: string;
+    /** A human-readable note for the `skipped-foreign` case (suitable for a warning). */
+    reason?: string;
+}
+/** A surface deliberately not acted on (e.g. Codex-absent host, or the file never existed). */
+export interface UnregisterSurfaceSkip {
+    /** Discriminant: this surface was skipped, not inspected. */
+    skipped: true;
+    /** Human-readable reason (e.g. "Codex runtime absent"). */
+    reason: string;
+}
+/** Outcome of {@link unregisterServer} — one entry per runtime surface. */
+export interface UnregisterServerResult {
+    /** The Claude/JSON surface result (always inspected — Claude is always present). */
+    claude: UnregisterSurfaceResult;
+    /**
+     * The Codex/TOML surface result, or a first-class SKIP when the Codex runtime is
+     * absent (`~/.codex` missing — never fabricated).
+     */
+    codex: UnregisterSurfaceResult | UnregisterSurfaceSkip;
+}
+/**
+ * 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 declare function removeClaudeServer(name: string, pack: string): (doc: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * 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 declare const claudeRemovalFormat: ConfigFormat<Record<string, unknown>>;
+/** Options for {@link unregisterServer} / {@link unregisterClaudeServer} / {@link unregisterCodexServer}. */
+export interface UnregisterServerOptions {
+    /** The bare server name to remove (the `mcpServers` / `mcp_servers` key). */
+    name: string;
+    /** The pack being uninstalled — ONLY entries stamped with this `_hqPack` are removed. */
+    pack: string;
+    /** Injectable env (tests pass a tmpdir home so the real configs are untouched). */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning (tests use tiny timeouts). */
+    lock?: AcquireLockOptions;
+    /** Backup timestamp override (deterministic tests). */
+    stamp?: string;
+    /**
+     * Append an audit-log line per surface (default true). The AC requires every
+     * unregister to log; this exists ONLY to suppress logging in narrow unit tests
+     * that call {@link unregisterClaudeServer}/{@link unregisterCodexServer} directly.
+     */
+    audit?: boolean;
+}
+/**
+ * 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 declare function unregisterClaudeServer(opts: UnregisterServerOptions): UnregisterSurfaceResult;
+/**
+ * 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 declare function removeCodexServer(name: string, pack: string): (doc: CodexTomlDoc) => CodexTomlDoc;
+/**
+ * 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 declare const codexRemovalFormat: ConfigFormat<CodexTomlDoc>;
+/**
+ * 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 declare function unregisterCodexServer(opts: UnregisterServerOptions): UnregisterSurfaceResult | UnregisterSurfaceSkip;
+/**
+ * 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 declare function unregisterServer(opts: UnregisterServerOptions): UnregisterServerResult;
+/**
+ * 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 declare function unregisterMcpServers(pkg: string, names: string[], options?: {
+    /** Injectable env (tests pass a tmpdir home). */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning + backup stamp passthrough (tests). */
+    lock?: AcquireLockOptions;
+    stamp?: string;
+}): UnregisterServerResult[];
+export {};
+//# sourceMappingURL=mcp-registration.d.ts.map