@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/src/commands/pack-install.ts

@@ -53,9 +53,19 @@ 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,
+  type McpManifest,
+  type SecretResolver,
+} from './mcp-registration.js';
+import { readCache, listSecretCacheScopes } from '../utils/secrets-cache.js';
 import type { PackManifest, PackContributeKey } from '../types.js';
 
 // ---------------------------------------------------------------------------
@@ -978,6 +988,165 @@ export function verifyArtifact(input: VerifyArtifactInput): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 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: string): boolean {
+  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: string[],
+  label: 'headers' | 'env',
+  value: unknown,
+): void {
+  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 as Record<string, unknown>)) {
+    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: string, item: string): void {
+  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: unknown;
+  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 as Error).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 as Record<string, unknown>;
+  const errs: string[] = [];
+
+  // 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'] as const) {
+      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'] as const) {
+      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: string[] = [];
+  for (const [label, mapVal] of [
+    ['header', m.headers],
+    ['env', m.env],
+  ] as const) {
+    if (mapVal === null || typeof mapVal !== 'object' || Array.isArray(mapVal)) continue;
+    for (const [k, v] of Object.entries(mapVal as Record<string, unknown>)) {
+      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)
 // ---------------------------------------------------------------------------
@@ -1032,6 +1201,40 @@ export function validateManifest(
       `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 as unknown as Record<string, unknown>;
+      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 ?? {}) as PackManifest['contributes'];
   const nonEmpty = Object.values(contributes).some(
@@ -1040,26 +1243,33 @@ export function validateManifest(
   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: Record<PackContributeKey, (item: string) => string> = {
-    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),
-  };
-  for (const [key, items] of Object.entries(contributes) as [PackContributeKey, string[]][]) {
+  // 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) as [string, unknown][]) {
+    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 as PackContributeKey, item as string);
       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 as PackContributeKey) === 'merge') {
+        validateMcpManifest(payloadDir, item as string);
+      }
     }
   }
   // author + capabilities (US-001) — both OPTIONAL and backwards-compatible.
@@ -1136,6 +1346,51 @@ export function validateManifest(
   return m as PackManifest;
 }
 
+// ---------------------------------------------------------------------------
+// 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: string, pkg: PackManifest): void {
+  const deps = pkg.requires?.packs ?? [];
+  if (deps.length === 0) return;
+  const installed = new Map<string, string | undefined>();
+  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)
 // ---------------------------------------------------------------------------
@@ -1200,6 +1455,148 @@ async function confirmHooks(
   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: string, item: string): string {
+  let manifest: McpManifest;
+  try {
+    const abs = path.join(payloadDir, payloadFor('mcp', item));
+    manifest = JSON.parse(fs.readFileSync(abs, 'utf-8')) as McpManifest;
+    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<string>();
+  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: string;
+  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: PackManifest,
+  payloadDir: string,
+  allowMcp: boolean,
+): Promise<boolean> {
+  // 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: string = await new Promise((resolve) => {
+    rl.question('Install anyway? [y/N] ', (a) => {
+      rl.close();
+      resolve(a);
+    });
+  });
+  return /^(y|yes)$/i.test(answer.trim());
+}
+
 // ---------------------------------------------------------------------------
 // Conditional predicate
 //
@@ -1246,6 +1643,130 @@ function evalConditional(expr: string): boolean {
   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(): SecretResolver {
+  return (name: string): string | null => {
+    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: string, name: string): McpManifest {
+  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')) as McpManifest;
+}
+
+/**
+ * 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: PackManifest['initialization']): string {
+  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: string): string {
+  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: PackManifest,
+  destDir: string,
+): { registered: string[]; skipped: string[] } {
+  const resolveSecret = makeInstallSecretResolver();
+  const loadManifest = (name: string): McpManifest => loadMcpManifestFrom(destDir, name);
+  const registered: string[] = [];
+  const skipped: string[] = [];
+
+  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
 // ---------------------------------------------------------------------------
@@ -1398,6 +1919,13 @@ export function runScanPackages(hqRoot: string, opts: { quiet?: boolean } = {}):
 
 export interface InstallPackOptions {
   allowHooks?: boolean;
+  /**
+   * US-010 install-time MCP trust prompt bypass (CI/ambient-trust). Mirrors
+   * `allowHooks`: when set, `confirmMcp` skips the prompt and prints a yellow
+   * notice. Absent/false → the operator is prompted (or, in a non-TTY shell,
+   * the install is refused with a "re-run with --allow-mcp" hint).
+   */
+  allowMcp?: boolean;
   followBranch?: boolean;
   /**
    * Route this function's human output to stderr (and silence scan-packages
@@ -1470,6 +1998,12 @@ export async function installPack(
 
     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) {
@@ -1497,6 +2031,22 @@ export async function installPack(
       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
@@ -1516,6 +2066,25 @@ export async function installPack(
     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)}/`