@indigoai-us/hq-cli 5.50.0 → 5.50.2

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]="0ec07d3a-ee86-51fd-adbd-2608c620ae99")}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, listInstalledPacks } 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) {
@@ -760,31 +907,64 @@ export function validateManifest(payloadDir, hqVersion) {
     if (hqVersion && !semverSatisfies(hqVersion, range, { includePrerelease: true })) {
         throw new Error(`Host hqCore ${hqVersion} does not satisfy pack requirement ${range}`);
     }
+    // 6b. requires.packs (M0) — OPTIONAL pack-to-pack dependencies. Absent → legacy
+    // behavior (hqCore is the only prerequisite). Present → a list of
+    // { name, version? } where `name` is a valid hq-pack name and `version` (if
+    // given) is a valid semver RANGE. SHAPE validation only (no filesystem) so a
+    // malformed dependency can't masquerade as valid; whether the named packs are
+    // actually INSTALLED is enforced at install time by assertPackDependencies
+    // (which needs hqRoot — a pure manifest validator doesn't have it).
+    const reqPacks = m.requires?.packs;
+    if (reqPacks !== undefined) {
+        if (!Array.isArray(reqPacks)) {
+            throw new Error('requires.packs must be a list of { name, version? } entries');
+        }
+        for (const dep of reqPacks) {
+            if (!dep || typeof dep !== 'object' || Array.isArray(dep)) {
+                throw new Error('requires.packs entries must be mappings with a name (and optional version)');
+            }
+            const d = dep;
+            if (typeof d.name !== 'string' || !/^hq-pack-[a-z0-9][a-z0-9-]*$/.test(d.name)) {
+                throw new Error(`requires.packs[].name "${d.name}" must match ^hq-pack-[a-z0-9][a-z0-9-]*$`);
+            }
+            if (d.version !== undefined &&
+                (typeof d.version !== 'string' || !semverValidRange(d.version))) {
+                throw new Error(`requires.packs entry for "${d.name}" has an invalid version range "${d.version}"`);
+            }
+        }
+    }
     // 7. contributes has at least one non-empty subfield
     const contributes = (m.contributes ?? {});
     const nonEmpty = Object.values(contributes).some((v) => Array.isArray(v) && v.length > 0);
     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.
@@ -853,6 +1033,46 @@ export function validateManifest(payloadDir, hqVersion) {
     return m;
 }
 // ---------------------------------------------------------------------------
+// Pack-to-pack dependency pre-flight (M0)
+// ---------------------------------------------------------------------------
+/**
+ * Enforce a pack's `requires.packs`: every named dependency MUST already be
+ * installed (and satisfy its optional semver RANGE) before we write anything.
+ *
+ * Installed packs are discovered by FILESYSTEM PRESENCE via `listInstalledPacks`
+ * — deliberately NOT `modules.yaml`, which `installPack` no longer writes under
+ * the v12+ layout (a modules.yaml-based check would silently ignore every modern
+ * pack). Throws on the first unmet dependency so the install aborts with NO
+ * partial state (it is called before installToPackages). No-op when
+ * `requires.packs` is absent/empty, keeping legacy packs unaffected.
+ */
+export function assertPackDependencies(hqRoot, pkg) {
+    const deps = pkg.requires?.packs ?? [];
+    if (deps.length === 0)
+        return;
+    const installed = new Map();
+    for (const p of listInstalledPacks(hqRoot)) {
+        // Key on the manifest name when readable, else the directory name.
+        installed.set(p.manifest?.name ?? p.name, p.manifest?.version);
+    }
+    for (const dep of deps) {
+        if (dep.name === pkg.name) {
+            throw new Error(`Pack ${pkg.name} cannot list itself in requires.packs.`);
+        }
+        if (!installed.has(dep.name)) {
+            throw new Error(`Pack ${pkg.name} requires ${dep.name}, which is not installed. ` +
+                `Install it first, e.g.: hq install marketplace:${dep.name}`);
+        }
+        if (dep.version) {
+            const have = installed.get(dep.name);
+            if (!have || !semverSatisfies(have, dep.version, { includePrerelease: true })) {
+                throw new Error(`Pack ${pkg.name} requires ${dep.name} ${dep.version}, but ` +
+                    `${dep.name}${have ? ` ${have}` : ' (version unknown)'} is installed.`);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // Post-install get-started line (US-005)
 // ---------------------------------------------------------------------------
 /**
@@ -901,6 +1121,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 +1271,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
 // ---------------------------------------------------------------------------
 /**
@@ -1099,6 +1548,11 @@ export async function installPack(source, opts = {}) {
                 break;
         }
         const pkg = validateManifest(fetched.payloadDir, hqVersion);
+        // M0 — pack-to-pack dependency pre-flight. Runs BEFORE any prompts or writes
+        // so a missing/unsatisfied `requires.packs` aborts with no partial state, and
+        // before we bother the operator with hook/MCP trust prompts for a pack that
+        // can't install anyway.
+        assertPackDependencies(hqRoot, pkg);
         if (pkg.conditional) {
             const allowed = await confirmConditional(pkg, opts.allowHooks ?? false);
             if (!allowed) {
@@ -1116,6 +1570,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 +1598,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 +1629,4 @@ export async function installPack(source, opts = {}) {
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=cb8b5583-b60f-52a5-802d-befc33f2a07b
+//# debugId=0ec07d3a-ee86-51fd-adbd-2608c620ae99