@indigoai-us/hq-cli 5.147.0 → 5.148.0

package/CHANGELOG.md

@@ -2,10 +2,15 @@
 
 ## [Unreleased]
 
+## [5.148.0] — 2026-09-23
+
 ## [5.147.0] — 2026-09-23
 
 ### Fixed
 
+- Reinstalling an MCP server now updates its definition when the existing
+  Claude or Codex entry belongs to the same HQ pack. Unmarked and other-pack
+  entries still refuse replacement.
 - `hq mesh context prd-sync` now moves the Board. Its task_status events carry the session's company and project, and take sequence numbers from the session's shared counter (the same file the hooks use), so the server no longer rejects them as duplicates. Rejections print their codes.
 - The mesh daemon no longer treats a missing company slug, a membership timeout, or a lookup error as proof that the device owner is not a member. A device-default session that was cleared to `needs_company` is checked once against the configured default company and, when that membership is active, the company is put back and held events flush. The same cleared session is not counted as a new denial on every later flush.
 - `hq mesh project ensure` no longer fails when the server refuses to close the extra genesis thread; it leaves that thread open and prints one line. Registration and the calling session's binding complete.

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";
 }
+export type CodexMcpCollisionOwner = 'hq' | 'foreign' | 'unknown';
+export 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,
@@ -494,7 +505,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 +658,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 +673,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 +682,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 +728,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.
  */

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,
@@ -1009,7 +1014,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 +1029,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 +1314,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 +1325,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 +1344,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 +1383,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 +1406,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 +1634,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 +1651,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 +1680,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/sentry.js

@@ -7,7 +7,7 @@ import { getCachedSentryUser } from "./utils/sentry-identity.js";
 import { isEpipe } from "./utils/epipe.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { incompleteInstallCaptureContext, incompleteInstallMessage, } from "./utils/incomplete-install-error.js";
-import { sentryFingerprintFor } from "./utils/sentry-fingerprint.js";
+import { sentryFingerprintFor, sentryMcpCollisionContextFor, } from "./utils/sentry-fingerprint.js";
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -70,12 +70,20 @@ export function epipeAwareBeforeSend(event, hint) {
     // before the fleet scrubber — so it covers EVERY capture route (the top-level
     // boundary, the command-level captureException sites, bin/hq-auth-refresh,
     // any uncaughtException), mirroring the EPIPE and environmental-fs drops
-    // above. The classifier reads only a closed allowlist (never message/argv),
-    // and returns null for anything it cannot bound, in which case Sentry's
-    // default grouping is left untouched.
-    const fingerprint = sentryFingerprintFor(hint?.originalException);
-    if (fingerprint)
-        event.fingerprint = fingerprint;
+    // above. The typed error classifiers use closed allowlists. The Codex
+    // collision branch uses one fixed bucket and adds the validated server name
+    // only as a tag; it sends no config values or paths. Unclassifiable
+    // events retain Sentry's default grouping.
+    const mcpCollision = sentryMcpCollisionContextFor(hint?.originalException);
+    if (mcpCollision) {
+        event.tags = { ...event.tags, ...mcpCollision.tags };
+        event.fingerprint = mcpCollision.fingerprint;
+    }
+    else {
+        const fingerprint = sentryFingerprintFor(hint?.originalException);
+        if (fingerprint)
+            event.fingerprint = fingerprint;
+    }
     return beforeSend(event, hint);
 }
 /**

package/dist/utils/sentry-fingerprint.d.ts

@@ -1,3 +1,14 @@
+export interface SentryMcpCollisionContext {
+    tags: {
+        mcp_client: "codex";
+        server_name: string;
+        existing_entry_owner: "hq" | "foreign" | "unknown";
+        diff_fields: string;
+    };
+    fingerprint: string[];
+}
+/** Return bounded, value-free Sentry context for an instrumented Codex name collision. */
+export declare function sentryMcpCollisionContextFor(err: unknown): SentryMcpCollisionContext | null;
 /**
  * Return a bounded `event.fingerprint` array for `err`, or `null` when `err`
  * carries no discriminator from the closed allowlist (in which case the caller

package/dist/utils/sentry-fingerprint.js

@@ -1,8 +1,8 @@
 // src/utils/sentry-fingerprint.ts
 //
-// Compute a BOUNDED Sentry grouping fingerprint from an error, using only a
-// CLOSED allowlist of enumerable discriminators — never any upstream- or
-// user-minted text. Sibling in spirit to qmd-collection-missing-error.ts
+// Compute a BOUNDED Sentry grouping fingerprint from an error, using only
+// closed discriminators and a fixed Codex collision bucket, never arbitrary
+// upstream- or user-minted text. Sibling in spirit to qmd-collection-missing-error.ts
 // (HQ-CLI-S): the same unbounded-fingerprint discipline, applied to grouping
 // instead of to a printed line.
 //
@@ -45,14 +45,14 @@
 // grouping untouched.
 //
 // Two hard rules, mirroring HQ-CLI-S:
-//   1. CLOSED ALLOWLIST. The discriminator is one of a finite set of known
-//      JSON-RPC codes / HTTP statuses, or the literal `rpc:other` / `http:other`
-//      bucket. Total cardinality is therefore bounded — an over-wide key that
-//      minted a brand-new permanent issue per invocation is impossible.
-//   2. NO FREE TEXT. Only the error's `name` (a class identifier), a numeric
-//      `rpcCode`, and a numeric HTTP `status` are read. `message`, argv, URLs,
-//      connection ids, company slugs and any other upstream/user text can NEVER
-//      reach the fingerprint, so the key cannot be inflated by input.
+//   1. BOUNDED DISCRIMINATORS. RPC/HTTP values use closed allowlists and
+//      fallback buckets. Codex collisions use one fixed client bucket. The
+//      server-name tag is restricted to 64 lowercase letters, digits,
+//      underscores or hyphens; other names share one fallback value. Owner and
+//      field tags also use closed sets.
+//   2. NO FREE TEXT. Error messages, argv, URLs, connection ids, company slugs,
+//      config values and paths never reach a fingerprint or tags. The Codex
+//      branch uses a fixed fingerprint and bounded diagnostic tags.
 //
 // An error that carries no bounded discriminator returns `null`: the caller
 // leaves `event.fingerprint` unset and Sentry keeps its DEFAULT grouping, so the
@@ -79,6 +79,48 @@ const KNOWN_HTTP_STATUSES = new Set([
 ]);
 /** Sentry's placeholder for "keep the normal, stack-based grouping too". */
 const DEFAULT_GROUPING = "{{ default }}";
+const CODEX_COLLISION_NAME_RE = /^[a-z0-9_-]{1,64}$/;
+const CODEX_COLLISION_OWNERS = new Set(["hq", "foreign", "unknown"]);
+const CODEX_COLLISION_FIELDS = new Set(["command", "args", "env", "url", "other"]);
+function isCodexCollisionOwner(value) {
+    return typeof value === "string" && CODEX_COLLISION_OWNERS.has(value);
+}
+/** Return bounded, value-free Sentry context for an instrumented Codex name collision. */
+export function sentryMcpCollisionContextFor(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "McpNameCollisionError" || record.code !== "McpNameCollisionError") {
+        return null;
+    }
+    const diagnostics = record.codexDiagnostics;
+    if (diagnostics === null || typeof diagnostics !== "object")
+        return null;
+    const context = diagnostics;
+    const owner = context.existingEntryOwner;
+    if (context.client !== "codex" ||
+        typeof context.serverName !== "string" ||
+        !isCodexCollisionOwner(owner) ||
+        !Array.isArray(context.diffFields) ||
+        context.diffFields.length === 0 ||
+        context.diffFields.length > CODEX_COLLISION_FIELDS.size ||
+        !context.diffFields.every((field) => typeof field === "string" && CODEX_COLLISION_FIELDS.has(field))) {
+        return null;
+    }
+    const fields = [...new Set(context.diffFields)].sort();
+    const serverName = CODEX_COLLISION_NAME_RE.test(context.serverName)
+        ? context.serverName
+        : "other";
+    return {
+        tags: {
+            mcp_client: "codex",
+            server_name: serverName,
+            existing_entry_owner: owner,
+            diff_fields: fields.join(","),
+        },
+        fingerprint: ["mcp-name-collision", "codex"],
+    };
+}
 /**
  * The CLOSED set of error class names allowed to appear VERBATIM in a
  * fingerprint. This hook runs on every capture route and accepts `unknown`, so
@@ -216,6 +258,9 @@ export function sentryFingerprintFor(err) {
     const rawName = typeof record.name === "string" && record.name.length > 0 ? record.name : null;
     if (rawName === null)
         return null;
+    const mcpCollision = sentryMcpCollisionContextFor(record);
+    if (mcpCollision)
+        return mcpCollision.fingerprint;
     // qmd process failures carry a PROCESS EXIT CODE in `status` (never an HTTP
     // status) plus a subcommand in args[0]. Fingerprint them on a dedicated,
     // fully-bounded key BEFORE the HTTP-status branch so an exit code is never read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.147.0",
+  "version": "5.148.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {