@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/commands/integrations-manage.js

@@ -16,7 +16,6 @@ import readline from "node:readline";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
-import { redactSensitiveUrl, redactUrlsInText } from "../utils/redact-url.js";
 import { IntegrationsCliError, bareProvider, printHealthNotice, fetchConnections, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, selectConnection, } from "./integrations-core.js";
 import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, purgeConnection, setReadSafe, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
 const WRITE_POLICIES = ["auto-allow", "confirm", "deny"];
@@ -96,7 +95,7 @@ function confirm(message) {
     });
 }
 function connectionLabel(connection) {
-    return redactUrlsInText(connection.installation?.displayName ?? bareProvider(connection.provider));
+    return connection.installation?.displayName ?? bareProvider(connection.provider);
 }
 /**
  * The category of match must mirror `selectConnection`: an exact provider id
@@ -220,13 +219,12 @@ export function registerManageCommands(integrations) {
         if (connection.status === "revoked") {
             const details = revokedConnectionDetails(connection, opts.company);
             console.log(chalk.yellow(`  Revoked — ${details.reason}`));
-            console.log(chalk.yellow(`  Re-add: ${redactUrlsInText(details.fixPath)}`));
+            console.log(chalk.yellow(`  Re-add: ${details.fixPath}`));
         }
         if (install?.domain)
-            console.log(chalk.dim(`  domain:      ${redactUrlsInText(install.domain)}`));
-        if (install?.surface?.url) {
-            console.log(chalk.dim(`  endpoint:    ${redactSensitiveUrl(install.surface.url)}`));
-        }
+            console.log(chalk.dim(`  domain:      ${install.domain}`));
+        if (install?.surface?.url)
+            console.log(chalk.dim(`  endpoint:    ${install.surface.url}`));
         const policy = connection.writePolicy;
         if (policy) {
             console.log(chalk.dim(`  changes:     ${policy} — ${POLICY_BLURB[policy] ?? ""}`));
@@ -549,7 +547,7 @@ export function registerManageCommands(integrations) {
             const who = row.memberOrAgentName ?? row.memberOrAgent;
             console.log(`${chalk.dim(row.timestamp)}  ${chalk.bold(row.outcome)}  ${row.toolName}  ${chalk.dim(who)}`);
             if (row.reason)
-                console.log(chalk.dim(`    ${redactUrlsInText(row.reason)}`));
+                console.log(chalk.dim(`    ${row.reason}`));
         }
         // hq-pro caps its own feed at 50 events; say so rather than letting a
         // truncated list read as "that is everything that ever happened".
@@ -562,7 +560,6 @@ export function registerManageCommands(integrations) {
         .description("Calls that were queued for an owner's approval")
         .option("--company <slug>", "Company slug, e.g. indigo")
         .option("--json", "Machine-readable output")
-        .option("--history", "Include recently decided calls")
         .action(async (opts) => {
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
@@ -571,9 +568,7 @@ export function registerManageCommands(integrations) {
         // could only show that a call was once queued.
         let pending;
         try {
-            pending = await fetchPendingApprovals(token, companyUid, {
-                includeHistory: opts.history,
-            });
+            pending = await fetchPendingApprovals(token, companyUid);
         }
         catch (err) {
             // This CLI can ship ahead of the hq-pro deploy that adds the pending
@@ -589,19 +584,14 @@ export function registerManageCommands(integrations) {
             return;
         }
         if (pending.length === 0) {
-            console.log(opts.history ? "No recent approval history." : "Nothing is waiting for approval.");
+            console.log("Nothing is waiting for approval.");
             return;
         }
         for (const row of pending) {
             const who = row.requestedByName ?? row.requestedBy;
             const label = row.requestedTool ?? row.toolName;
             console.log(`${chalk.bold(label)}  ${chalk.dim(`${who} · ${row.createdAt}`)}`);
-            if (opts.history) {
-                console.log(chalk.dim(`  ${row.queueId} · ${row.status ?? row.outcome ?? "status unavailable"}`));
-            }
-            else {
-                console.log(chalk.dim(`  hq integrations approve ${row.queueId}${row.provider ? ` --provider ${bareProvider(row.provider)}` : ""}`));
-            }
+            console.log(chalk.dim(`  hq integrations approve ${row.queueId}${row.provider ? ` --provider ${bareProvider(row.provider)}` : ""}`));
         }
     });
     integrations
@@ -618,6 +608,9 @@ export function registerManageCommands(integrations) {
         const companyUid = await getCompanyUid(token, opts.company);
         const connection = await resolveConnection(token, companyUid, app, opts);
         const installationId = connection.installation?.id;
+        if (!installationId) {
+            throw new IntegrationsCliError(`${connectionLabel(connection)} was not installed through the app catalog, so it cannot be disconnected from here.`, { expected: true });
+        }
         if (!opts.yes) {
             const label = connectionLabel(connection);
             // Warning + prompt go to stderr: with --json, stdout must stay parseable,
@@ -630,7 +623,7 @@ export function registerManageCommands(integrations) {
                 throw new IntegrationsCliError("Not disconnected. Re-run with --yes if you are sure.", { expected: true });
             }
         }
-        const result = await uninstallIntegration(token, companyUid, installationId ? { installationId } : { connectionId: connection.id });
+        const result = await uninstallIntegration(token, companyUid, installationId);
         if (opts.json) {
             printJson(result);
             return;

package/dist/commands/integrations.d.ts

@@ -22,7 +22,6 @@
  *   hq integrations tools --provider <p>     What the connected app can do.
  *   hq integrations call <tool> --provider <p> --args '<json>'
  *   hq integrations pending                  Calls awaiting approval.
- *   hq integrations pending --history        Recently decided calls, including status.
  *   hq integrations approve|reject <queueId> Decide a queued call.
  *
  * Govern and remove:
@@ -50,14 +49,7 @@
  * `integrations-manage.ts`.
  */
 import { Command } from "commander";
-import { type PendingApproval } from "./integrations-api.js";
 export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
 export type { AdminConnection } from "./integrations-core.js";
-/** Wait for a decided queue item without resending the approve request. */
-export declare function waitForApprovalTerminal(token: string, companyUid: string, queueId: string, options?: {
-    timeoutMs?: number;
-    now?: () => number;
-    sleep?: (milliseconds: number) => Promise<void>;
-}): Promise<PendingApproval | null>;
 export declare function registerIntegrationsCommand(program: Command): void;
 //# sourceMappingURL=integrations.d.ts.map

package/dist/commands/integrations.js

@@ -22,7 +22,6 @@
  *   hq integrations tools --provider <p>     What the connected app can do.
  *   hq integrations call <tool> --provider <p> --args '<json>'
  *   hq integrations pending                  Calls awaiting approval.
- *   hq integrations pending --history        Recently decided calls, including status.
  *   hq integrations approve|reject <queueId> Decide a queued call.
  *
  * Govern and remove:
@@ -53,12 +52,10 @@ import { randomUUID } from "node:crypto";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { redactSensitiveUrl, redactSensitiveUrls, redactUrlsInText } from "../utils/redact-url.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printHealthNotice, printJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
 import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
-import { fetchPendingApprovals } from "./integrations-api.js";
 export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
 /**
  * Gateway metadata is additive and may be absent when talking to an older
@@ -133,7 +130,7 @@ function connectionLabel(connection) {
     const slug = bareProvider(connection.provider);
     const displayName = connection.installation?.displayName?.trim();
     return displayName && displayName.toLowerCase() !== slug.toLowerCase()
-        ? `${slug} (${redactUrlsInText(displayName)})`
+        ? `${slug} (${displayName})`
         : slug;
 }
 function printToolSchema(tool) {
@@ -141,7 +138,7 @@ function printToolSchema(tool) {
         console.log(chalk.dim("  Input schema was not reported by this app."));
         return;
     }
-    const schema = JSON.stringify(redactSensitiveUrls(tool.inputSchema), null, 2);
+    const schema = JSON.stringify(tool.inputSchema, null, 2);
     console.log(chalk.dim("  Input schema:"));
     console.log(chalk.dim(schema.split("\n").map((line) => `  ${line}`).join("\n")));
 }
@@ -155,62 +152,13 @@ function reportRevokedConnection(connection, opts) {
     else {
         console.log(chalk.yellow(`${connectionLabel(connection)}: status=revoked`));
         console.log(chalk.yellow(`  ${details.reason}`));
-        console.log(`  Re-add: ${redactUrlsInText(details.fixPath)}`);
+        console.log(`  Re-add: ${details.fixPath}`);
     }
     if (opts.fail) {
         throw new IntegrationsCliError(`status=revoked. ${details.reason} Re-add with: ${details.fixPath}`, { expected: true });
     }
     return true;
 }
-const APPROVAL_POLL_TIMEOUT_MS = 5 * 60_000;
-const APPROVAL_POLL_INITIAL_DELAY_MS = 1_000;
-const APPROVAL_POLL_MAX_DELAY_MS = 15_000;
-const APPROVAL_TERMINAL_STATUSES = new Set([
-    "completed",
-    "resumed",
-    "failed",
-    "write_unknown",
-    "rejected",
-    "expired",
-]);
-const APPROVAL_TERMINAL_OUTCOMES = new Set([
-    "ran",
-    "failed",
-    "unknown",
-    "turned_down",
-    "timed_out",
-]);
-function isTerminalApproval(row) {
-    return APPROVAL_TERMINAL_STATUSES.has(row.status ?? "") ||
-        APPROVAL_TERMINAL_OUTCOMES.has(row.outcome ?? "");
-}
-/** Wait for a decided queue item without resending the approve request. */
-export async function waitForApprovalTerminal(token, companyUid, queueId, options = {}) {
-    const timeoutMs = options.timeoutMs ?? APPROVAL_POLL_TIMEOUT_MS;
-    const now = options.now ?? Date.now;
-    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
-    const deadline = now() + timeoutMs;
-    let delayMs = APPROVAL_POLL_INITIAL_DELAY_MS;
-    while (now() < deadline) {
-        const rows = await fetchPendingApprovals(token, companyUid, { includeHistory: true });
-        const row = rows.find((candidate) => candidate.queueId === queueId);
-        if (row && isTerminalApproval(row))
-            return row;
-        const remainingMs = deadline - now();
-        if (remainingMs <= 0)
-            break;
-        await sleep(Math.min(delayMs, remainingMs));
-        delayMs = Math.min(delayMs * 2, APPROVAL_POLL_MAX_DELAY_MS);
-    }
-    return null;
-}
-function isPendingApprovalResponse(status) {
-    return ["pending", "approved", "approved_pending_run", "in_progress"].includes(status ?? "");
-}
-function approvalOutcomeFailed(row) {
-    return ["failed", "write_unknown"].includes(row.status ?? "") ||
-        ["failed", "unknown"].includes(row.outcome ?? "");
-}
 export function registerIntegrationsCommand(program) {
     const integrations = program
         .command("integrations")
@@ -242,9 +190,6 @@ export function registerIntegrationsCommand(program) {
                 .join(" · ");
             console.log(`${chalk.bold(connectionLabel(c))}  ${chalk.dim(flags)}`);
             console.log(chalk.dim(`  connection: ${c.id}`));
-            const endpoint = c.installation?.surface?.url;
-            if (endpoint)
-                console.log(chalk.dim(`  endpoint: ${redactSensitiveUrl(endpoint)}`));
             printHealthNotice(c);
         }
     });
@@ -291,7 +236,7 @@ export function registerIntegrationsCommand(program) {
             const badge = formatToolBadge(tool);
             console.log(`${chalk.bold(tool.name)}${badge ? `  ${badge}` : ""}  ${chalk.dim(`on ${connectionLabel(connection)}`)}`);
             if (tool.description)
-                console.log(chalk.dim(`  ${redactUrlsInText(tool.description)}`));
+                console.log(chalk.dim(`  ${tool.description}`));
             printToolSchema(tool);
             return;
         }
@@ -301,7 +246,7 @@ export function registerIntegrationsCommand(program) {
         }
         console.log(chalk.dim(`App: ${connectionLabel(connection)}`));
         for (const tool of tools) {
-            const label = tool.title && tool.title !== tool.name ? `  ${chalk.dim(redactUrlsInText(tool.title))}` : "";
+            const label = tool.title && tool.title !== tool.name ? `  ${chalk.dim(tool.title)}` : "";
             const required = requiredInputHint(tool.inputSchema);
             const badge = formatToolBadge(tool);
             console.log(`${chalk.bold(tool.name)}${badge ? `  ${badge}` : ""}${label}${required ? `  ${chalk.dim(required)}` : ""}`);
@@ -367,7 +312,7 @@ export function registerIntegrationsCommand(program) {
         // parsing output. The gateway double-wraps the provider result as a
         // text-content string, so `isError` lands on the UNWRAPPED payload, not
         // on the raw envelope; check both levels so either shape is caught.
-        printIntegrationCallResultJson(payload);
+        printJson(payload);
         if (gatewayResultIsError(payload) || gatewayResultIsError(message.result)) {
             process.exitCode = 1;
         }
@@ -398,38 +343,6 @@ export function registerIntegrationsCommand(program) {
                 raiseIfUpstreamUnavailable(res);
                 throw new IntegrationsCliError(body.error ?? `${decision} failed (HTTP ${res.status})`, { expected: isClientError(res.status) });
             }
-            const pendingApprove = decision === "approve" &&
-                (res.status === 202 || isPendingApprovalResponse(body.status));
-            if (pendingApprove) {
-                const terminal = await waitForApprovalTerminal(token, companyUid, queueId);
-                const historyCommand = `hq integrations pending --history${opts.company ? ` --company ${opts.company}` : ""}`;
-                if (!terminal) {
-                    if (opts.json) {
-                        printJson({ ...body, status: "pending", pollTimedOut: true, checkCommand: historyCommand });
-                    }
-                    else {
-                        console.log(chalk.yellow(`Approval is still running after 5 minutes. Check queue ${queueId} later with: ${historyCommand}`));
-                    }
-                    return;
-                }
-                if (opts.json)
-                    printJson(terminal);
-                else if (approvalOutcomeFailed(terminal)) {
-                    const unknown = terminal.status === "write_unknown" || terminal.outcome === "unknown";
-                    console.log(chalk.red(unknown
-                        ? `The provider outcome is unknown for ${queueId}. Check the provider before taking any action; ${historyCommand} shows the latest queue state.`
-                        : `The approved call failed (${terminal.status ?? terminal.outcome}). See ${historyCommand} for its status.`));
-                }
-                else if (terminal.status === "resumed" || terminal.status === "completed" || terminal.outcome === "ran") {
-                    console.log(chalk.green("Approved — the call completed."));
-                }
-                else {
-                    console.log(chalk.yellow(`Approval ended with status ${terminal.status ?? terminal.outcome ?? "unknown"}.`));
-                }
-                if (approvalOutcomeFailed(terminal))
-                    process.exitCode = 1;
-                return;
-            }
             if (opts.json) {
                 printJson(body);
                 return;

package/dist/commands/login.js

@@ -4,11 +4,6 @@
 import chalk from 'chalk';
 import { browserLogin, loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
 import { cognitoConfigForLoginProvider } from '../utils/login-provider.js';
-import * as readline from "node:readline/promises";
-import { listActiveMembershipCompanies } from "../lib/mesh/api.js";
-import { setDefaultCompany } from "../lib/work-context/config.js";
-import { ensureDefaultCompany } from "../lib/work-context/default-company.js";
-import { workContextRoot } from "../lib/work-context/paths.js";
 function peekIdToken(idToken) {
     try {
         const payload = idToken.split('.')[1];
@@ -29,59 +24,21 @@ export function registerLoginCommand(program) {
         .description('Authenticate with HQ via Cognito')
         .option('--provider <provider>', 'OAuth provider to use: google, microsoft, or picker')
         .action(async (options) => {
-        let accessToken;
         try {
             const existing = loadCachedTokens();
             if (existing && !isExpiring(existing, 120)) {
                 const who = peekIdToken(existing.idToken).email ?? 'cached session';
                 console.log(chalk.green(`Already logged in as ${who}. Run \`hq logout\` to switch accounts.`));
-                accessToken = existing.accessToken;
-            }
-            else {
-                console.log('Opening browser for authentication...');
-                const tokens = await browserLogin(cognitoConfigForLoginProvider(options.provider));
-                const who = peekIdToken(tokens.idToken).email ?? 'HQ';
-                console.log(chalk.green(`Logged in as ${who}`));
-                accessToken = tokens.accessToken;
+                return;
             }
+            console.log('Opening browser for authentication...');
+            const tokens = await browserLogin(cognitoConfigForLoginProvider(options.provider));
+            const who = peekIdToken(tokens.idToken).email ?? 'HQ';
+            console.log(chalk.green(`Logged in as ${who}`));
         }
         catch (error) {
             console.error(chalk.red('Login failed:'), error instanceof Error ? error.message : 'Unknown error');
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const root = workContextRoot();
-            const activation = await ensureDefaultCompany({
-                root,
-                listMemberships: () => listActiveMembershipCompanies(accessToken),
-                log: (message) => console.error(chalk.dim(message)),
-            });
-            if (activation.status === "needs_choice" && process.stdin.isTTY && process.stdout.isTTY) {
-                const choices = activation.memberships
-                    .map((membership, index) => `${index + 1}. ${membership.slug}`)
-                    .join("\n");
-                const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-                try {
-                    const answer = await rl.question(`Choose this device's default company:\n${choices}\nSelection: `);
-                    const selected = activation.memberships[Number.parseInt(answer, 10) - 1];
-                    if (selected) {
-                        await setDefaultCompany(selected.slug, {
-                            root,
-                            validateMembership: (candidate) => candidate === selected.slug ? { uid: selected.uid } : false,
-                        });
-                    }
-                }
-                finally {
-                    rl.close();
-                }
-            }
-            else if (activation.status === "needs_choice") {
-                console.error(chalk.yellow("Multiple active memberships. Run `hq mesh context default set <slug>` to choose this device's default company."));
-            }
-        }
-        catch (error) {
-            console.error(chalk.yellow('Default-company setup failed:'), error instanceof Error ? error.message : 'Unknown error');
+            process.exit(1);
         }
     });
 }

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

@@ -74,15 +74,6 @@ export declare class ConfigParseError extends McpRegistrationError {
 export declare class ConfigPermissionError extends McpRegistrationError {
     readonly code: "ConfigPermissionError";
 }
-type CodexMcpCollisionOwner = 'hq' | 'foreign' | 'unknown';
-type CodexMcpCollisionField = 'command' | 'args' | 'env' | 'url' | 'other';
-/** Safe, value-free context for a Codex name collision reported to Sentry. */
-export interface CodexMcpCollisionDiagnostics {
-    client: 'codex';
-    serverName: string;
-    existingEntryOwner: CodexMcpCollisionOwner;
-    diffFields: CodexMcpCollisionField[];
-}
 /**
  * A server name is already present in the target config with a DIFFERENT
  * definition than the one being merged (def-equal = idempotent no-op;
@@ -91,8 +82,6 @@ export interface CodexMcpCollisionDiagnostics {
  */
 export declare class McpNameCollisionError extends McpRegistrationError {
     readonly code: "McpNameCollisionError";
-    readonly codexDiagnostics?: CodexMcpCollisionDiagnostics;
-    constructor(message: string, codexDiagnostics?: CodexMcpCollisionDiagnostics);
 }
 /**
  * The Codex runtime is absent (`~/.codex` missing). This is a FIRST-CLASS SKIP,
@@ -146,7 +135,7 @@ 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. */
-type AuditAction = 'register' | 'unregister';
+export type AuditAction = 'register' | 'unregister';
 /**
  * The result recorded on an audit line:
  *   - `registered`   — a register write that changed the file.
@@ -156,7 +145,7 @@ type AuditAction = 'register' | 'unregister';
  *                      foreign/unstamped entry left in place). PARTIAL is auditable.
  *   - `error`        — the surface emit threw (the operation failed for this surface).
  */
-type AuditResult = 'registered' | 'unregistered' | 'noop' | 'skipped' | 'error';
+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 }`.
@@ -213,6 +202,8 @@ export declare function codexConfigPath(env: SafeWriteEnv): string;
 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. */
@@ -282,6 +273,10 @@ export declare function readConfigDoc<T>(target: string, format: ConfigFormat<T>
  * 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`). */
@@ -499,8 +494,7 @@ export declare function serverDefsEqual(a: unknown, b: unknown): boolean;
  *     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, same non-empty `_hqPack` -> replace the entry.
- *   - name PRESENT, def-DIFFERS, unmarked or different owner -> collision ABORT.
+ *   - name PRESENT, def-DIFFERS -> {@link McpNameCollisionError} ABORT.
  *
  * Never touches any OTHER server entry or any other top-level key.
  */
@@ -652,8 +646,8 @@ 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 a new table or replace sections of a same-pack
- * owned table without re-serializing unrelated content. This is the seam that
+ * 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 {
@@ -667,7 +661,7 @@ 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 for appending new servers, replacing an owned table, and the
+ * 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).
  */
@@ -676,15 +670,15 @@ export declare function serializeOneCodexServer(name: string, def: TomlTable): s
  * 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 a new server
- * table or replaces only a same-pack owned table, rather than re-serializing the
- * whole value. Only a fresh file (`null`) is serialized from scratch.
- * `assertEntry` checks `mcp_servers.<name>` is present.
- *
- * Because `serialize` needs to know WHICH server to append or replace, the merge
- * fn ({@link mergeCodexServer}) records the operation on the doc. For an
- * idempotent no-op (server already present, def-equal) the merge returns the doc
- * UNCHANGED, so
+ * 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>;
@@ -722,10 +716,9 @@ export declare function buildCodexToolsTable(tools: McpManifest['tools']): TomlT
  *   - 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, same `_hqPack` owner → update that owned table
- *     while preserving unrelated TOML bytes and comments.
- *   - name PRESENT, def-DIFFERS, any other owner → {@link McpNameCollisionError}
- *     ABORT with value-free diagnostics.
+ *   - 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.
  */
@@ -746,7 +739,7 @@ export declare function mergeCodexServer(name: string, def: TomlTable): (doc: Co
  */
 export declare function registerCodexServer(opts: RegisterServerOptions): RegisterSurfaceResult | RegisterSurfaceSkip;
 /** Discriminates an un-registration outcome on one surface. */
-type UnregisterOutcome = 
+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. */