@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/login.js

@@ -4,6 +4,11 @@
 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];
@@ -24,21 +29,59 @@ 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.`));
-                return;
+                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;
             }
-            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.exit(1);
+            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');
         }
     });
 }

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

@@ -74,6 +74,15 @@ 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;
@@ -82,6 +91,8 @@ export declare class ConfigPermissionError extends McpRegistrationError {
  */
 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,
@@ -135,7 +146,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. */
-export type AuditAction = 'register' | 'unregister';
+type AuditAction = 'register' | 'unregister';
 /**
  * The result recorded on an audit line:
  *   - `registered`   — a register write that changed the file.
@@ -145,7 +156,7 @@ export type AuditAction = 'register' | 'unregister';
  *                      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';
+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 }`.
@@ -202,8 +213,6 @@ 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. */
@@ -273,10 +282,6 @@ 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`). */
@@ -494,7 +499,8 @@ 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 -> {@link McpNameCollisionError} ABORT.
+ *   - name PRESENT, def-DIFFERS, same non-empty `_hqPack` -> replace the entry.
+ *   - name PRESENT, def-DIFFERS, unmarked or different owner -> collision ABORT.
  *
  * Never touches any OTHER server entry or any other top-level key.
  */
@@ -646,8 +652,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 the one new table without re-serializing — and so
- * without dropping — the user's existing comments and tables. This is the seam that
+ * 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
  * makes "preserves comments" honest within a value-only TOML library.
  */
 export interface CodexTomlDoc {
@@ -661,7 +667,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 both for the append path (preserve-comments) and for the
+ * smol-toml. Used for appending new servers, replacing an owned table, and the
  * collision/equality comparison. The output is deterministic for a given def so a
  * re-install produces byte-identical text (idempotency depends on it).
  */
@@ -670,15 +676,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 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
+ * 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
  * `serialize` reproduces the original text exactly (no write happens).
  */
 export declare const codexConfigFormat: ConfigFormat<CodexTomlDoc>;
@@ -716,9 +722,10 @@ 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 → {@link McpNameCollisionError} ABORT (never mutate
- *     an existing table — which is also what keeps the comment-preserving append
- *     sound: we only ever ADD).
+ *   - 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.
  *
  * Never touches any OTHER server table or any other top-level table.
  */
@@ -739,7 +746,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. */
-export type UnregisterOutcome = 
+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. */

package/dist/commands/mcp-registration.js

@@ -99,6 +99,11 @@ export class ConfigPermissionError extends McpRegistrationError {
  */
 export class McpNameCollisionError extends McpRegistrationError {
     code = 'McpNameCollisionError';
+    codexDiagnostics;
+    constructor(message, codexDiagnostics) {
+        super(message);
+        this.codexDiagnostics = codexDiagnostics;
+    }
 }
 /**
  * The Codex runtime is absent (`~/.codex` missing). This is a FIRST-CLASS SKIP,
@@ -237,10 +242,6 @@ export function isCodexInstalled(env) {
 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
@@ -363,9 +364,9 @@ export function sanitizeParserMessage(message) {
 // 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;
+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;
+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);
@@ -1009,7 +1010,8 @@ function canonicalJson(v) {
  *     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.
+ *   - name PRESENT, def-DIFFERS, same non-empty `_hqPack` -> replace the entry.
+ *   - name PRESENT, def-DIFFERS, unmarked or different owner -> collision ABORT.
  *
  * Never touches any OTHER server entry or any other top-level key.
  */
@@ -1023,6 +1025,12 @@ export function mergeClaudeServer(name, def) {
                 // (do not re-stamp) so a re-install is a true byte-for-byte no-op.
                 return doc;
             }
+            const existingPack = provenanceOf(existing);
+            const incomingPack = provenanceOf(def);
+            if (existingPack && existingPack === incomingPack) {
+                servers[name] = def;
+                return { ...doc, mcpServers: servers };
+            }
             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.');
@@ -1302,7 +1310,7 @@ 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
+ * smol-toml. Used for appending new servers, replacing an owned table, and the
  * collision/equality comparison. The output is deterministic for a given def so a
  * re-install produces byte-identical text (idempotency depends on it).
  */
@@ -1313,15 +1321,15 @@ export function serializeOneCodexServer(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.
+ * 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 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
+ * 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
  * `serialize` reproduces the original text exactly (no write happens).
  */
 export const codexConfigFormat = {
@@ -1332,7 +1340,16 @@ export const codexConfigFormat = {
         return { value, originalText: text };
     },
     serialize(doc) {
-        const pending = doc[PENDING_APPEND];
+        const pendingDoc = doc;
+        const pendingUpdate = pendingDoc[PENDING_UPDATE];
+        if (doc.originalText !== null && pendingUpdate) {
+            const updated = replaceCodexTable(doc.originalText, pendingUpdate.name, pendingUpdate.def);
+            if (updated === null) {
+                throw new McpNameCollisionError(codexCollisionMessage(pendingUpdate.name), pendingUpdate.diagnostics);
+            }
+            return updated;
+        }
+        const pending = pendingDoc[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.
@@ -1362,6 +1379,7 @@ export const codexConfigFormat = {
 };
 /** Symbol carrying the pending append on a {@link CodexTomlDoc} (merge → serialize). */
 const PENDING_APPEND = Symbol('hqPendingCodexAppend');
+const PENDING_UPDATE = Symbol('hqPendingCodexUpdate');
 /** 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] ?? {}) };
@@ -1384,6 +1402,171 @@ export function appendCodexTable(originalText, name, def) {
     const body = block.endsWith('\n') ? block : `${block}\n`;
     return `${trimmed}\n\n${body}`;
 }
+/** Return the decoded table path for a valid TOML table header, or null. */
+function codexTablePath(headerLine) {
+    try {
+        const value = parseToml(headerLine);
+        const matches = [];
+        const visit = (current, pathParts) => {
+            if (current === null || typeof current !== 'object')
+                return;
+            if (Array.isArray(current)) {
+                current.forEach((item, index) => visit(item, [...pathParts, String(index)]));
+                return;
+            }
+            const table = current;
+            const entries = Object.entries(table);
+            if (entries.length === 0) {
+                matches.push(pathParts);
+                return;
+            }
+            for (const [key, child] of entries) {
+                visit(child, [...pathParts, key]);
+            }
+        };
+        visit(value, []);
+        return matches.length === 1 ? matches[0] : null;
+    }
+    catch {
+        // The caller has already parsed the whole document. Ordinary values are
+        // not table headers.
+        return null;
+    }
+}
+/**
+ * Locate real table headers without mistaking bracket-like text in TOML values
+ * for a header. Parsing the preceding prefix ensures a candidate is not inside
+ * an unfinished multiline string or array; smol-toml decodes quoted key paths.
+ */
+function codexTomlSections(text) {
+    const headers = [];
+    let offset = 0;
+    for (const line of text.match(/[^\n]*(?:\n|$)/g) ?? []) {
+        if (line.length === 0)
+            continue;
+        const content = line.replace(/\r?\n$/, '');
+        if (content.trimStart().startsWith('[')) {
+            try {
+                parseToml(text.slice(0, offset));
+                const path = codexTablePath(content);
+                if (path)
+                    headers.push({ start: offset, path });
+            }
+            catch {
+                // The prefix is incomplete TOML, so this bracket is part of a value.
+            }
+        }
+        offset += line.length;
+    }
+    return headers.map((header, index) => {
+        const nextStart = headers[index + 1]?.start ?? text.length;
+        let end = nextStart;
+        const trailingLines = text.slice(header.start, nextStart).match(/[^\n]*(?:\n|$)/g) ?? [];
+        for (let lineIndex = trailingLines.length - 1; lineIndex >= 0; lineIndex -= 1) {
+            const content = trailingLines[lineIndex].replace(/\r?\n$/, '');
+            if (content.trim() === '' || content.trimStart().startsWith('#')) {
+                end -= trailingLines[lineIndex].length;
+            }
+            else {
+                break;
+            }
+        }
+        return { ...header, end };
+    });
+}
+/** Extract comment text outside TOML strings so updating an owned table drops no user notes. */
+function codexTomlComments(text) {
+    const comments = [];
+    let multiline = null;
+    let lineOffset = 0;
+    for (const lineWithEnding of text.match(/[^\n]*(?:\n|$)/g) ?? []) {
+        if (lineWithEnding.length === 0)
+            continue;
+        const line = lineWithEnding.replace(/\r?\n$/, '');
+        let quote = null;
+        let index = 0;
+        while (index < line.length) {
+            if (multiline) {
+                const delimiter = multiline === 'basic' ? '"""' : "'''";
+                if (multiline === 'basic' && line[index] === '\\') {
+                    index += 2;
+                }
+                else if (line.startsWith(delimiter, index)) {
+                    multiline = null;
+                    index += 3;
+                }
+                else {
+                    index += 1;
+                }
+                continue;
+            }
+            if (quote) {
+                const closing = quote === 'basic' ? '"' : "'";
+                if (quote === 'basic' && line[index] === '\\') {
+                    index += 2;
+                }
+                else if (line[index] === closing) {
+                    quote = null;
+                    index += 1;
+                }
+                else {
+                    index += 1;
+                }
+                continue;
+            }
+            if (line[index] === '#') {
+                comments.push({ offset: lineOffset + index, text: line.slice(index) });
+                break;
+            }
+            if (line.startsWith('"""', index)) {
+                multiline = 'basic';
+                index += 3;
+            }
+            else if (line.startsWith("'''", index)) {
+                multiline = 'literal';
+                index += 3;
+            }
+            else if (line[index] === '"') {
+                quote = 'basic';
+                index += 1;
+            }
+            else if (line[index] === "'") {
+                quote = 'literal';
+                index += 1;
+            }
+            else {
+                index += 1;
+            }
+        }
+        lineOffset += lineWithEnding.length;
+    }
+    return comments;
+}
+/** Replace all sections for one same-pack server while retaining unrelated bytes and comments. */
+function replaceCodexTable(originalText, name, def) {
+    const sections = codexTomlSections(originalText);
+    const target = sections.filter((section) => section.path[0] === CODEX_MCP_SERVERS_KEY && section.path[1] === name);
+    if (!target.some((section) => section.path.length === 2))
+        return null;
+    const newline = originalText.includes('\r\n') ? '\r\n' : '\n';
+    const comments = codexTomlComments(originalText)
+        .filter((comment) => target.some((section) => comment.offset >= section.start && comment.offset < section.end))
+        .map((comment) => comment.text);
+    let output = '';
+    let cursor = 0;
+    let inserted = false;
+    for (const section of target) {
+        output += originalText.slice(cursor, section.start);
+        if (!inserted) {
+            output += serializeOneCodexServer(name, def).replace(/\n/g, newline);
+            if (comments.length > 0)
+                output += comments.join(newline) + newline;
+            inserted = true;
+        }
+        cursor = section.end;
+    }
+    return inserted ? output + originalText.slice(cursor) : null;
+}
 /**
  * Build the Codex server table emitted as `[mcp_servers.<name>]`: pass the
  * transport fields through, resolve `${secret:}` in every argument/header/env value
@@ -1447,9 +1630,10 @@ export function buildCodexToolsTable(tools) {
  *   - 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).
+ *   - 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.
  *
  * Never touches any OTHER server table or any other top-level table.
  */
@@ -1463,9 +1647,23 @@ export function mergeCodexServer(name, def) {
                 // 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.');
+            const diagnostics = codexCollisionDiagnostics(name, existing, def);
+            const existingPack = isTomlTable(existing)
+                ? existing[HQ_PACK_PROVENANCE_KEY]
+                : undefined;
+            if (doc.originalText !== null &&
+                isTomlTable(existing) &&
+                typeof existingPack === 'string' &&
+                existingPack.length > 0 &&
+                existingPack === def[HQ_PACK_PROVENANCE_KEY]) {
+                const next = {
+                    value: withServer(doc.value, name, def),
+                    originalText: doc.originalText,
+                    [PENDING_UPDATE]: { name, def, diagnostics },
+                };
+                return next;
+            }
+            throw new McpNameCollisionError(codexCollisionMessage(name), diagnostics);
         }
         // Insert into the value (for verify-after-write) AND record the pending append
         // (for comment-preserving serialize).
@@ -1478,6 +1676,41 @@ export function mergeCodexServer(name, def) {
         return next;
     };
 }
+function isTomlTable(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function codexCollisionMessage(name) {
+    return `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.';
+}
+function codexCollisionDiagnostics(name, existing, incoming) {
+    const existingTable = isTomlTable(existing) ? existing : {};
+    const owner = typeof existingTable[HQ_PACK_PROVENANCE_KEY] === 'string' &&
+        existingTable[HQ_PACK_PROVENANCE_KEY].length > 0
+        ? 'hq'
+        : 'unknown';
+    const keys = new Set([...Object.keys(existingTable), ...Object.keys(incoming)]);
+    keys.delete(HQ_PACK_PROVENANCE_KEY);
+    const fields = new Set();
+    for (const key of keys) {
+        const existingHasKey = Object.prototype.hasOwnProperty.call(existingTable, key);
+        const incomingHasKey = Object.prototype.hasOwnProperty.call(incoming, key);
+        if (existingHasKey === incomingHasKey &&
+            canonicalJson(existingTable[key]) === canonicalJson(incoming[key])) {
+            continue;
+        }
+        fields.add(key === 'command' || key === 'args' || key === 'env' || key === 'url'
+            ? key
+            : 'other');
+    }
+    return {
+        client: 'codex',
+        serverName: name,
+        existingEntryOwner: owner,
+        diffFields: [...fields].sort(),
+    };
+}
 /**
  * Emit ONE server into the GLOBAL Codex surface (`~/.codex/config.toml`
  * `[mcp_servers.<name>]`) via {@link writeConfigAtomic}. A FIRST-CLASS SKIP when the

package/dist/commands/mcp-status.js

@@ -374,6 +374,7 @@ export function registerMcpCommand(program) {
         .description('MCP pack observability (read-only) across Claude + Codex');
     mcp
         .command('status')
+        .alias('list')
         .description('Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)')
         .option('--json', 'Emit the structured report as JSON (for CI / scripting)')
         .action((opts) => {