@indigoai-us/hq-cli 5.50.0 → 5.50.1

package/dist/commands/pack-install.js

@@ -34,7 +34,7 @@
  * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cb8b5583-b60f-52a5-802d-befc33f2a07b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fbfbcf69-d410-51cb-ae59-886c451b3a55")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -48,9 +48,12 @@ import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
 import semverGt from 'semver/functions/gt.js';
 import { findHqRoot } from '../utils/manifest.js';
-import { readHqVersion } from '../utils/pack-contributions.js';
+import { readHqVersion, routeContribution } from '../utils/pack-contributions.js';
+import { CONTRIBUTION_TABLE, payloadFor } from '../utils/contribution-table.js';
 import { safeExtractTarball } from './safe-extract.js';
 import { vaultApiFetchPublic } from '../utils/vault-api.js';
+import { redactSecrets, SECRET_REDACTION, registerMcpServers, McpManifestError, } from './mcp-registration.js';
+import { readCache, listSecretCacheScopes } from '../utils/secrets-cache.js';
 /** Prefix that routes a source through the HQ marketplace transport (US-006). */
 export const MARKETPLACE_PREFIX = 'marketplace:';
 export function classify(source) {
@@ -712,6 +715,150 @@ export function verifyArtifact(input) {
     }
 }
 // ---------------------------------------------------------------------------
+// MCP per-server manifest validation (US-005, the TS counterpart of the bash
+// `validate_mcp_manifest` arm in core/scripts/scan-packages.sh).
+//
+// The `mcp` contributes key is `wire: 'merge'` — its per-server manifests are
+// NEVER symlinked; they are validated here and (US-006) merged into the agent
+// configs via registerMcpServers. This function MIRRORS the bash transport
+// rules hand-coded against the draft-07 schema
+// (repos/public/knowledge-hq-core/mcp-manifest.schema.json). There is no `ajv`
+// dependency in hq-cli; the schema file is single-source documentation, so the
+// rules are replicated here (dependency-free, robust if the schema is absent).
+// ---------------------------------------------------------------------------
+/** Allowed top-level keys (schema `additionalProperties: false`). */
+const MCP_ALLOWED_KEYS = ['type', 'url', 'headers', 'command', 'args', 'env', 'tools'];
+/** Schema `$id` for an at-a-glance error reference (kept inline; no file read). */
+const MCP_SCHEMA_ID = 'mcp-manifest.schema.json';
+/** True iff a header/env value carries a `${secret:NAME}` reference. */
+function hasSecretRef(value) {
+    return /\$\{secret:/.test(value);
+}
+/**
+ * Validate that a record (`headers` or `env`) is an object of STRING values,
+ * pushing one error per offending entry into `errs`. Mirrors the schema's
+ * `additionalProperties: { type: 'string' }`.
+ */
+function checkStringMap(errs, label, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        errs.push(`${label} must be an object`);
+        return;
+    }
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof v !== 'string') {
+            errs.push(`${label} "${k}" value must be a string`);
+        }
+    }
+}
+/**
+ * Parse + shape-validate one pack's per-server MCP manifest (`mcp/{item}.json`),
+ * mirroring the bash `validate_mcp_manifest` arm. EXPORTED so the acceptance
+ * test (and US-006's registration engine) can call it directly.
+ *
+ * Throws an `Error` (whose message names the pack-relative payload path, e.g.
+ * `mcp/foo.json`) when the file does not parse as JSON or violates a transport
+ * rule:
+ *   - `type` required, one of `http|stdio|sse`;
+ *   - no unknown top-level keys (allowed: {@link MCP_ALLOWED_KEYS});
+ *   - http/sse: `url` required + `^https?://`; `command`/`args`/`env` forbidden;
+ *   - stdio: non-empty `command` required; `url`/`headers` forbidden;
+ *   - `headers`/`env` (if present) are objects of string values;
+ *   - NO inline literal `Bearer ` secret — such a value MUST carry a
+ *     `${secret:NAME}` reference, never a literal token.
+ *
+ * @param payloadDir the pack payload root (holds `mcp/{item}.json`)
+ * @param item       the bare server name declared under `contributes.mcp`
+ */
+export function validateMcpManifest(payloadDir, item) {
+    const rel = payloadFor('mcp', item); // mcp/{item}.json
+    const abs = path.join(payloadDir, rel);
+    // EXISTS — the existsSync gate in validateManifest already covers this, but
+    // re-check so the helper is safe to call standalone (tests, US-006).
+    if (!fs.existsSync(abs)) {
+        throw new Error(`MCP manifest missing: ${rel} (declared under contributes.mcp but no such file)`);
+    }
+    // PARSE — a non-JSON file is a hard error that names the file.
+    let doc;
+    try {
+        doc = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`MCP manifest malformed: ${rel} is not valid JSON (failed to parse: ${e.message})`);
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+        throw new Error(`MCP manifest malformed: ${rel} must be a JSON object`);
+    }
+    const m = doc;
+    const errs = [];
+    // type: required + enum.
+    const type = m.type;
+    if (!('type' in m)) {
+        errs.push('missing required field: type');
+    }
+    else if (type !== 'http' && type !== 'stdio' && type !== 'sse') {
+        errs.push(`type must be one of http|stdio|sse (got: ${JSON.stringify(type)})`);
+    }
+    // No unknown top-level keys (schema additionalProperties: false).
+    for (const k of Object.keys(m)) {
+        if (!MCP_ALLOWED_KEYS.includes(k)) {
+            errs.push(`unknown top-level key: ${k}`);
+        }
+    }
+    // http / sse transport: url required (^https?://); command/args/env forbidden.
+    if (type === 'http' || type === 'sse') {
+        if (!('url' in m)) {
+            errs.push(`${type} transport requires a url`);
+        }
+        else if (typeof m.url !== 'string' || !/^https?:\/\//.test(m.url)) {
+            errs.push('url must be an absolute http(s) URL');
+        }
+        for (const forbidden of ['command', 'args', 'env']) {
+            if (forbidden in m)
+                errs.push(`${type} transport forbids: ${forbidden}`);
+        }
+    }
+    // stdio transport: non-empty command required; url/headers forbidden.
+    if (type === 'stdio') {
+        if (typeof m.command !== 'string' || m.command.length === 0) {
+            errs.push('stdio transport requires a non-empty command');
+        }
+        for (const forbidden of ['url', 'headers']) {
+            if (forbidden in m)
+                errs.push(`stdio transport forbids: ${forbidden}`);
+        }
+    }
+    // headers / env values must be strings.
+    if ('headers' in m)
+        checkStringMap(errs, 'headers', m.headers);
+    if ('env' in m)
+        checkStringMap(errs, 'env', m.env);
+    if (errs.length > 0) {
+        throw new Error(`MCP manifest fails shape validation: ${rel} (schema: ${MCP_SCHEMA_ID})\n` +
+            errs.map((e) => `  - ${e}`).join('\n'));
+    }
+    // Reject INLINE LITERAL Bearer secrets. A header/env value containing
+    // 'Bearer ' MUST use a ${secret:NAME} reference, never a literal token baked
+    // into a synced/committed artifact.
+    const bad = [];
+    for (const [label, mapVal] of [
+        ['header', m.headers],
+        ['env', m.env],
+    ]) {
+        if (mapVal === null || typeof mapVal !== 'object' || Array.isArray(mapVal))
+            continue;
+        for (const [k, v] of Object.entries(mapVal)) {
+            if (typeof v === 'string' && v.includes('Bearer ') && !hasSecretRef(v)) {
+                bad.push(`${label} "${k}"`);
+            }
+        }
+    }
+    if (bad.length > 0) {
+        throw new Error(`MCP manifest contains an inline literal Bearer secret: ${rel} (${bad.join(', ')}) — ` +
+            'a \'Bearer \' header/env value MUST use a ${secret:NAME} reference, never a literal token ' +
+            '(a resolved secret is never written to a synced/committed artifact)');
+    }
+}
+// ---------------------------------------------------------------------------
 // Manifest validation (spec §Validation, 10 checks)
 // ---------------------------------------------------------------------------
 export function validateManifest(payloadDir, hqVersion) {
@@ -766,25 +913,32 @@ export function validateManifest(payloadDir, hqVersion) {
     if (!nonEmpty) {
         throw new Error('contributes must have at least one non-empty subfield');
     }
-    // 10. payload files exist (hooks check happens separately in step 8)
-    const subpaths = {
-        workers: (i) => path.join('workers', i),
-        knowledge: (i) => path.join('knowledge', i),
-        skills: (i) => path.join('skills', i),
-        commands: (i) => path.join('commands', `${i}.md`),
-        hooks: (i) => path.join('hooks', `${i}.sh`),
-        policies: (i) => path.join('policies', `${i}.md`),
-        scripts: (i) => path.join('scripts', i),
-    };
+    // 10. payload files exist (hooks check happens separately in step 8).
+    // Payload paths are READ from the single-source CONTRIBUTION_TABLE (US-003)
+    // via payloadFor -- no restated `subpaths` record. An unknown key (not in the
+    // table) is rejected here so a typo can't silently install unwired.
     for (const [key, items] of Object.entries(contributes)) {
+        if (!(key in CONTRIBUTION_TABLE)) {
+            throw new Error(`contributes.${key} is not a known contribution type`);
+        }
         if (!Array.isArray(items))
             continue;
         for (const item of items) {
-            const rel = subpaths[key](item);
+            const rel = payloadFor(key, item);
             const abs = path.join(payloadDir, rel);
             if (!fs.existsSync(abs)) {
                 throw new Error(`contributes.${key} declares "${item}" but payload file missing: ${rel}`);
             }
+            // The `mcp` key (wire: 'merge') is NOT existsSync-only: after the file is
+            // confirmed present it must PARSE + SHAPE-validate against the per-server
+            // MCP schema (US-005), mirroring the bash validate_mcp_manifest arm. Other
+            // (symlink) keys keep their existsSync-only behavior. We dispatch on the
+            // ROUTE from the single-source table (not a hardcoded key) so the merge
+            // path is table-driven; the merge itself (registering into the agent
+            // configs via registerMcpServers, US-006) is NEVER a symlink.
+            if (routeContribution(key) === 'merge') {
+                validateMcpManifest(payloadDir, item);
+            }
         }
     }
     // author + capabilities (US-001) — both OPTIONAL and backwards-compatible.
@@ -901,6 +1055,122 @@ async function confirmHooks(pkg, allowHooks) {
     return /^(y|yes)$/i.test(answer.trim());
 }
 // ---------------------------------------------------------------------------
+// MCP confirmation (US-010)
+//
+// The MCP equivalent of confirmHooks. MCP servers are a high-trust surface: an
+// http/sse server points your agent at a REMOTE endpoint (typosquat / phishing
+// risk — the FULL url is disclosed verbatim so the operator can eyeball it), and
+// a stdio server runs a LOCAL binary with your shell permissions. We GATE on a
+// non-empty `contributes.mcp` (NEVER the advisory `capabilities` field, which is
+// reserved/unenforced — gating on it would let a pack omit a capability to dodge
+// the prompt) and render per-server transport + url-or-command + a count of ALL
+// servers being added.
+//
+// REDACTION: header/env VALUES are never printed. The manifests use
+// `${secret:NAME}` references (never literal Bearers), but we STILL run the
+// rendered prompt through `redactSecrets` against the raw header/env values so
+// that even a LITERAL secret could not leak. We show header KEY names with a
+// redacted value marker.
+//
+// FAIL-SAFE: a manifest that fails to load/parse here is NOT a bypass — we
+// surface the server name with a `[manifest unreadable]` note and STILL require
+// confirmation (a malformed manifest should make the operator MORE cautious).
+// ---------------------------------------------------------------------------
+/**
+ * Render one declared MCP server's prompt line, redacting every header/env value.
+ * EXPORTED so the acceptance/redaction self-test can assert no secret/Bearer
+ * substring ever appears in the rendered output.
+ */
+export function renderMcpServerLine(payloadDir, item) {
+    let manifest;
+    try {
+        const abs = path.join(payloadDir, payloadFor('mcp', item));
+        manifest = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+        if (manifest === null || typeof manifest !== 'object')
+            throw new Error('not an object');
+    }
+    catch {
+        // Fail-safe: do not crash the prompt; flag the server and keep requiring
+        // confirmation.
+        return `  - ${item}  [manifest unreadable] — could not load mcp/${item}.json; treat with caution`;
+    }
+    const transport = manifest.type;
+    // Accumulate every raw header/env value so a final redactSecrets pass scrubs
+    // even a literal token that slipped past `${secret:}` (defense in depth — we
+    // already replace the values with the redaction marker below).
+    const rawValues = new Set();
+    for (const v of Object.values(manifest.headers ?? {}))
+        rawValues.add(v);
+    for (const v of Object.values(manifest.env ?? {}))
+        rawValues.add(v);
+    // Header KEYS shown, VALUES always redacted (never the raw value).
+    const headerKeys = Object.keys(manifest.headers ?? {});
+    const headerStr = headerKeys.length > 0
+        ? `   headers: { ${headerKeys.map((k) => `${k}: ${SECRET_REDACTION}`).join(', ')} }`
+        : '';
+    let line;
+    if (transport === 'http' || transport === 'sse') {
+        // FULL url verbatim — typosquat disclosure is the whole point.
+        line =
+            `  - ${item}  [${transport}]  url: ${manifest.url ?? '(missing)'}` +
+                headerStr +
+                `   (contacts a remote endpoint)`;
+    }
+    else {
+        // stdio — local binary with shell permissions.
+        const args = manifest.args ?? [];
+        const argsStr = args.length > 0 ? `  args: [${args.join(', ')}]` : '';
+        line =
+            `  - ${item}  [stdio] command: ${manifest.command ?? '(missing)'}` +
+                argsStr +
+                headerStr +
+                `   (runs a local binary with your shell permissions)`;
+    }
+    // Final defense-in-depth scrub: even though values are already replaced with
+    // the marker above, run the whole line through redactSecrets so a stray
+    // literal token (e.g. inside command/args) can never reach the terminal.
+    return redactSecrets(line, rawValues);
+}
+/**
+ * Install-time MCP trust prompt. EXPORTED so the acceptance test can drive the
+ * gate / bypass / non-TTY branches directly (capture stdout, assert no secret
+ * substring leaks, assert deny returns false). See {@link confirmHooks} for the
+ * voice/shape this mirrors.
+ */
+export async function confirmMcp(pkg, payloadDir, allowMcp) {
+    // GATE on non-empty `contributes.mcp` — mirrors confirmHooks. Never on the
+    // advisory `capabilities` field.
+    const servers = pkg.contributes.mcp ?? [];
+    if (servers.length === 0)
+        return true;
+    if (allowMcp) {
+        console.log(chalk.yellow(`--allow-mcp set; registering ${servers.length} MCP server(s) without prompting.`));
+        return true;
+    }
+    console.log('');
+    console.log(chalk.yellow(`Pack ${pkg.publisher}/${pkg.name} declares ${servers.length} MCP server(s):`));
+    for (const item of servers) {
+        console.log(chalk.yellow(renderMcpServerLine(payloadDir, item)));
+    }
+    console.log(chalk.yellow('These servers will be registered into your Claude and Codex agent configs.'));
+    // Non-TTY guard (mirrors the secrets.ts pattern): do NOT call rl.question in a
+    // non-interactive shell — it would hang. Instruct the operator to re-run with
+    // --allow-mcp and DENY (return false -> abort, no partial state).
+    if (!process.stdin.isTTY) {
+        console.log(chalk.red(`Refusing to register ${servers.length} MCP server(s) without confirmation ` +
+            'in a non-interactive shell. Re-run with --allow-mcp to approve.'));
+        return false;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+        rl.question('Install anyway? [y/N] ', (a) => {
+            rl.close();
+            resolve(a);
+        });
+    });
+    return /^(y|yes)$/i.test(answer.trim());
+}
+// ---------------------------------------------------------------------------
 // Conditional predicate
 //
 // `package.yaml:conditional` is arbitrary bash sourced from a remote pack.
@@ -935,6 +1205,119 @@ function evalConditional(expr) {
     return r.status === 0;
 }
 // ---------------------------------------------------------------------------
+// MCP registration wiring (US-007) — call registerMcpServers from installPack.
+//
+// The registration CORE + Claude/Codex emitters live in mcp-registration.ts and
+// are fully unit-tested; this is the install-time SEAM that feeds them a real
+// manifest loader and a production, vault-backed secret resolver, with per-server
+// secret-deferral so a fresh install (before `/connect-shopify` has minted the
+// key) still SUCCEEDS, skipping only the server whose secret is not yet present.
+// ---------------------------------------------------------------------------
+/**
+ * Build the install-time {@link SecretResolver} bound to the HQ vault's local
+ * secrets-cache (`~/.hq/secrets-cache/<scope>/<NAME>`, AES-256-GCM, 0600, TTL'd).
+ *
+ * Active-company resolution at install time is INDIRECT by design: `hq install`
+ * has no `--company` flag and runs OFFLINE (no token), so we cannot resolve a
+ * single active company UID the way `hq run` / `hq secrets` do (via
+ * `getEntityUid` over the network). Instead we probe EVERY cached scope
+ * (`cmp_*`/`prs_*` — whichever has minted secrets locally) for the requested
+ * name and return the first hit. This naturally resolves to whichever company
+ * context just provisioned the secret (e.g. the one `/connect-shopify` minted
+ * `VYG_API_KEY` under), without guessing, and works whether the vault scoped the
+ * key under a company or person entity.
+ *
+ * On MISS across all scopes (no cache, expired TTL, or key never minted) it
+ * returns `null` — which is exactly what {@link registerMcpServers}'s
+ * unresolvable-secret path keys off to defer that server gracefully. With no
+ * cached scopes at all (`listSecretCacheScopes()` → `[]`) it simply returns
+ * `null` for every name, the desired graceful-deferral behavior.
+ */
+export function makeInstallSecretResolver() {
+    return (name) => {
+        for (const scope of listSecretCacheScopes()) {
+            const value = readCache(scope, name);
+            if (value !== null)
+                return value;
+        }
+        return null;
+    };
+}
+/**
+ * Load + shape-validate + parse a pack's per-server MCP manifest from disk.
+ * `validateMcpManifest(destDir, name)` is the SAME shape gate `validateManifest`
+ * runs at install; it returns void and THROWS on bad shape, so we call it first
+ * (re-using one source of truth), then parse `mcp/<name>.json` and return it
+ * typed as {@link McpManifest}. `destDir` is the installed pack root
+ * (`core/packages/<pkg>/`), the realpath `registerMcpServers` emits from.
+ */
+function loadMcpManifestFrom(destDir, name) {
+    validateMcpManifest(destDir, name); // throws on bad shape (void on success)
+    const abs = path.join(destDir, 'mcp', `${name}.json`);
+    return JSON.parse(fs.readFileSync(abs, 'utf-8'));
+}
+/**
+ * Derive the per-server "needs secret" remedy command from the pack's
+ * `initialization.entrypoint` (e.g. the vyg pack's `connect-shopify` →
+ * `/connect-shopify`). Falls back to a generic "provision the secret then re-run
+ * `hq install`" when the pack declares no entrypoint.
+ */
+function mcpSecretRemedy(initialization) {
+    const entrypoint = initialization?.entrypoint;
+    if (typeof entrypoint === 'string' && entrypoint.trim() !== '') {
+        const command = '/' + entrypoint.trim().replace(/^\/+/, '');
+        return `run \`${command}\` to provision it, then re-run \`hq install\``;
+    }
+    return 'provision the secret then re-run `hq install`';
+}
+/** Pull the `${secret:NAME}` token out of a `cannot resolve ${secret:NAME}` error message. */
+function extractDeferredSecretName(message) {
+    const m = /\$\{secret:([^}]+)\}/.exec(message);
+    return m ? m[1] : 'a required secret';
+}
+/**
+ * Register one pack's `contributes.mcp` servers into the shared Claude/Codex
+ * agent configs, PER SERVER, so a single unresolvable `${secret:NAME}` defers
+ * ONLY that server instead of aborting the whole install. Returns the registered
+ * and skipped (deferred) server-name lists for the one-line summary.
+ *
+ * Per-server policy:
+ *   - SUCCESS                       → push to `registered`.
+ *   - McpManifestError matching
+ *     `/cannot resolve \$\{secret:/` → SKIP (push to `skipped`), warn on stderr,
+ *     install still succeeds (the key gets minted later, then a re-install wires it).
+ *   - ANY OTHER error               → RE-THROW (abort install). Only the
+ *     unresolvable-secret case is swallowed.
+ */
+function wireMcpServers(pkg, destDir) {
+    const resolveSecret = makeInstallSecretResolver();
+    const loadManifest = (name) => loadMcpManifestFrom(destDir, name);
+    const registered = [];
+    const skipped = [];
+    for (const name of pkg.contributes.mcp ?? []) {
+        try {
+            // Per-server call: registerMcpServers throws on the FIRST unresolvable
+            // secret, so calling it one name at a time lets us catch + continue.
+            registerMcpServers(pkg.name, [name], { loadManifest, resolveSecret });
+            registered.push(name);
+        }
+        catch (e) {
+            const isUnresolvableSecret = e instanceof McpManifestError && /cannot resolve \$\{secret:/.test(e.message);
+            if (!isUnresolvableSecret) {
+                // ConfigParseError / ConfigPermissionError / McpNameCollisionError / a
+                // malformed-manifest McpManifestError / etc. — propagate, abort install.
+                throw e;
+            }
+            skipped.push(name);
+            const secret = extractDeferredSecretName(e.message);
+            // Always stderr (never suppressed by --quiet): the user must see WHY a
+            // server was deferred and exactly how to finish wiring it.
+            process.stderr.write(`MCP server '${name}' needs secret ${secret} — ${mcpSecretRemedy(pkg.initialization)}.\n`);
+        }
+    }
+    return { registered, skipped };
+}
+// ---------------------------------------------------------------------------
 // Move into core/packages/ + run core/scripts/scan-packages.sh
 // ---------------------------------------------------------------------------
 /**
@@ -1116,6 +1499,17 @@ export async function installPack(source, opts = {}) {
             say(chalk.red('Install aborted (hooks denied).'));
             return;
         }
+        // US-010 — install-time MCP trust prompt. Positioned AFTER confirmHooks and
+        // BEFORE installToPackages so a deny aborts with NO partial state (no config
+        // written, no pack moved into core/packages, no registerMcpServers call). The
+        // actual registration (US-007) now fires AFTER installToPackages +
+        // runScanPackages below (pack on disk + symlinks wired), once this gate has
+        // confirmed the servers — so a deny here means registration never runs.
+        const mcpConfirmed = await confirmMcp(pkg, fetched.payloadDir, opts.allowMcp ?? false);
+        if (!mcpConfirmed) {
+            say(chalk.red('Install aborted (MCP servers denied).'));
+            return;
+        }
         const destDir = installToPackages(fetched.payloadDir, pkg, hqRoot);
         // Under the v12+ HQ layout, packs live at `core/packages/<name>/` and
         // are tracked by filesystem presence — no `modules.yaml` write (that
@@ -1133,6 +1527,20 @@ export async function installPack(source, opts = {}) {
         const stampedSource = transport === 'marketplace' ? fetched.resolvedSource : source;
         stampInstallSource(destDir, stampedSource);
         runScanPackages(hqRoot, { quiet: opts.quiet });
+        // US-007 — register `contributes.mcp` servers into the shared Claude/Codex
+        // agent configs. Fires HERE (after installToPackages + runScanPackages, i.e.
+        // pack on disk + symlinks wired) and only once the confirmMcp gate above
+        // approved them. The `mcp` key is wire:'merge' — NEVER symlinked; this merge
+        // is its only wiring path. registerMcpServers honors the
+        // HQ_DISABLE_MCP_REGISTRATION kill-switch internally, so we never re-check it.
+        // Per-server secret-deferral keeps a fresh install (key not yet minted) at
+        // exit 0, deferring only the unresolvable server (see wireMcpServers).
+        if (Array.isArray(pkg.contributes.mcp) && pkg.contributes.mcp.length > 0) {
+            const { registered, skipped } = wireMcpServers(pkg, destDir);
+            // One-line summary (server NAMES only — never resolved secret VALUES).
+            say(chalk.dim(`  MCP servers: registered [${registered.join(', ')}]; ` +
+                `skipped [${skipped.join(', ')}].`));
+        }
         say(chalk.green(`\nOK Installed ${pkg.name}@${pkg.version} -> ${path.relative(hqRoot, destDir)}/`));
         say(chalk.dim(`  Wired ${Object.values(pkg.contributes).flat().filter(Boolean).length} ` +
             `contribution(s) into host-side paths.`));
@@ -1150,4 +1558,4 @@ export async function installPack(source, opts = {}) {
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=cb8b5583-b60f-52a5-802d-befc33f2a07b
+//# debugId=fbfbcf69-d410-51cb-ae59-886c451b3a55

package/dist/commands/packs.js

@@ -18,7 +18,7 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="527d0e7d-2101-5438-8251-2579a40453e6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="570f7491-8d05-577c-8bae-6f6cf7dfb2ec")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
@@ -27,7 +27,7 @@ import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { classify, resolveLatest, resolveLatestMarketplace, runScanPackages, installPack, } from './pack-install.js';
-import { contributionLinks, linkStatus, listInstalledPacks, readPackManifest, unwirePack, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
+import { contributionLinks, linkStatus, listInstalledPacks, readPackManifest, unwirePack, unwirePackMcp, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
 function resolveRoot(opts) {
     return opts.hqRoot ? path.resolve(opts.hqRoot) : findHqRoot();
 }
@@ -246,6 +246,7 @@ async function runUpdate(name, opts) {
             try {
                 await installPack(source, {
                     allowHooks: opts.yes || opts.allowHooks,
+                    allowMcp: opts.yes || opts.allowMcp,
                     followBranch: opts.branch,
                     quiet: wantsJson(opts),
                 });
@@ -279,6 +280,28 @@ async function runUninstall(name, opts) {
     }
     // 1. Un-wire only our symlinks.
     const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
+    // 1b. Un-register the pack's MCP (`wire: 'merge'`) servers — invisible to the
+    // symlink unwire above. Provenance-scoped: removes ONLY entries stamped with this
+    // pack's `_hqPack`, and skip-and-warns on any foreign/unstamped same-named entry.
+    // Tolerant of a Codex-less host / absent config; idempotent on re-run.
+    try {
+        const mcp = unwirePackMcp(name, contributes);
+        for (const server of mcp.servers) {
+            if ('skipped' in server.claude)
+                continue; // (claude is always inspected; never skipped)
+            if (server.claude.outcome === 'skipped-foreign' && server.claude.reason) {
+                warnings.push(server.claude.reason);
+            }
+            if (!('skipped' in server.codex) && server.codex.outcome === 'skipped-foreign' && server.codex.reason) {
+                warnings.push(server.codex.reason);
+            }
+        }
+    }
+    catch (e) {
+        // Never let an MCP un-registration failure abort the rest of the uninstall
+        // (symlink unwire already ran; the pack dir still gets archived). Surface it.
+        warnings.push(`MCP un-registration encountered an error: ${e.message}`);
+    }
     // 2. Archive (or delete) the pack dir -- BEFORE re-scan so it isn't re-wired.
     let archived = null;
     if (opts.archive === false) {
@@ -358,8 +381,9 @@ export function registerPacksCommand(parent) {
         .option('--json', 'Machine-readable JSON output')
         .option('--hq-root <path>', 'HQ root (default: auto-detect)')
         .option('--check-only', 'Report availability without installing')
-        .option('-y, --yes', 'Non-interactive (implies --allow-hooks)')
+        .option('-y, --yes', 'Non-interactive (implies --allow-hooks and --allow-mcp)')
         .option('--allow-hooks', 'Install pack hooks without prompting')
+        .option('--allow-mcp', 'Register pack MCP servers without prompting')
         .option('--branch', 'Follow the source branch instead of SHA-pinning')
         .action(async (name, opts) => {
         try {
@@ -425,4 +449,4 @@ export function registerPacksCommand(parent) {
     });
 }
 //# sourceMappingURL=packs.js.map
-//# debugId=527d0e7d-2101-5438-8251-2579a40453e6
+//# debugId=570f7491-8d05-577c-8bae-6f6cf7dfb2ec

package/dist/commands/pkg-install.js

@@ -13,7 +13,7 @@
  * 9. Print next-step message
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ac6f26b7-5678-5b4e-b0d8-2f5901adf9fe")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ccc2e70c-f577-5a47-9a29-31a206194392")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -33,12 +33,14 @@ export function registerPackageInstallCommand(parent) {
         '@scope/name[@ver] (npm pack), git URL[#ref], or local path.')
         .option('--company <co>', 'Scope the package to a specific company (registry flow only)')
         .option('--allow-hooks', 'Skip the hooks confirmation prompt (content-pack flow)')
+        .option('--allow-mcp', 'Skip the MCP server confirmation prompt (content-pack flow)')
         .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
         .action(async (source, opts) => {
         try {
             if (sourceMatchesPackPattern(source)) {
                 await installPack(source, {
                     allowHooks: opts.allowHooks,
+                    allowMcp: opts.allowMcp,
                     followBranch: opts.branch,
                 });
             }
@@ -49,6 +51,7 @@ export function registerPackageInstallCommand(parent) {
                 // listings transport — the live install path — instead.
                 await installPack(`${MARKETPLACE_PREFIX}${source}`, {
                     allowHooks: opts.allowHooks,
+                    allowMcp: opts.allowMcp,
                     followBranch: opts.branch,
                 });
             }
@@ -163,4 +166,4 @@ async function installPackage(slug, company) {
     }
 }
 //# sourceMappingURL=pkg-install.js.map
-//# debugId=ac6f26b7-5678-5b4e-b0d8-2f5901adf9fe
+//# debugId=ccc2e70c-f577-5a47-9a29-31a206194392

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d57c1cc3-6dd3-5c7f-8eef-c7692d41b836")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="34e9e978-4c0a-5113-82af-9a33e30686c6")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -44,6 +44,7 @@ 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, } from "./utils/version-check.js";
@@ -159,6 +160,10 @@ registerReindexCommand(program);
 // the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
 // 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({
@@ -198,4 +203,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=d57c1cc3-6dd3-5c7f-8eef-c7692d41b836
+//# debugId=34e9e978-4c0a-5113-82af-9a33e30686c6