@indigoai-us/hq-cli 5.49.0 → 5.50.1

package/src/index.ts

@@ -44,7 +44,9 @@ import { registerSourcesCommand } from "./commands/sources.js";
 import { registerSignalsCommand } from "./commands/signals.js";
 import { registerReindexCommand } from "./commands/reindex.js";
 import { registerRescueCommand } from "./commands/rescue.js";
+import { registerMcpCommand } from "./commands/mcp-status.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
+import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import {
   maybeWarnNewVersion,
   refreshVersionCache,
@@ -198,6 +200,11 @@ registerReindexCommand(program);
 // shipped from @indigoai-us/hq-cloud.
 registerRescueCommand(program);
 
+// MCP pack observability (subcommand group — `hq mcp status`). Read-only
+// provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
+// off the configs, NOT linkStatus), with secret-redacted output + `--json`.
+registerMcpCommand(program);
+
 (async () => {
   try {
     Sentry.addBreadcrumb({
@@ -215,7 +222,17 @@ registerRescueCommand(program);
     }
     await program.parseAsync();
   } catch (err) {
-    Sentry.captureException(err);
+    // A full disk / exhausted quota / read-only filesystem is the user's
+    // machine, not an HQ code defect. Surface a clear, actionable message and
+    // skip Sentry capture so one full disk doesn't flood the tracker with
+    // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+    // to Sentry and still exit 1.
+    const envMsg = environmentalFsErrorMessage(err);
+    if (envMsg) {
+      process.stderr.write(`hq: ${envMsg}\n`);
+    } else {
+      Sentry.captureException(err);
+    }
     process.exitCode = 1;
   } finally {
     // Release health: finalize the per-run session before the flush.

package/src/types.ts

@@ -8,6 +8,8 @@
  *                            knowledge/public/hq-core/package-yaml-spec.md)
  */
 
+import type { ContributionKey } from './utils/contribution-table.js';
+
 export type LegacyStrategy = 'link' | 'merge' | 'copy';
 export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
@@ -73,14 +75,13 @@ export interface SyncResult {
 // covers the entitlement-gated registry flow (`hq packages install <slug>`).
 // ---------------------------------------------------------------------------
 
-export type PackContributeKey =
-  | 'workers'
-  | 'knowledge'
-  | 'skills'
-  | 'commands'
-  | 'hooks'
-  | 'policies'
-  | 'scripts';
+/**
+ * The `contributes.*` keys a pack may declare. DERIVED (US-003) from the single
+ * declarative contribution registry in `utils/contribution-table.ts` -- adding
+ * a contribution type is one row there, and this union updates automatically.
+ * Do NOT restate the keys here.
+ */
+export type PackContributeKey = ContributionKey;
 
 /**
  * Pack authorship attribution (US-001). OPTIONAL and backwards-compatible —

package/src/utils/contribution-table.ts

@@ -0,0 +1,83 @@
+/**
+ * The contribution registry -- the SINGLE declarative source of truth (US-003)
+ * for the `contributes.* -> host` mapping. Every other surface DERIVES from
+ * this table:
+ *
+ *   - `PackContributeKey` (types.ts)              = `keyof typeof CONTRIBUTION_TABLE`
+ *   - `linkFor` / `contributionLinks`             read `payload` + `host`
+ *   - `validateManifest`'s payload check          reads `payload`
+ *   - `core/scripts/scan-packages.sh`             reads a data block GENERATED
+ *                                                 from this table
+ *                                                 (scripts/generate-scan-packages-table.mjs)
+ *
+ * Adding a contribution type is ONE row here, not a five-site edit. The parity
+ * test (`pack-contributions.test.ts`) asserts every surface agrees on the full
+ * key-set, the payload suffix, and the wire mode.
+ *
+ * Row fields:
+ *   - `payload`: path INSIDE the pack, with the literal token `{item}` for the
+ *     declared name. The suffix after `{item}` (e.g. `.md`, `.json`, or none)
+ *     IS the load-bearing per-key shape.
+ *   - `host`: for `wire: 'symlink'`, the host DIRECTORY (relative to the HQ
+ *     root) the symlink is created under -- the symlink dst is
+ *     `<host>/<expanded-item-basename>`. For `wire: 'merge'`, a non-path
+ *     SENTINEL describing the merge target (e.g. `merge:claude+codex`); it is
+ *     NEVER used as a filesystem path.
+ *   - `wire`: `symlink` (a single `ln -s` into `host`) or `merge` (merged into
+ *     a shared host config; see US-004/US-005). Symlink-only readers MUST skip
+ *     `merge` rows.
+ *
+ * NOTE: the `mcp` row is DECLARED here as data only. US-003 does NOT wire any
+ * MCP behavior -- the merge engine lands in US-004/US-005. Declaring it now
+ * makes the table the single source so adding the merge wiring is a code change
+ * against an already-present row, and the parity test guards it from day one.
+ */
+
+export type WireMode = 'symlink' | 'merge';
+
+export interface ContributionRow {
+  /** Path inside the pack, with `{item}` substituted for the declared name. */
+  payload: string;
+  /**
+   * `wire: 'symlink'` -> host directory the symlink lives under (HQ-root
+   * relative). `wire: 'merge'` -> a non-path sentinel for the merge target.
+   */
+  host: string;
+  wire: WireMode;
+}
+
+/**
+ * The 8-key contribution registry. `as const` so `keyof typeof` yields the
+ * exact literal key union consumed by `PackContributeKey`.
+ */
+export const CONTRIBUTION_TABLE = {
+  workers: { payload: 'workers/{item}', host: 'core/workers/public', wire: 'symlink' },
+  knowledge: { payload: 'knowledge/{item}', host: 'core/knowledge/public', wire: 'symlink' },
+  skills: { payload: 'skills/{item}', host: '.claude/skills', wire: 'symlink' },
+  commands: { payload: 'commands/{item}.md', host: '.claude/commands', wire: 'symlink' },
+  hooks: { payload: 'hooks/{item}.sh', host: '.claude/hooks', wire: 'symlink' },
+  policies: { payload: 'policies/{item}.md', host: 'core/policies', wire: 'symlink' },
+  scripts: { payload: 'scripts/{item}', host: 'core/scripts', wire: 'symlink' },
+  // wire:merge -- DECLARED as data (US-003); the merge engine ships in
+  // US-004/US-005. Symlink readers skip this row.
+  mcp: { payload: 'mcp/{item}.json', host: 'merge:claude+codex', wire: 'merge' },
+} as const satisfies Record<string, ContributionRow>;
+
+/** The declared contribution keys, derived once from the table. */
+export type ContributionKey = keyof typeof CONTRIBUTION_TABLE;
+
+/** All contribution keys, in declaration order. */
+export const CONTRIBUTION_KEYS = Object.keys(CONTRIBUTION_TABLE) as ContributionKey[];
+
+/**
+ * Expand a row's `payload` template for a concrete item name. Returns the
+ * pack-relative path of the contribution's payload (e.g. `commands/foo.md`).
+ */
+export function payloadFor(key: ContributionKey, item: string): string {
+  return CONTRIBUTION_TABLE[key].payload.replace('{item}', item);
+}
+
+/** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
+export const SYMLINK_KEYS = CONTRIBUTION_KEYS.filter(
+  (k) => CONTRIBUTION_TABLE[k].wire === 'symlink',
+);

package/src/utils/environmental-error.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { environmentalFsErrorMessage } from "./environmental-error.js";
+
+/** Build a Node-style errno error with a `.code`, as fs.*Sync throws. */
+function errnoError(code: string, message: string): NodeJS.ErrnoException {
+  const err = new Error(message) as NodeJS.ErrnoException;
+  err.code = code;
+  return err;
+}
+
+describe("environmentalFsErrorMessage", () => {
+  // HQ-CLI-2: the exact error that crashed `hq reindex` and flooded Sentry.
+  it("classifies ENOSPC (no space left on device) as environmental", () => {
+    const err = errnoError("ENOSPC", "ENOSPC: no space left on device, open '/x'");
+    const msg = environmentalFsErrorMessage(err);
+    expect(msg).not.toBeNull();
+    expect(msg).toMatch(/no space left on device/i);
+  });
+
+  it("classifies EDQUOT (quota exceeded) as environmental", () => {
+    const msg = environmentalFsErrorMessage(errnoError("EDQUOT", "EDQUOT: disk quota exceeded"));
+    expect(msg).toMatch(/quota/i);
+  });
+
+  it("classifies EROFS (read-only filesystem) as environmental", () => {
+    const msg = environmentalFsErrorMessage(errnoError("EROFS", "EROFS: read-only file system"));
+    expect(msg).toMatch(/read-only/i);
+  });
+
+  // A genuine code bug must still reach Sentry — only the disk-class codes are
+  // diverted, so we never silently swallow real defects.
+  it("returns null for a code-bug error (ENOENT) so it is still captured", () => {
+    expect(environmentalFsErrorMessage(errnoError("ENOENT", "ENOENT: not found"))).toBeNull();
+  });
+
+  it("returns null for a plain Error with no code", () => {
+    expect(environmentalFsErrorMessage(new Error("boom"))).toBeNull();
+  });
+
+  it("returns null for non-error values (null/undefined/string)", () => {
+    expect(environmentalFsErrorMessage(null)).toBeNull();
+    expect(environmentalFsErrorMessage(undefined)).toBeNull();
+    expect(environmentalFsErrorMessage("ENOSPC")).toBeNull();
+  });
+});

package/src/utils/environmental-error.ts

@@ -0,0 +1,39 @@
+// src/utils/environmental-error.ts
+//
+// Classify errors that stem from the user's machine/filesystem state rather
+// than an HQ code defect. These are unactionable from our side: a full disk, an
+// exhausted quota, or a read-only filesystem. The CLI surfaces a clear,
+// actionable message and does NOT report them to Sentry — otherwise a single
+// full disk floods the issue tracker with identical, unfixable crash reports.
+//
+// HQ-CLI-2: `hq reindex` hit ENOSPC in the operation-lock temp-file write
+// (`fs.openSync` → "ENOSPC: no space left on device, open") and the raw error
+// propagated uncaught to the CLI's top-level handler, which captured it to
+// Sentry and exited silently — 5 stack-trace crashes in 6 seconds, with no
+// message telling the user their disk was full.
+
+/**
+ * Node errno codes for "the filesystem cannot accept this write" — purely
+ * environmental, never a code bug. Mapped to the message shown to the user.
+ */
+const ENVIRONMENTAL_FS_CODES: Record<string, string> = {
+  ENOSPC: "No space left on device. Free up disk space and try again.",
+  EDQUOT:
+    "Disk quota exceeded. Free up space (or raise your quota) and try again.",
+  EROFS:
+    "The filesystem is read-only, so HQ can't write here. Check the mount/permissions and try again.",
+};
+
+/**
+ * If `err` is an environmental disk/quota/read-only filesystem error, return a
+ * short, user-facing message explaining it; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — the condition is the user's machine, not a bug HQ can fix. A null
+ * result means "this is a normal error; handle it as usual (capture to Sentry)".
+ */
+export function environmentalFsErrorMessage(err: unknown): string | null {
+  const code = (err as NodeJS.ErrnoException | null | undefined)?.code;
+  if (typeof code !== "string") return null;
+  return ENVIRONMENTAL_FS_CODES[code] ?? null;
+}

package/src/utils/pack-contributions.test.ts

@@ -17,23 +17,39 @@ import {
   linkStatus,
   listInstalledPacks,
   unwirePack,
+  unwirePackMcp,
   packagesDir,
   readHqVersion,
   type WiredLink,
 } from './pack-contributions.js';
+import { parse as parseToml } from 'smol-toml';
+import {
+  registerClaudeServer,
+  registerServer,
+  claudeConfigPath,
+  codexConfigPath,
+  codexHome,
+} from '../commands/mcp-registration.js';
+import {
+  CONTRIBUTION_TABLE,
+  CONTRIBUTION_KEYS,
+  SYMLINK_KEYS,
+  payloadFor,
+  type ContributionKey,
+} from './contribution-table.js';
 import type { PackContributeKey } from '../types.js';
 
-// The canonical mapping, encoded once here as the test oracle. Host paths are
-// relative to hqRoot; src paths relative to the pack dir.
-const EXPECTED: Record<PackContributeKey, { src: string; dst: string }> = {
-  workers: { src: 'workers/X', dst: 'core/workers/public/X' },
-  knowledge: { src: 'knowledge/X', dst: 'core/knowledge/public/X' },
-  skills: { src: 'skills/X', dst: '.claude/skills/X' },
-  commands: { src: 'commands/X.md', dst: '.claude/commands/X.md' },
-  hooks: { src: 'hooks/X.sh', dst: '.claude/hooks/X.sh' },
-  policies: { src: 'policies/X.md', dst: 'core/policies/X.md' },
-  scripts: { src: 'scripts/X', dst: 'core/scripts/X' },
-};
+// The canonical mapping is DERIVED from the single-source CONTRIBUTION_TABLE
+// (US-003) -- the oracle is no longer a hand-restated copy. For each SYMLINK
+// key, src = the payload expanded for item "X"; dst = <host-dir>/<basename>.
+const EXPECTED: Record<ContributionKey, { src: string; dst: string }> =
+  Object.fromEntries(
+    SYMLINK_KEYS.map((k) => {
+      const src = payloadFor(k, 'X');
+      const dst = `${CONTRIBUTION_TABLE[k].host}/${src.split('/').pop()}`;
+      return [k, { src, dst }];
+    }),
+  ) as Record<ContributionKey, { src: string; dst: string }>;
 
 function mkTmp(prefix: string): string {
   // realpathSync so macOS /tmp -> /private/tmp doesn't break path equality.
@@ -41,10 +57,10 @@ function mkTmp(prefix: string): string {
 }
 
 describe('contributionLinks: mapping', () => {
-  it('maps every contributes key to the canonical src/dst', () => {
+  it('maps every SYMLINK contributes key to the canonical src/dst', () => {
     const hqRoot = '/hq';
     const packDir = '/hq/core/packages/hq-pack-x';
-    for (const key of Object.keys(EXPECTED) as PackContributeKey[]) {
+    for (const key of SYMLINK_KEYS) {
       const [link] = contributionLinks(hqRoot, packDir, { [key]: ['X'] });
       expect(link.key).toBe(key);
       expect(link.src).toBe(path.join(packDir, EXPECTED[key].src));
@@ -52,6 +68,19 @@ describe('contributionLinks: mapping', () => {
     }
   });
 
+  it('produces NO symlink for wire:merge keys (mcp)', () => {
+    // The mcp row is wire:merge — declared as data (US-003) but never wired as a
+    // symlink here; its host effect is a config merge (US-004/US-005).
+    const mergeKeys = CONTRIBUTION_KEYS.filter(
+      (k) => CONTRIBUTION_TABLE[k].wire === 'merge',
+    );
+    expect(mergeKeys).toContain('mcp'); // guards the row exists
+    for (const key of mergeKeys) {
+      const links = contributionLinks('/hq', '/p', { [key]: ['X'] });
+      expect(links).toEqual([]);
+    }
+  });
+
   it('ignores empty / non-array contributes subfields', () => {
     const links = contributionLinks('/hq', '/p', {
       skills: [],
@@ -63,21 +92,118 @@ describe('contributionLinks: mapping', () => {
   });
 });
 
-describe('contributionLinks: parity with scan-packages.sh', () => {
-  // Best-effort drift guard: if the bash wirer is reachable, confirm each
-  // case arm's dst suffix matches our TS mapping. Skips cleanly off-tree.
-  const candidates = [
+// ---------------------------------------------------------------------------
+// US-003 single-source parity: FULL key-set + payload-suffix + wire-mode
+// equivalence across every surface (table, derived union, validateManifest's
+// payload reader, and the generated scan-packages.sh block). Replaces the old
+// substring-only `toContain` check, which passed even if a key was MISSING, had
+// the WRONG payload suffix, or the WRONG wire mode.
+// ---------------------------------------------------------------------------
+describe('US-003 parity: contribution table is the single source', () => {
+  // Resolve the HQ root so we can read the GENERATED scan-packages.sh block.
+  const scanCandidates = [
     path.resolve(process.cwd(), '../../../core/scripts/scan-packages.sh'),
     path.resolve(process.cwd(), '../../../../core/scripts/scan-packages.sh'),
   ];
-  const scanPath = candidates.find((p) => fs.existsSync(p));
-
-  (scanPath ? it : it.skip)('dst suffixes match the bash case arms', () => {
-    const bash = fs.readFileSync(scanPath as string, 'utf-8');
-    for (const key of Object.keys(EXPECTED) as PackContributeKey[]) {
-      // dst host-path suffix, with the trailing /$item or /$item.md stripped.
-      const suffix = EXPECTED[key].dst.replace(/\/X(\.\w+)?$/, '');
-      expect(bash).toContain(suffix); // e.g. core/workers/public, .claude/skills
+  const scanPath = scanCandidates.find((p) => fs.existsSync(p));
+
+  // Parse the generated `contrib_row` case arms back into {key:{payload,host,wire}}.
+  function parseBashTable(bash: string): Record<
+    string,
+    { payload: string; host: string; wire: string }
+  > {
+    const out: Record<string, { payload: string; host: string; wire: string }> = {};
+    const re =
+      /^\s*([a-z]+)\)\s*printf\s+'%s'\s+'([^|]+)\|([^|]+)\|([^']+)'\s*;;/gm;
+    let m;
+    while ((m = re.exec(bash)) !== null) {
+      out[m[1]] = { payload: m[2], host: m[3], wire: m[4] };
+    }
+    return out;
+  }
+
+  it('the derived PackContributeKey union == the table keys (8 keys incl. mcp)', () => {
+    // CONTRIBUTION_KEYS IS PackContributeKey's source (types.ts derives the
+    // union from it). Assert the full expected set is present, no more, no less.
+    expect([...CONTRIBUTION_KEYS].sort()).toEqual(
+      [
+        'commands',
+        'hooks',
+        'knowledge',
+        'mcp',
+        'policies',
+        'scripts',
+        'skills',
+        'workers',
+      ].sort(),
+    );
+    // Type-level: every key is assignable to PackContributeKey.
+    const asUnion: PackContributeKey[] = [...CONTRIBUTION_KEYS];
+    expect(asUnion.length).toBe(8);
+  });
+
+  it('every key has a wire mode of exactly symlink|merge, mcp is the merge row', () => {
+    for (const k of CONTRIBUTION_KEYS) {
+      expect(['symlink', 'merge']).toContain(CONTRIBUTION_TABLE[k].wire);
+    }
+    expect(CONTRIBUTION_TABLE.mcp.wire).toBe('merge');
+    expect(CONTRIBUTION_TABLE.mcp.payload).toBe('mcp/{item}.json');
+    expect(CONTRIBUTION_TABLE.mcp.host).toBe('merge:claude+codex');
+    // All non-mcp rows are symlink in this milestone.
+    for (const k of CONTRIBUTION_KEYS) {
+      if (k !== 'mcp') expect(CONTRIBUTION_TABLE[k].wire).toBe('symlink');
+    }
+  });
+
+  it('payload suffixes are pinned per key (suffix is load-bearing)', () => {
+    const suffix = (p: string) => {
+      const base = p.split('/').pop() as string;
+      const dot = base.indexOf('.', base.indexOf('}'));
+      return dot >= 0 ? base.slice(dot) : '';
+    };
+    expect(suffix(CONTRIBUTION_TABLE.commands.payload)).toBe('.md');
+    expect(suffix(CONTRIBUTION_TABLE.policies.payload)).toBe('.md');
+    expect(suffix(CONTRIBUTION_TABLE.hooks.payload)).toBe('.sh');
+    expect(suffix(CONTRIBUTION_TABLE.mcp.payload)).toBe('.json');
+    expect(suffix(CONTRIBUTION_TABLE.workers.payload)).toBe('');
+    expect(suffix(CONTRIBUTION_TABLE.knowledge.payload)).toBe('');
+    expect(suffix(CONTRIBUTION_TABLE.skills.payload)).toBe('');
+    expect(suffix(CONTRIBUTION_TABLE.scripts.payload)).toBe('');
+  });
+
+  (scanPath ? it : it.skip)(
+    'scan-packages.sh generated block matches the table on key-set + payload + host + wire',
+    () => {
+      const bash = fs.readFileSync(scanPath as string, 'utf-8');
+      const bashTable = parseBashTable(bash);
+
+      // FULL key-set equivalence (fails if a surface is MISSING a key or has an
+      // EXTRA one — not just a substring presence check).
+      expect(Object.keys(bashTable).sort()).toEqual([...CONTRIBUTION_KEYS].sort());
+
+      // Per-key payload + host + wire-mode equivalence.
+      for (const k of CONTRIBUTION_KEYS) {
+        expect(bashTable[k], `scan-packages.sh missing row for "${k}"`).toBeDefined();
+        expect(bashTable[k].payload).toBe(CONTRIBUTION_TABLE[k].payload);
+        expect(bashTable[k].host).toBe(CONTRIBUTION_TABLE[k].host);
+        expect(bashTable[k].wire).toBe(CONTRIBUTION_TABLE[k].wire);
+      }
+
+      // The CONTRIB_KEYS array in the script also lists every key.
+      const keysLine = bash.match(/CONTRIB_KEYS=\(([^)]*)\)/);
+      expect(keysLine).not.toBeNull();
+      const bashKeys = (keysLine as RegExpMatchArray)[1].trim().split(/\s+/).sort();
+      expect(bashKeys).toEqual([...CONTRIBUTION_KEYS].sort());
+    },
+  );
+
+  it('validateManifest payload reader (payloadFor) agrees with the table for every key', () => {
+    for (const k of CONTRIBUTION_KEYS) {
+      // payloadFor is exactly what validateManifest now uses for the
+      // payload-existence check, so this pins that surface to the table.
+      expect(payloadFor(k, 'demo')).toBe(
+        CONTRIBUTION_TABLE[k].payload.replace('{item}', 'demo'),
+      );
     }
   });
 });
@@ -257,3 +383,109 @@ describe('readHqVersion: v15 layout awareness (feedback_57d7edcf, symptom b)', (
     expect(readHqVersion(hqRoot)).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// US-009: unwirePackMcp — the wire:merge (MCP) un-registration parallel to the
+// symlink unwirePack. Runs against an ISOLATED tmpdir home (env.home) so the
+// developer's real ~/.claude.json / ~/.codex are NEVER touched.
+// ---------------------------------------------------------------------------
+
+describe('US-009: unwirePackMcp (mcp un-registration parallel to symlink unwire)', () => {
+  let mcpHome: string;
+
+  beforeEach(() => {
+    mcpHome = mkTmp('hq-unwire-mcp-');
+  });
+  afterEach(() => {
+    fs.rmSync(mcpHome, { recursive: true, force: true });
+  });
+
+  it('un-registers ONLY this pack\'s provenance-stamped mcp servers from ~/.claude.json', () => {
+    const env = { home: mcpHome };
+    // The user owns `figma`; our pack installs `vyg`.
+    fs.writeFileSync(
+      claudeConfigPath(env),
+      JSON.stringify({ mcpServers: { figma: { type: 'http', url: 'https://figma' } } }, null, 2) + '\n',
+    );
+    registerClaudeServer({ name: 'vyg', manifest: { type: 'http', url: 'https://vyg' }, pack: 'hq-pack-vyg', env });
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers).toHaveLength(1);
+    expect(result.servers[0]!.claude.outcome).toBe('removed');
+
+    const after = JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8'));
+    expect(after.mcpServers.vyg).toBeUndefined(); // ours removed
+    expect(after.mcpServers.figma.url).toBe('https://figma'); // user sibling preserved
+  });
+
+  it('no-ops cleanly when the pack declares no mcp (merge) keys', () => {
+    const result = unwirePackMcp('hq-pack-x', { commands: ['foo'], skills: ['bar'] }, { env: { home: mcpHome } });
+    expect(result.servers).toEqual([]);
+  });
+
+  it('skip-and-warns (does not delete) a foreign/unstamped same-named entry', () => {
+    const env = { home: mcpHome };
+    // The user has their OWN `vyg` (no _hqPack stamp).
+    fs.writeFileSync(
+      claudeConfigPath(env),
+      JSON.stringify({ mcpServers: { vyg: { type: 'http', url: 'https://user-vyg' } } }, null, 2) + '\n',
+    );
+    const before = fs.readFileSync(claudeConfigPath(env), 'utf-8');
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers[0]!.claude.outcome).toBe('skipped-foreign');
+    // The user's server is left byte-for-byte intact.
+    expect(fs.readFileSync(claudeConfigPath(env), 'utf-8')).toBe(before);
+  });
+
+  it('is a clean no-op on a Codex-less host with no ~/.claude.json (never fabricates)', () => {
+    const env = { home: mcpHome };
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers[0]!.claude.outcome).toBe('absent');
+    expect('skipped' in result.servers[0]!.codex && (result.servers[0]!.codex as any).skipped).toBe(true);
+    expect(fs.existsSync(path.join(mcpHome, '.claude.json'))).toBe(false);
+    expect(fs.existsSync(path.join(mcpHome, '.codex'))).toBe(false);
+  });
+
+  it('delegates to unregisterMcpServers across BOTH surfaces when ~/.codex exists', () => {
+    // The unwire-hook must un-register from Claude AND Codex (not just Claude) — i.e.
+    // it really delegates to unregisterMcpServers, which fans out over both surfaces.
+    const env = { home: mcpHome };
+    fs.mkdirSync(codexHome(env), { recursive: true }); // make Codex a real runtime
+    // Install our vyg into BOTH surfaces, alongside a user-owned figma on Claude.
+    fs.writeFileSync(
+      claudeConfigPath(env),
+      JSON.stringify({ mcpServers: { figma: { type: 'http', url: 'https://figma' } } }, null, 2) + '\n',
+    );
+    registerServer({ name: 'vyg', manifest: { type: 'http', url: 'https://vyg' }, pack: 'hq-pack-vyg', env });
+    // Both surfaces carry vyg before uninstall.
+    expect(JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8')).mcpServers.vyg).toBeDefined();
+    expect((parseToml(fs.readFileSync(codexConfigPath(env), 'utf-8')) as any).mcp_servers.vyg).toBeDefined();
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers).toHaveLength(1);
+    expect(result.servers[0]!.claude.outcome).toBe('removed');
+    expect('skipped' in result.servers[0]!.codex).toBe(false);
+    expect((result.servers[0]!.codex as any).outcome).toBe('removed');
+
+    // Both surfaces no longer carry vyg; the user's Claude figma sibling survives.
+    expect(JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8')).mcpServers.vyg).toBeUndefined();
+    expect(JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8')).mcpServers.figma).toBeDefined();
+    expect((parseToml(fs.readFileSync(codexConfigPath(env), 'utf-8')) as any).mcp_servers.vyg).toBeUndefined();
+  });
+
+  it('skip-and-warns a foreign Codex table too (does not delete another pack\'s server)', () => {
+    // The Codex parallel of the foreign skip: a vyg table stamped by ANOTHER pack must
+    // be left in place when uninstalling OUR pack — provenance scope, not name match.
+    const env = { home: mcpHome };
+    fs.mkdirSync(codexHome(env), { recursive: true });
+    const original =
+      '# keep me\n[mcp_servers.vyg]\ntype = "http"\nurl = "https://vyg"\n_hqPack = "hq-pack-OTHER"\n';
+    fs.writeFileSync(codexConfigPath(env), original);
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect((result.servers[0]!.codex as any).outcome).toBe('skipped-foreign');
+    // Byte-for-byte preserved (comment intact — no write on a foreign skip).
+    expect(fs.readFileSync(codexConfigPath(env), 'utf-8')).toBe(original);
+  });
+});