@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/pack-install.ts

@@ -1,2256 +0,0 @@
-/**
- * hq install <source> — content-pack installer (US-003, hq-core v12.0.0+)
- *
- * Source patterns and transports:
- *   @scope/name[@version]          → npm (default pin = latest, frozen on install)
- *   https://... | git@... | *.git  → git (SHA-pinned by default; --branch to follow)
- *   github:owner/repo[#...]        → git (sugar — expands to https://github.com/owner/repo.git)
- *   ./path | ../path | /path | file:... → local (path recorded as-is)
- *
- * Git fragment grammar (after '#'):
- *   '#<ref>'                → whole repo at ref (tag / branch / SHA)
- *   '#<subpath>'            → subdirectory of repo at default branch
- *   '#<subpath>@<ref>'      → subdirectory at ref
- * Fragment disambiguation: if the token after '#' contains '/' it's a subpath;
- * otherwise it's a ref. Subpath enables monorepo-hosted packs (e.g.
- * 'github:indigoai-us/hq#packages/hq-pack-gstack@abc1234') without a separate
- * registry or release tarball.
- *
- * Distinct from pkg-install.ts (entitlement-gated registry flow against the
- * proprietary HQ registry — that still runs for plain slugs). Spec:
- * knowledge/public/hq-core/package-yaml-spec.md.
- *
- * Flow:
- *   1. Classify source → transport
- *   2. Fetch payload to tmpdir (npm pack | git clone | rsync)
- *   3. Parse + validate package.yaml (10 checks from spec)
- *   4. Evaluate `conditional` predicate — skip if exits non-zero
- *   5. Confirm hooks if `contributes.hooks` non-empty (unless --allow-hooks)
- *   6. Move into core/packages/{name}/
- *   7. Run core/scripts/scan-packages.sh to wire contributions into host paths
- *
- * Installed packs are tracked by filesystem presence — there's no separate
- * registry file under the v12 layout. (`hq update <pack>` re-resolves source
- * from each pack's package.yaml; rationale lives in the layout-fix PR.)
- */
-
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import * as readline from 'readline';
-import { parseUserYaml } from '../utils/user-yaml-error.js';
-import {
-  createHash,
-  createPublicKey,
-  verify as cryptoVerify,
-  type KeyObject,
-} from 'node:crypto';
-import { execFileSync, spawnSync } from 'child_process';
-import { Command } from 'commander';
-import chalk from 'chalk';
-import semverSatisfies from 'semver/functions/satisfies.js';
-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, routeContribution, listInstalledPacks } from '../utils/pack-contributions.js';
-import { CONTRIBUTION_TABLE, payloadFor } from '../utils/contribution-table.js';
-import { safeExtractTarball } from './safe-extract.js';
-import { getCompanyUid, vaultApiFetchPublic } from '../utils/vault-api.js';
-import { ensureCognitoToken } from '../utils/cognito-session.js';
-import {
-  redactSecrets,
-  SECRET_REDACTION,
-  registerMcpServers,
-  McpManifestError,
-  type McpManifest,
-  type SecretResolver,
-} from './mcp-registration.js';
-import { listSecretCacheScopes } from '../utils/secrets-cache.js';
-import { loadRevealedSecrets } from './secrets.js';
-import type { PackManifest, PackContributeKey } from '../types.js';
-
-const PACK_UPDATE_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
-const PACK_UPDATE_FETCH_TIMEOUT_MS = 3_000;
-
-interface PackUpdateCacheEntry {
-  latest: string;
-  fetchedAt: number;
-}
-
-interface PackUpdateCacheFile {
-  entries: Record<string, PackUpdateCacheEntry>;
-}
-
-export interface ResolveLatestOptions {
-  forceRefresh?: boolean;
-  now?: number;
-  cacheTtlMs?: number;
-  fetchImpl?: typeof fetch;
-}
-
-const gitLsRemoteMemo = new Map<string, string>();
-
-function packUpdateCachePath(): string {
-  return path.join(os.homedir(), '.hq', 'pack-update-cache.json');
-}
-
-function readPackUpdateCache(): PackUpdateCacheFile {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(packUpdateCachePath(), 'utf-8')) as Partial<PackUpdateCacheFile>;
-    if (!parsed || typeof parsed !== 'object' || !parsed.entries || typeof parsed.entries !== 'object') {
-      return { entries: {} };
-    }
-    return { entries: parsed.entries as Record<string, PackUpdateCacheEntry> };
-  } catch {
-    return { entries: {} };
-  }
-}
-
-function writePackUpdateCache(cache: PackUpdateCacheFile): void {
-  try {
-    const file = packUpdateCachePath();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(cache));
-  } catch {
-    // best-effort; update checks must never fail because the cache is unwritable
-  }
-}
-
-function cachedLatest(cacheKey: string, opts: ResolveLatestOptions): string | undefined {
-  if (opts.forceRefresh) return undefined;
-  const entry = readPackUpdateCache().entries[cacheKey];
-  if (!entry || typeof entry.latest !== 'string' || typeof entry.fetchedAt !== 'number') return undefined;
-  const now = opts.now ?? Date.now();
-  const ttl = opts.cacheTtlMs ?? PACK_UPDATE_CACHE_TTL_MS;
-  return now - entry.fetchedAt <= ttl ? entry.latest : undefined;
-}
-
-function storeCachedLatest(cacheKey: string, latest: string, opts: ResolveLatestOptions): void {
-  const cache = readPackUpdateCache();
-  cache.entries[cacheKey] = { latest, fetchedAt: opts.now ?? Date.now() };
-  writePackUpdateCache(cache);
-}
-
-async function latestWithDiskCache(
-  cacheKey: string,
-  opts: ResolveLatestOptions,
-  refresh: () => Promise<string | undefined> | string | undefined,
-): Promise<string | undefined> {
-  const cached = cachedLatest(cacheKey, opts);
-  if (cached) return cached;
-  const latest = await refresh();
-  if (latest) storeCachedLatest(cacheKey, latest, opts);
-  return latest;
-}
-
-// ---------------------------------------------------------------------------
-// Source classification
-// ---------------------------------------------------------------------------
-
-export type Transport = 'npm' | 'git' | 'local' | 'marketplace';
-
-/** Prefix that routes a source through the HQ marketplace transport (US-006). */
-export const MARKETPLACE_PREFIX = 'marketplace:';
-
-export function classify(source: string): Transport {
-  // US-006: marketplace:<slug>[@version] is recognized BEFORE the legacy
-  // registry fallback and ahead of every other transport. The slug is resolved
-  // against the public listings API, the presigned tarball is downloaded,
-  // verified (US-021), and safe-extracted (US-020) into the existing local
-  // install + symlink-wiring path.
-  if (source.startsWith(MARKETPLACE_PREFIX)) return 'marketplace';
-  if (source.startsWith('@')) return 'npm';
-  if (
-    source.startsWith('http://') ||
-    source.startsWith('https://') ||
-    source.startsWith('git@') ||
-    source.startsWith('git://') ||
-    source.startsWith('github:') ||
-    source.endsWith('.git') ||
-    /\.git#/.test(source)
-  ) {
-    return 'git';
-  }
-  // A '#' fragment is only meaningful to git (ref / subpath). If we see one
-  // on a file: or path source, the caller means "clone this local git repo"
-  // — route to git. Local transport does not consume fragments.
-  if (source.includes('#')) {
-    return 'git';
-  }
-  if (
-    source.startsWith('./') ||
-    source.startsWith('../') ||
-    source.startsWith('/') ||
-    source.startsWith('file:')
-  ) {
-    return 'local';
-  }
-  // Fallback: bare slug — caller (dispatcher) routes those to legacy flow.
-  throw new Error(
-    `Cannot classify source "${source}" as pack (npm @scope/name, git URL, or path). ` +
-      `Bare slugs go through the registry (Cognito) flow.`
-  );
-}
-
-/**
- * Expand 'github:owner/repo' shorthand to a cloneable URL. Passes anything
- * else through unchanged. Separate from classify() so the transport-dispatch
- * stays readable.
- */
-function expandGithubShorthand(url: string): string {
-  if (!url.startsWith('github:')) return url;
-  const slug = url.slice('github:'.length);
-  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(slug)) {
-    throw new Error(
-      `github: shorthand must be 'github:owner/repo' (got 'github:${slug}')`
-    );
-  }
-  return `https://github.com/${slug}.git`;
-}
-
-/**
- * Parse a git source's '#<...>' fragment into { url, subpath, ref }.
- * Disambiguation: fragment containing '/' is a subpath (optionally with
- * '@<ref>' suffix); fragment without '/' is a ref.
- */
-export function parseGitFragment(source: string): {
-  url: string;
-  subpath?: string;
-  ref?: string;
-} {
-  const hashAt = source.indexOf('#');
-  if (hashAt < 0) return { url: source };
-  const url = source.slice(0, hashAt);
-  const frag = source.slice(hashAt + 1);
-  if (frag.includes('/')) {
-    // subpath[@ref]
-    const atAt = frag.lastIndexOf('@');
-    if (atAt > 0) {
-      return { url, subpath: frag.slice(0, atAt), ref: frag.slice(atAt + 1) };
-    }
-    return { url, subpath: frag };
-  }
-  return { url, ref: frag || undefined };
-}
-
-/**
- * sourceMatchesPackPattern — exported for the dispatcher in pkg-install.ts
- * so it can decide whether to route to the new content-pack handler or fall
- * back to the legacy registry flow.
- */
-export function sourceMatchesPackPattern(source: string): boolean {
-  try {
-    classify(source);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Transports
-// ---------------------------------------------------------------------------
-
-interface FetchResult {
-  payloadDir: string;     // where the extracted pack lives (caller mvs it)
-  resolvedSource: string; // e.g. '@scope/name@1.0.0' (version frozen) or URL#sha
-  resolvedSha?: string;   // git transport only
-}
-
-/**
- * Optional marketplace integrity metadata for a tarball-based install (US-021).
- * When present, `verifyArtifact` runs over the downloaded tarball bytes BEFORE
- * `safeExtractTarball` — a hash/signature mismatch aborts the install before
- * any byte is unpacked. US-006 populates this from the listing detail; the npm
- * fetch path also honors it so a registry-fetched tarball can be verified.
- */
-export interface ArtifactIntegrity {
-  expectedHash: string;
-  signature?: string;
-  publicKey?: string;
-  requireSignature?: boolean;
-}
-
-function fetchNpm(
-  source: string,
-  tmpDir: string,
-  integrity?: ArtifactIntegrity,
-): FetchResult {
-  // Use `npm pack` to grab the tarball without actually installing anything.
-  // Capture output to get the produced filename. Arguments are passed as an
-  // argv array — never interpolated into a shell string — so `source` cannot
-  // break out even if it contains metacharacters.
-  const out = execFileSync(
-    'npm',
-    ['pack', '--silent', '--pack-destination', tmpDir, source],
-    { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'inherit'] },
-  );
-  const tarball = out.trim().split('\n').filter(Boolean).pop();
-  if (!tarball) {
-    throw new Error(`npm pack produced no tarball for "${source}"`);
-  }
-  const tarballPath = path.join(tmpDir, tarball);
-  const extractDir = path.join(tmpDir, 'extracted');
-  // SECURITY (US-021): verify integrity + authenticity over the EXACT
-  // downloaded bytes BEFORE we extract. A hash/signature mismatch throws
-  // `ArtifactVerificationError` here, so a tampered artifact is never unpacked
-  // or wired. This MUST precede `safeExtractTarball` (US-020). Only runs when
-  // the caller supplied a pinned hash (i.e. a marketplace listing did); the
-  // plain `npm pack` path with no listing metadata is unaffected.
-  if (integrity) {
-    const tarballBytes = fs.readFileSync(tarballPath);
-    verifyArtifact({
-      tarballBytes,
-      expectedHash: integrity.expectedHash,
-      signature: integrity.signature,
-      publicKey: integrity.publicKey,
-      requireSignature: integrity.requireSignature,
-    });
-  }
-  // SECURITY (US-020): the tarball is untrusted. Extract through the hardened
-  // path — zip-slip / link-escape containment + decompression-bomb caps +
-  // staged-then-atomic commit with full rollback — instead of a blind
-  // `tar -xzf`. safeExtractTarball requires the destination not to pre-exist,
-  // so we do NOT mkdir extractDir first; it is created atomically on success.
-  safeExtractTarball(tarballPath, extractDir);
-  // npm tarballs unpack into ./package/
-  const payloadDir = path.join(extractDir, 'package');
-  if (!fs.existsSync(payloadDir)) {
-    throw new Error(`npm tarball layout unexpected — no "package/" in ${tarballPath}`);
-  }
-  // Freeze version from the resolved tarball filename when caller passed e.g.
-  // '@scope/name' (no @version) — fall back to the source string.
-  // npm pack writes the filename as scope-name-version.tgz (no leading @).
-  const m = /([0-9]+\.[0-9]+\.[0-9]+[^.]*)\.tgz$/.exec(tarball);
-  const resolvedSource = m ? `${stripVersion(source)}@${m[1]}` : source;
-  return { payloadDir, resolvedSource };
-}
-
-function stripVersion(src: string): string {
-  // '@scope/name@1.0.0' → '@scope/name'
-  const at = src.lastIndexOf('@');
-  if (at > 0) return src.slice(0, at);
-  return src;
-}
-
-// ---------------------------------------------------------------------------
-// Marketplace transport (US-006)
-//
-// `marketplace:<slug>[@version]` resolves a slug against the PUBLIC listings
-// API (US-005, NONE-auth), downloads the presigned tarball, verifies it
-// (US-021) BEFORE extraction, and feeds it into the existing safe-extract +
-// validate + symlink-wire path. The legacy registry/npm/git/local transports
-// are untouched.
-// ---------------------------------------------------------------------------
-
-/** Parsed `marketplace:<slug>[@version]` source. */
-export function parseMarketplaceSource(source: string): {
-  slug: string;
-  version?: string;
-} {
-  if (!source.startsWith(MARKETPLACE_PREFIX)) {
-    throw new Error(`Not a marketplace source: "${source}"`);
-  }
-  const rest = source.slice(MARKETPLACE_PREFIX.length).trim();
-  if (!rest) {
-    throw new Error('marketplace: source requires a slug (marketplace:<slug>[@version]).');
-  }
-  // Split on the LAST '@' so a slug never legitimately contains one, but be
-  // defensive: only treat the suffix as a version if there's a non-empty slug.
-  const at = rest.lastIndexOf('@');
-  if (at > 0) {
-    return { slug: rest.slice(0, at), version: rest.slice(at + 1) || undefined };
-  }
-  return { slug: rest };
-}
-
-/**
- * A resolved marketplace listing detail — the public `GET /v1/listings/{id}`
- * shape (US-005) reduced to the fields the installer needs. The presigned
- * `downloadUrl` is short-lived; `listingId` lets us re-resolve a fresh one if
- * it expires mid-download.
- */
-export interface MarketplaceListing {
-  listingId: string;
-  slug: string;
-  version?: string;
-  /** Short-lived presigned S3 URL for the tarball. */
-  downloadUrl: string;
-  /** Lowercase-hex sha256 the listing pinned + approval is bound to (US-021). */
-  contentHash: string;
-  /** Hash algorithm the server reported (e.g. `sha256`), when present. */
-  contentHashAlg?: string;
-  /** Base64 Ed25519 signature over the contentHash (optional during key-defer). */
-  signature?: string;
-  /** Identifier of the signing key the server used, when present. */
-  signingKeyId?: string;
-  /** Platform public key (PEM/SPKI) to verify the signature against. */
-  publicKey?: string;
-}
-
-/**
- * Network seams for the marketplace transport, dependency-injected so unit
- * tests can mock resolve + download without real HTTP/S3. Production wiring
- * lives in `defaultMarketplaceDeps`.
- */
-export interface MarketplaceDeps {
-  /**
-   * Resolve `slug[@version]` to a listing detail (id + presigned URL + the
-   * approved hash/signature/publicKey). Throws if no approved listing matches.
-   */
-  resolveListing: (slug: string, version?: string) => Promise<MarketplaceListing>;
-  /** Re-fetch the listing detail by id to mint a FRESH presigned URL. */
-  refreshListing: (listingId: string) => Promise<MarketplaceListing>;
-  /** Download the tarball bytes from a presigned URL. Returns null on 403/expired. */
-  download: (url: string) => Promise<Uint8Array | { expired: true }>;
-}
-
-/** True when a download result signals an expired/forbidden presigned URL. */
-function isExpired(r: Uint8Array | { expired: true }): r is { expired: true } {
-  return !(r instanceof Uint8Array) && (r as { expired?: true }).expired === true;
-}
-
-interface RawListingSummary {
-  listingId?: string;
-  id?: string;
-  slug?: string;
-  version?: string;
-  latestVersion?: string;
-  status?: string;
-}
-
-interface RawListingDetailFields extends RawListingSummary {
-  downloadUrl?: string;
-  url?: string;
-  contentHash?: string;
-  contentHashAlg?: string;
-  sha256?: string;
-  signature?: string;
-  signingKeyId?: string;
-  publicKey?: string;
-}
-
-/**
- * `GET /v1/listings/{id}` returns the listing WRAPPED in an envelope
- * (`{ listing: { id, downloadUrl, contentHash, ... } }`). Older/back-compat
- * responses returned the listing fields at the top level, so we accept both.
- */
-interface RawListingDetail extends RawListingDetailFields {
-  listing?: RawListingDetailFields;
-}
-
-/** Map a raw `GET /v1/listings/{id}` body into a MarketplaceListing. */
-export function toMarketplaceListing(raw: RawListingDetail): MarketplaceListing {
-  // Unwrap the `{ listing: {...} }` envelope when present; fall back to the
-  // top level for the legacy flat shape (backwards-compat).
-  const detail: RawListingDetailFields =
-    raw.listing && typeof raw.listing === 'object' ? raw.listing : raw;
-  // The detail uses `id`; the legacy flat shape may use `listingId`.
-  const listingId = detail.id ?? detail.listingId;
-  const downloadUrl = detail.downloadUrl ?? detail.url;
-  const contentHash = detail.contentHash ?? detail.sha256;
-  if (!listingId) throw new Error('Listing detail missing an id.');
-  if (!downloadUrl) {
-    throw new Error(`Listing ${listingId} has no download URL — it may not be approved yet.`);
-  }
-  if (!contentHash) {
-    throw new Error(
-      `Listing ${listingId} has no content hash — refusing to install an unverifiable artifact.`,
-    );
-  }
-  return {
-    listingId,
-    slug: detail.slug ?? '',
-    version: detail.version ?? detail.latestVersion,
-    downloadUrl,
-    contentHash,
-    contentHashAlg: detail.contentHashAlg,
-    signature: detail.signature,
-    signingKeyId: detail.signingKeyId,
-    publicKey: detail.publicKey,
-  };
-}
-
-/** Default production marketplace deps — public listings API + presigned S3. */
-export function defaultMarketplaceDeps(): MarketplaceDeps {
-  const fetchDetail = async (listingId: string): Promise<MarketplaceListing> => {
-    const res = await vaultApiFetchPublic({
-      path: `/v1/listings/${encodeURIComponent(listingId)}`,
-    });
-    if (!res.ok) {
-      throw new Error(
-        `Failed to resolve listing ${listingId} (HTTP ${res.status}). The pack may be unavailable or unapproved.`,
-      );
-    }
-    const body = (await res.json().catch(() => ({}))) as RawListingDetail;
-    return toMarketplaceListing(body);
-  };
-  return {
-    resolveListing: async (slug, version) => {
-      // Search by slug (public). The API returns approved listings only.
-      //
-      // BUGFIX: the browse handler historically IGNORED `?slug=` and only
-      // honored `?q=` (fuzzy), so `?slug=tdd` returned ALL approved listings
-      // newest-first — and blindly taking `listings[0]` then installed the
-      // newest pack, not the requested slug (e.g. `marketplace:tdd` installed
-      // hq-pack-review). We now (a) query with BOTH `slug` (exact, server-side
-      // filter being added in parallel) AND `q` (fuzzy fallback) so the right
-      // results come back whichever param the server honors, and (b) NEVER take
-      // `listings[0]` — we exact-match `l.slug === slug` among the results and
-      // throw a clear error if none matches, rather than installing the wrong
-      // pack.
-      const query: Record<string, string> = { slug, q: slug };
-      if (version) query.version = version;
-      const res = await vaultApiFetchPublic({
-        path: '/v1/listings',
-        query,
-      });
-      if (!res.ok) {
-        throw new Error(
-          `Failed to search marketplace for "${slug}" (HTTP ${res.status}).`,
-        );
-      }
-      const body = (await res.json().catch(() => ({}))) as {
-        listings?: RawListingSummary[];
-      };
-      const listings = body.listings ?? [];
-      // Only consider listings whose slug EXACTLY matches the request — the
-      // fuzzy `q` search (and a slug-ignoring browse handler) can return
-      // unrelated packs, so an exact-slug filter is the safety floor.
-      const exact = listings.filter((l) => l.slug === slug);
-      let match: RawListingSummary | undefined;
-      if (version) {
-        // Pinned `marketplace:<slug>@<version>` → require an exact version too.
-        match = exact.find((l) => (l.version ?? l.latestVersion) === version);
-      } else {
-        // No pin → newest exact-slug match. The feed is newest-first, so the
-        // first exact-slug entry is the newest version of that slug.
-        match = exact[0];
-      }
-      if (!match) {
-        throw new Error(
-          `No marketplace listing found for slug "${slug}"${version ? `@${version}` : ''}.`,
-        );
-      }
-      const id = match.listingId ?? match.id;
-      if (!id) throw new Error(`Listing for "${slug}" has no id.`);
-      // The summary may omit the presigned URL; always fetch detail to mint it.
-      return fetchDetail(id);
-    },
-    refreshListing: fetchDetail,
-    download: async (url) => {
-      const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
-      if (response.status === 403) return { expired: true };
-      if (!response.ok) {
-        throw new Error(`Tarball download failed (HTTP ${response.status}).`);
-      }
-      return new Uint8Array(await response.arrayBuffer());
-    },
-  };
-}
-
-/**
- * Fetch + verify + safe-extract a marketplace pack. Mirrors `fetchNpm`'s
- * contract (returns a payloadDir the caller mvs into core/packages/), but
- * resolves the tarball from the marketplace and ALWAYS verifies it against the
- * listing's approved hash/signature BEFORE extraction (US-021 → US-020).
- *
- * @param requireSignature production posture once signing keys exist; during
- *        the key-deferral window callers pass false (hash still always checked).
- */
-export async function fetchMarketplace(
-  source: string,
-  tmpDir: string,
-  deps: MarketplaceDeps,
-  opts: { requireSignature?: boolean } = {},
-): Promise<FetchResult> {
-  const { slug, version } = parseMarketplaceSource(source);
-  let listing = await deps.resolveListing(slug, version);
-
-  // Download with a single expired-URL retry: a presigned URL can expire
-  // between resolve and download, surfacing as a raw S3 403. We re-resolve the
-  // detail by id to mint a fresh URL and retry ONCE rather than leaking the 403.
-  let bytes = await deps.download(listing.downloadUrl);
-  if (isExpired(bytes)) {
-    listing = await deps.refreshListing(listing.listingId);
-    bytes = await deps.download(listing.downloadUrl);
-    if (isExpired(bytes)) {
-      throw new Error(
-        `Marketplace download URL for "${slug}" expired and re-resolving did not help. ` +
-          `Try again in a moment.`,
-      );
-    }
-  }
-  const tarballBytes = bytes as Uint8Array;
-
-  // SECURITY (US-021): verify integrity (+ authenticity) over the EXACT
-  // downloaded bytes BEFORE extraction. A hash/signature mismatch throws
-  // `ArtifactVerificationError` and nothing is unpacked or wired. The hash is
-  // ALWAYS verified when present; signature is enforced when requireSignature.
-  verifyArtifact({
-    tarballBytes,
-    expectedHash: listing.contentHash,
-    signature: listing.signature,
-    publicKey: listing.publicKey,
-    requireSignature: opts.requireSignature ?? false,
-  });
-
-  // Write to a tmp tarball and run it through the SAME hardened extractor
-  // (US-020) as every other tarball transport.
-  const tarballPath = path.join(tmpDir, 'marketplace.tar.gz');
-  fs.writeFileSync(tarballPath, tarballBytes);
-  const extractDir = path.join(tmpDir, 'extracted');
-  safeExtractTarball(tarballPath, extractDir);
-
-  // Marketplace tarballs are packed with `tar -C payloadDir .` (publish.ts), so
-  // the manifest + contributes dirs are at the archive root — no `package/`
-  // wrapper to descend into.
-  const payloadDir = extractDir;
-  if (!fs.existsSync(path.join(payloadDir, 'package.yaml'))) {
-    throw new Error(
-      `Marketplace tarball for "${slug}" has no package.yaml at its root.`,
-    );
-  }
-
-  // Record the marketplace source for re-install + `hq packs update`. We stamp
-  // the resolved version so a later `update` can detect a newer listing.
-  const resolvedSource = listing.version
-    ? `${MARKETPLACE_PREFIX}${slug}@${listing.version}`
-    : `${MARKETPLACE_PREFIX}${slug}`;
-  return { payloadDir, resolvedSource };
-}
-
-function fetchGit(
-  source: string,
-  tmpDir: string,
-  followBranch: boolean
-): FetchResult {
-  const parsed = parseGitFragment(source);
-  const url = expandGithubShorthand(parsed.url);
-  const { subpath, ref } = parsed;
-
-  // Defensive: subpath must not escape the clone root.
-  if (subpath) {
-    if (
-      subpath.startsWith('/') ||
-      subpath.split('/').some((seg) => seg === '..' || seg === '')
-    ) {
-      throw new Error(
-        `Invalid subpath "${subpath}" — must be a relative path within the repo.`
-      );
-    }
-  }
-
-  // Defensive: reject refs that would be ambiguous or shell-dangerous.
-  // `git` itself would tolerate most of these, but refusing them early avoids
-  // having to reason about quoting later.
-  if (ref && /[\s;&|`$<>(){}\\]/.test(ref)) {
-    throw new Error(`Invalid ref "${ref}" — contains disallowed characters.`);
-  }
-
-  const cloneDir = path.join(tmpDir, 'clone');
-  // Disambiguate ref=branch-or-tag vs. ref=SHA authoritatively via `git
-  // ls-remote`. Hex-shaped branch names (e.g. `deadbeef`) previously got
-  // silently downgraded to the "no --branch" path by a heuristic regex;
-  // that is now fixed. Arguments are passed as argv; no shell.
-  const refIsNamedRef = !!ref && isNamedRef(url, ref);
-  const cloneArgs = ['clone', '--depth', '1'];
-  if (refIsNamedRef) cloneArgs.push('--branch', ref);
-  cloneArgs.push(url, cloneDir);
-  execFileSync('git', cloneArgs, { stdio: 'inherit' });
-  if (ref && !refIsNamedRef) {
-    // SHA (or something ls-remote didn't recognize as a ref). Try a direct
-    // checkout first — works if the SHA happens to be HEAD of the default
-    // branch — otherwise unshallow and retry.
-    try {
-      execFileSync('git', ['-C', cloneDir, 'checkout', ref], {
-        stdio: 'inherit',
-      });
-    } catch {
-      execFileSync('git', ['-C', cloneDir, 'fetch', '--unshallow', 'origin'], {
-        stdio: 'inherit',
-      });
-      execFileSync('git', ['-C', cloneDir, 'checkout', ref], {
-        stdio: 'inherit',
-      });
-    }
-  }
-  const resolvedSha = execFileSync(
-    'git',
-    ['-C', cloneDir, 'rev-parse', 'HEAD'],
-    { encoding: 'utf-8' },
-  ).trim();
-
-  // If a subpath is specified, the payload is only that subdirectory.
-  let payloadDir = cloneDir;
-  if (subpath) {
-    const subAbs = path.join(cloneDir, subpath);
-    if (!fs.existsSync(subAbs) || !fs.statSync(subAbs).isDirectory()) {
-      throw new Error(
-        `subpath "${subpath}" not found in ${url}@${resolvedSha.slice(0, 7)}`
-      );
-    }
-    payloadDir = path.join(tmpDir, 'payload');
-    fs.mkdirSync(payloadDir, { recursive: true });
-    rsyncDir(subAbs, payloadDir);
-  } else {
-    // Drop .git — the pack should be file content, not a nested repo
-    fs.rmSync(path.join(cloneDir, '.git'), { recursive: true, force: true });
-  }
-
-  // Recorded source shape:
-  //   with subpath:    url#subpath@<sha|ref>
-  //   without subpath: url#<sha|ref>
-  // --branch opt-in follows the ref by name; default SHA-pins.
-  const recordedRef = followBranch && ref ? ref : resolvedSha;
-  const resolvedSource = subpath
-    ? `${parsed.url}#${subpath}@${recordedRef}`
-    : `${parsed.url}#${recordedRef}`;
-  return { payloadDir, resolvedSource, resolvedSha };
-}
-
-function fetchLocal(source: string, tmpDir: string): FetchResult {
-  const clean = source.startsWith('file:') ? source.slice('file:'.length) : source;
-  const abs = path.resolve(process.cwd(), clean);
-  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
-    throw new Error(`Local path not a directory: ${abs}`);
-  }
-  const payloadDir = path.join(tmpDir, 'local');
-  fs.mkdirSync(payloadDir, { recursive: true });
-  rsyncDir(abs, payloadDir);
-  return { payloadDir, resolvedSource: clean };
-}
-
-/**
- * Invoke rsync with an argv array (no shell). Trailing slashes on the source
- * path are preserved by passing the exact strings through execFileSync.
- */
-function rsyncDir(src: string, dest: string): void {
-  const srcSlashed = src.endsWith('/') ? src : `${src}/`;
-  const destSlashed = dest.endsWith('/') ? dest : `${dest}/`;
-  execFileSync(
-    'rsync',
-    [
-      '-a',
-      '--exclude=.git',
-      '--exclude=node_modules',
-      '--exclude=.DS_Store',
-      srcSlashed,
-      destSlashed,
-    ],
-    { stdio: 'inherit' },
-  );
-}
-
-/**
- * Ask git whether <ref> resolves as a named branch or tag on <url>. Returns
- * true only when ls-remote prints a matching refs/heads/<ref> or
- * refs/tags/<ref>. Anything else (including hex-shaped branch names that
- * happen to be missing, network failures, or explicit SHAs) falls through to
- * the SHA-checkout path. Uses argv — no shell.
- */
-function isNamedRef(url: string, ref: string): boolean {
-  try {
-    const out = gitLsRemote(['--heads', '--tags', url, ref]);
-    return out.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-
-function gitLsRemote(args: string[]): string {
-  const key = args.join('\0');
-  const cached = gitLsRemoteMemo.get(key);
-  if (cached !== undefined) return cached;
-  const out = execFileSync(
-    'git',
-    ['ls-remote', ...args],
-    { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
-  );
-  gitLsRemoteMemo.set(key, out);
-  return out;
-}
-
-async function fetchLatestNpmVersion(pkg: string, opts: ResolveLatestOptions): Promise<string | undefined> {
-  const fetchImpl = opts.fetchImpl ?? fetch;
-  const res = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`, {
-    headers: { Accept: 'application/json' },
-    signal: AbortSignal.timeout(PACK_UPDATE_FETCH_TIMEOUT_MS),
-  });
-  if (!res.ok) throw new Error(`registry returned ${res.status}`);
-  const body = (await res.json()) as { version?: unknown };
-  return typeof body.version === 'string' ? body.version : undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Update-availability probe (no install) — used by `hq packs update --check-only`
-// ---------------------------------------------------------------------------
-
-export interface LatestResult {
-  transport: Transport;
-  /** Identifier of the currently-installed pack (sha for git, version for npm). */
-  current?: string;
-  /** Latest available identifier from the remote. */
-  latest?: string;
-  /** true/false when a comparison was possible; null when undeterminable (local). */
-  updateAvailable: boolean | null;
-  error?: string;
-}
-
-/** Extract the ref (sha or named ref) recorded in a stamped git source. */
-function gitRefFromSource(source: string): string | undefined {
-  const { subpath, ref } = parseGitFragment(source);
-  // For 'url#subpath@ref' parseGitFragment returns ref; for 'url#ref' likewise.
-  // A bare 'url#subpath' (no @ref) has no ref.
-  void subpath;
-  return ref;
-}
-
-function isFullGitSha(ref: string): boolean {
-  return /^[0-9a-f]{40}$/i.test(ref);
-}
-
-/**
- * Probe whether a newer version of an already-installed pack is available,
- * WITHOUT fetching or installing. Reuses the same git/npm primitives as the
- * install path. Never throws — network/parse failures return
- * `{ updateAvailable: null, error }` so callers (the menubar) stay resilient.
- *
- * @param source         the stamped `source:` from the installed package.yaml
- * @param installedVersion the installed pack's manifest `version` (npm compare)
- */
-export async function resolveLatest(
-  source: string,
-  installedVersion?: string,
-  opts: ResolveLatestOptions = {},
-): Promise<LatestResult> {
-  let transport: Transport;
-  try {
-    transport = classify(source);
-  } catch (e) {
-    return { transport: 'local', updateAvailable: null, error: (e as Error).message };
-  }
-
-  if (transport === 'local') {
-    return { transport, updateAvailable: null, error: 'local source — re-run to re-sync' };
-  }
-
-  if (transport === 'marketplace') {
-    // The marketplace probe needs an async network call (listings API), which
-    // this synchronous helper cannot make. Callers that want the marketplace
-    // update check use the async `resolveLatestMarketplace`; here we report the
-    // installed version but leave availability undeterminable (null) so the
-    // sync menubar `--check-updates` path is not regressed.
-    const { version } = parseMarketplaceSource(source);
-    return {
-      transport,
-      current: installedVersion ?? version,
-      updateAvailable: null,
-      error: 'marketplace source — use async update check',
-    };
-  }
-
-  if (transport === 'npm') {
-    const pkg = stripVersion(source);
-    const current =
-      installedVersion ?? (source.lastIndexOf('@') > 0 ? source.slice(source.lastIndexOf('@') + 1) : undefined);
-    try {
-      const latest = await latestWithDiskCache(`npm:${pkg}`, opts, () =>
-        fetchLatestNpmVersion(pkg, opts),
-      );
-      const updateAvailable =
-        current && latest ? semverGt(latest, current) : null;
-      return { transport, current, latest, updateAvailable };
-    } catch (e) {
-      return { transport, current, updateAvailable: null, error: `npm registry check failed: ${(e as Error).message}` };
-    }
-  }
-
-  // git
-  const parsed = parseGitFragment(source);
-  let url: string;
-  try {
-    url = expandGithubShorthand(parsed.url);
-  } catch (e) {
-    return { transport, updateAvailable: null, error: (e as Error).message };
-  }
-  const current = gitRefFromSource(source);
-  // If install followed a named ref (branch/tag), compare that ref's tip;
-  // otherwise (default SHA-pin) compare the default branch HEAD.
-  const refArg = current && !isFullGitSha(current) && isNamedRef(url, current) ? current : 'HEAD';
-  try {
-    const latest = await latestWithDiskCache(`git:${url}#${refArg}`, opts, () => {
-      const out = gitLsRemote([url, refArg]).trim();
-      return out.split(/\s+/)[0] || undefined;
-    });
-    const updateAvailable =
-      current && latest ? !latest.startsWith(current) && !current.startsWith(latest) : null;
-    return { transport, current, latest, updateAvailable };
-  } catch (e) {
-    return { transport, current, updateAvailable: null, error: `git ls-remote failed: ${(e as Error).message}` };
-  }
-}
-
-/**
- * Async marketplace update probe (US-006): resolve the slug's latest approved
- * listing version and compare it to the installed version. Reuses the same
- * `MarketplaceDeps.resolveListing` seam as the install path (resolving with NO
- * version pin returns the latest listing). Never throws — network/parse
- * failures return `{ updateAvailable: null, error }` so `hq packs update`
- * stays resilient.
- *
- * @param source           the stamped `marketplace:<slug>[@version]` source
- * @param installedVersion the installed pack's manifest version (semver compare)
- * @param deps             injected for tests; defaults to the public API
- */
-export async function resolveLatestMarketplace(
-  source: string,
-  installedVersion?: string,
-  deps?: MarketplaceDeps,
-): Promise<LatestResult> {
-  let slug: string;
-  let pinned: string | undefined;
-  try {
-    ({ slug, version: pinned } = parseMarketplaceSource(source));
-  } catch (e) {
-    return { transport: 'marketplace', updateAvailable: null, error: (e as Error).message };
-  }
-  const current = installedVersion ?? pinned;
-  try {
-    const d = deps ?? defaultMarketplaceDeps();
-    // No version pin → latest approved listing.
-    const listing = await d.resolveListing(slug);
-    const latest = listing.version;
-    let updateAvailable: boolean | null = null;
-    if (current && latest) {
-      // Prefer semver compare; fall back to inequality if either side isn't
-      // valid semver (so a non-semver listing version still flags a change).
-      updateAvailable =
-        semverValid(latest) && semverValid(current)
-          ? semverGt(latest, current)
-          : latest !== current;
-    }
-    return { transport: 'marketplace', current, latest, updateAvailable };
-  } catch (e) {
-    return {
-      transport: 'marketplace',
-      current,
-      updateAvailable: null,
-      error: `marketplace check failed: ${(e as Error).message}`,
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Marketplace artifact verification (US-021, INSTALL side)
-//
-// Guarantees the bytes we install are EXACTLY the bytes a moderator approved:
-//   1. recompute sha256 over the downloaded tarball bytes and compare it to the
-//      hash the listing pinned at publish (and approval bound to);
-//   2. verify the platform Ed25519 signature over that hash against a
-//      distributable PUBLIC key.
-//
-// SHARED CONTRACT (must match hq-pro `src/listings/signing.ts`):
-//   • CANONICAL BYTES = the gzipped tarball object EXACTLY as uploaded to S3
-//                       (i.e. exactly the bytes we downloaded — no transform).
-//   • contentHash     = sha256(canonical bytes), lowercase hex.
-//   • signature       = Ed25519 over the UTF-8 bytes of the lowercase-hex
-//                       contentHash, base64-encoded.
-//
-// This runs BEFORE safe-extract (US-020): a mismatch must abort the install
-// before any bytes are unpacked or wired. US-006 wires the marketplace
-// transport that surfaces the listing's {hash, signature, publicKey}; this
-// function is the reusable verifier it calls.
-// ---------------------------------------------------------------------------
-
-/** Thrown when a downloaded artifact fails hash or signature verification. */
-export class ArtifactVerificationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'ArtifactVerificationError';
-  }
-}
-
-/** Hash algorithm for the content hash — pinned to sha256 (matches publish). */
-export const ARTIFACT_HASH_ALG = 'sha256' as const;
-
-export interface VerifyArtifactInput {
-  /** The downloaded gzipped tarball bytes (canonical bytes). */
-  tarballBytes: Uint8Array;
-  /** Lowercase-hex sha256 the listing pinned at publish (approval bound to it). */
-  expectedHash: string;
-  /**
-   * Base64 Ed25519 signature over the lowercase-hex `expectedHash`. Optional:
-   * when the listing carries no signature (e.g. published before signing-key
-   * provisioning), hash verification still runs but signature verification is
-   * skipped UNLESS `requireSignature` is set.
-   */
-  signature?: string;
-  /**
-   * The platform PUBLIC key (Ed25519) as a PEM/SPKI string or a pre-parsed
-   * KeyObject. Required to verify a signature. The public key is distributable
-   * (embedded in / fetched by the installer).
-   */
-  publicKey?: string | KeyObject;
-  /**
-   * When true, a missing signature OR missing public key is a hard failure
-   * (production posture once signing keys are provisioned). Default false so an
-   * unsigned listing still hash-verifies during the deferred-key window.
-   */
-  requireSignature?: boolean;
-}
-
-/** Lowercase-hex sha256 of the given bytes — the install-side content hash. */
-export function computeArtifactHash(tarballBytes: Uint8Array): string {
-  return createHash(ARTIFACT_HASH_ALG).update(tarballBytes).digest('hex');
-}
-
-/**
- * Verify a downloaded marketplace artifact's integrity (hash) and authenticity
- * (signature). Throws `ArtifactVerificationError` on ANY mismatch — the caller
- * MUST let it propagate so the install aborts before extraction.
- *
- * Constant-time-ish hash comparison: hashes are fixed-length lowercase hex, and
- * the early-exit risk is negligible (the hash is public), but we still compare
- * full strings rather than prefixes.
- */
-export function verifyArtifact(input: VerifyArtifactInput): void {
-  const {
-    tarballBytes,
-    expectedHash,
-    signature,
-    publicKey,
-    requireSignature = false,
-  } = input;
-
-  if (!expectedHash || !/^[0-9a-f]{64}$/.test(expectedHash)) {
-    throw new ArtifactVerificationError(
-      `Refusing to install: listing did not provide a valid ${ARTIFACT_HASH_ALG} content hash.`,
-    );
-  }
-
-  // 1. Integrity — recompute the hash over the EXACT downloaded bytes.
-  const actualHash = computeArtifactHash(tarballBytes);
-  if (actualHash !== expectedHash) {
-    throw new ArtifactVerificationError(
-      `Artifact hash mismatch — refusing to install. ` +
-        `expected ${ARTIFACT_HASH_ALG}=${expectedHash}, got ${actualHash}. ` +
-        `The downloaded bytes are NOT the bytes that were approved.`,
-    );
-  }
-
-  // 2. Authenticity — verify the Ed25519 signature over the hash.
-  if (!signature || !publicKey) {
-    if (requireSignature) {
-      throw new ArtifactVerificationError(
-        signature
-          ? 'Artifact signature present but no public key available to verify it — refusing to install.'
-          : 'Artifact is unsigned and a signature is required — refusing to install.',
-      );
-    }
-    // Deferred-key window: hash verified, no signature to check. Caller opted to
-    // allow unsigned (requireSignature=false).
-    return;
-  }
-
-  let key: KeyObject;
-  try {
-    key = typeof publicKey === 'string' ? createPublicKey(publicKey) : publicKey;
-  } catch (e) {
-    throw new ArtifactVerificationError(
-      `Invalid artifact public key — refusing to install: ${(e as Error).message}`,
-    );
-  }
-
-  let ok = false;
-  try {
-    // Ed25519: digest algorithm is null (the scheme hashes internally). The
-    // signed payload is the UTF-8 bytes of the lowercase-hex hash — identical to
-    // what hq-pro signed at publish.
-    ok = cryptoVerify(
-      null,
-      Buffer.from(expectedHash, 'utf-8'),
-      key,
-      Buffer.from(signature, 'base64'),
-    );
-  } catch (e) {
-    throw new ArtifactVerificationError(
-      `Artifact signature verification errored — refusing to install: ${(e as Error).message}`,
-    );
-  }
-  if (!ok) {
-    throw new ArtifactVerificationError(
-      'Artifact signature is invalid — refusing to install. ' +
-        'The artifact was not signed by the platform key (possible tampering).',
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 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)
-// ---------------------------------------------------------------------------
-
-export function validateManifest(
-  payloadDir: string,
-  hqVersion: string | null
-): PackManifest {
-  // 1. parse
-  const manifestPath = path.join(payloadDir, 'package.yaml');
-  if (!fs.existsSync(manifestPath)) {
-    throw new Error('package.yaml missing from pack payload');
-  }
-  let parsed: unknown;
-  try {
-    parsed = parseUserYaml(fs.readFileSync(manifestPath, 'utf-8'), manifestPath);
-  } catch (e) {
-    if (e instanceof Error && (e as { expected?: unknown }).expected === true) {
-      throw e;
-    }
-    throw new Error(`package.yaml invalid YAML: ${(e as Error).message}`);
-  }
-  const m = parsed as Partial<PackManifest> & Record<string, unknown>;
-  if (!m || typeof m !== 'object') {
-    throw new Error('package.yaml must be a YAML mapping');
-  }
-  // 2. name
-  if (!m.name || !/^hq-pack-[a-z0-9][a-z0-9-]*$/.test(m.name)) {
-    throw new Error(`Invalid pack name "${m.name}" — must match ^hq-pack-[a-z0-9][a-z0-9-]*$`);
-  }
-  // 3. version
-  if (!m.version || !semverValid(m.version)) {
-    throw new Error(`Invalid version "${m.version}" — must be valid semver`);
-  }
-  // 4. publisher
-  if (!m.publisher || !/^@[a-z0-9][a-z0-9-]*$/i.test(m.publisher)) {
-    throw new Error(`Invalid publisher "${m.publisher}" — must be a valid npm scope starting with @`);
-  }
-  // 5. access
-  if (m.access !== 'public' && m.access !== 'private') {
-    throw new Error(`access must be "public" or "private" (got "${m.access}")`);
-  }
-  // 6. requires.hqCore
-  const range = m.requires?.hqCore;
-  if (!range || !semverValidRange(range)) {
-    throw new Error(`requires.hqCore must be a valid semver range (got "${range}")`);
-  }
-  // `includePrerelease` so a prerelease host version (e.g. `15.0.9-beta.1`)
-  // satisfies a plain range like `>=14.2.0`. By default node-semver excludes
-  // prereleases from range matching, which would wrongly reject every dogfooding
-  // beta/rc HQ build from installing packs. A genuinely-too-old host (e.g.
-  // `13.0.0`) still fails the range.
-  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 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(
-    (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).
-  // 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 = 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.
-  // Absent → fine (legacy packs). Present → must be well-shaped so a malformed
-  // attribution can't masquerade as a valid one.
-  if (m.author !== undefined) {
-    const a = m.author as unknown as Record<string, unknown>;
-    if (!a || typeof a !== 'object' || Array.isArray(a)) {
-      throw new Error('author must be a mapping with uid, handle, displayName');
-    }
-    for (const field of ['uid', 'handle', 'displayName'] as const) {
-      if (typeof a[field] !== 'string' || (a[field] as string).trim() === '') {
-        throw new Error(`author.${field} must be a non-empty string`);
-      }
-    }
-  }
-  if (m.capabilities !== undefined) {
-    if (
-      !Array.isArray(m.capabilities) ||
-      !m.capabilities.every((c) => typeof c === 'string')
-    ) {
-      throw new Error('capabilities must be a list of strings');
-    }
-  }
-  // initialization (US-004) — OPTIONAL and backwards-compatible. Absent → fine
-  // (legacy packs). Present → the `entrypoint` is REQUIRED and MUST resolve to a
-  // declared `contributes.skills` or `contributes.commands` entry (this is the
-  // content-pack system, so entries are named under `contributes.*` — NOT the
-  // registry `exposes.*` system). The post-install initialization prompt is
-  // rendered/moderated in a later story; here we only validate shape so a
-  // malformed block can't slip through to install.
-  if (m.initialization !== undefined) {
-    const init = m.initialization as unknown;
-    if (!init || typeof init !== 'object' || Array.isArray(init)) {
-      throw new Error('initialization must be a mapping with an entrypoint');
-    }
-    const initObj = init as Record<string, unknown>;
-    const entrypoint = initObj.entrypoint;
-    if (typeof entrypoint !== 'string' || entrypoint.trim() === '') {
-      throw new Error(
-        'initialization.entrypoint is required and must be a non-empty string',
-      );
-    }
-    // Resolve the entrypoint against declared skills/commands. Normalize a
-    // leading slash on BOTH sides so `/email-assistant` matches a contributes
-    // entry named `email-assistant` and vice-versa.
-    const stripSlash = (s: string): string => (s.startsWith('/') ? s.slice(1) : s);
-    const target = stripSlash(entrypoint.trim());
-    const declared = [
-      ...(contributes.skills ?? []),
-      ...(contributes.commands ?? []),
-    ];
-    const resolves = declared.some((d) => stripSlash(d) === target);
-    if (!resolves) {
-      throw new Error(
-        `initialization.entrypoint "${entrypoint}" does not resolve to a declared ` +
-          `contributes.skills or contributes.commands entry. ` +
-          `Valid entries: ${declared.length ? declared.join(', ') : '(none declared)'}`,
-      );
-    }
-    // initialization.prompt — OPTIONAL. When present it must be a string ≤ 2000
-    // chars. (Rendering/moderation is a later story; we only validate type/length.)
-    if (initObj.prompt !== undefined) {
-      if (typeof initObj.prompt !== 'string') {
-        throw new Error('initialization.prompt must be a string');
-      }
-      if (initObj.prompt.length > 2000) {
-        throw new Error(
-          `initialization.prompt must be ≤ 2000 characters (got ${initObj.prompt.length})`,
-        );
-      }
-    }
-  }
-  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)
-// ---------------------------------------------------------------------------
-
-/**
- * Derive the safe, auto-generated "get started" line for a freshly installed
- * pack from its `initialization.entrypoint` ONLY. PHASE 1 deliberately ignores
- * the free-text `initialization.prompt` prose (rendering/moderation is a later
- * story) so untrusted prose can't reach the operator's terminal.
- *
- * The command is slash-normalized to exactly one leading slash regardless of
- * whether `entrypoint` was stored with or without one, matching the HQ Sync
- * desktop render: ``Run `/email-assistant` to get started``.
- *
- * Returns `null` when there is no initialization block (backwards-compatible —
- * the caller prints nothing extra).
- */
-export function getStartedLine(
-  initialization?: PackManifest['initialization'],
-): string | null {
-  const entrypoint = initialization?.entrypoint;
-  if (typeof entrypoint !== 'string' || entrypoint.trim() === '') return null;
-  const command = '/' + entrypoint.trim().replace(/^\/+/, '');
-  return `Run \`${command}\` to get started`;
-}
-
-// ---------------------------------------------------------------------------
-// Hooks confirmation
-// ---------------------------------------------------------------------------
-
-async function confirmHooks(
-  pkg: PackManifest,
-  allowHooks: boolean
-): Promise<boolean> {
-  const hooks = pkg.contributes.hooks ?? [];
-  if (hooks.length === 0) return true;
-  if (allowHooks) {
-    console.log(
-      chalk.yellow(
-        `--allow-hooks set; installing ${hooks.length} hook(s) without prompting.`
-      )
-    );
-    return true;
-  }
-  console.log('');
-  console.log(
-    chalk.yellow(`Pack ${pkg.publisher}/${pkg.name} declares ${hooks.length} hook(s):`)
-  );
-  for (const h of hooks) console.log(chalk.yellow(`  - ${h}.sh`));
-  console.log(
-    chalk.yellow(
-      'These run automatically on tool events with your shell permissions.'
-    )
-  );
-  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());
-}
-
-// ---------------------------------------------------------------------------
-// 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
-//
-// `package.yaml:conditional` is arbitrary bash sourced from a remote pack.
-// Evaluating it is effectively code execution — same trust surface as the
-// post-install hooks. We therefore gate it behind the same confirmation flow:
-// a pack with a `conditional` must be approved (interactively) or run under
-// `--allow-hooks` (ambient trust, e.g. `create-hq --full`).
-// ---------------------------------------------------------------------------
-
-async function confirmConditional(
-  pkg: PackManifest,
-  allowHooks: boolean,
-): Promise<boolean> {
-  if (!pkg.conditional) return true;
-  if (allowHooks) return true;
-  console.log('');
-  console.log(
-    chalk.yellow(
-      `Pack ${pkg.publisher}/${pkg.name} declares a conditional predicate:`,
-    ),
-  );
-  console.log(chalk.yellow(`  $ ${pkg.conditional}`));
-  console.log(
-    chalk.yellow(
-      'This runs as bash with your shell permissions before install proceeds.',
-    ),
-  );
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  const answer: string = await new Promise((resolve) => {
-    rl.question('Evaluate predicate? [y/N] ', (a) => {
-      rl.close();
-      resolve(a);
-    });
-  });
-  return /^(y|yes)$/i.test(answer.trim());
-}
-
-function evalConditional(expr: string): boolean {
-  const r = spawnSync('bash', ['-c', expr], { stdio: 'ignore' });
-  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 an install-time {@link SecretResolver} from a fresh server authorization
- * decision. The encrypted cache may identify one unambiguous scope, but its
- * plaintext is never trusted or read to register an MCP server.
- *
- * With `--company`, the caller-selected company is resolved normally. Without
- * it, exactly one cache scope may identify the intended company/person context;
- * multiple scopes are ambiguous and fail closed. The requested names are then
- * loaded through the same server-authorized endpoint as exec/env/run. Offline,
- * expired-session, forbidden, not-found, script-lock, and malformed-response
- * outcomes all produce an empty resolver, so MCP registration is deferred.
- *
- * The returned synchronous resolver contains only values from that fresh
- * authorization response. No cached value is a fallback.
- */
-export async function makeInstallSecretResolver(
-  secretNames: string[],
-  company?: string,
-): Promise<SecretResolver> {
-  const names = [...new Set(secretNames)];
-  if (names.length === 0) return () => null;
-
-  try {
-    const token = await ensureCognitoToken({ interactive: false });
-    let scopeUid: string;
-    if (company) {
-      scopeUid = await getCompanyUid(token, company);
-    } else {
-      const scopes = listSecretCacheScopes();
-      if (scopes.length !== 1) return () => null;
-      [scopeUid] = scopes;
-    }
-    const authorized = await loadRevealedSecrets(token, scopeUid, names);
-    return (name: string): string | null => authorized.get(name) ?? null;
-  } catch {
-    return () => null;
-  }
-}
-
-const INSTALL_SECRET_REF_RE =
-  /\$\{secret:([A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]+)*)\}/g;
-
-function collectManifestSecretNames(manifest: McpManifest): string[] {
-  const names = new Set<string>();
-  for (const value of [
-    ...Object.values(manifest.headers ?? {}),
-    ...Object.values(manifest.env ?? {}),
-  ]) {
-    INSTALL_SECRET_REF_RE.lastIndex = 0;
-    for (let match = INSTALL_SECRET_REF_RE.exec(value); match; match = INSTALL_SECRET_REF_RE.exec(value)) {
-      names.add(match[1]);
-    }
-  }
-  return [...names];
-}
-
-/**
- * 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.
- */
-async function wireMcpServers(
-  pkg: PackManifest,
-  destDir: string,
-  company?: string,
-): Promise<{ registered: string[]; skipped: string[] }> {
-  const loadManifest = (name: string): McpManifest => loadMcpManifestFrom(destDir, name);
-  const registered: string[] = [];
-  const skipped: string[] = [];
-
-  for (const name of pkg.contributes.mcp ?? []) {
-    try {
-      const resolveSecret = await makeInstallSecretResolver(
-        collectManifestSecretNames(loadManifest(name)),
-        company,
-      );
-      // 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
-// ---------------------------------------------------------------------------
-
-/**
- * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
- * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships
- * `core/packages/` as the canonical pack root; writing to top-level
- * `packages/` would leave an orphan tree alongside the real one.
- *
- * Re-installs replace the existing destination so stale contributions don't
- * linger (the post-install `scan-packages.sh` would otherwise wire them
- * back into host paths).
- *
- * Exported for tests in pack-install.test.ts — see that file for the
- * contract this function pins.
- */
-export function installToPackages(
-  payloadDir: string,
-  pkg: PackManifest,
-  hqRoot: string
-): string {
-  const packagesDir = path.join(hqRoot, 'core', 'packages');
-  fs.mkdirSync(packagesDir, { recursive: true });
-  const destDir = path.join(packagesDir, pkg.name);
-
-  // SECURITY/ATOMICITY (US-020): wire atomically. rsync into a sibling staging
-  // dir on the SAME filesystem first; only swap it into the final destination
-  // once the copy fully succeeds. A failed/partial rsync therefore never
-  // leaves a half-wired pack dir in place (which scan-packages.sh would then
-  // wire into host paths). On any error the staging dir is rolled back.
-  const stagingDir = fs.mkdtempSync(path.join(packagesDir, `.${pkg.name}.staging-`));
-  try {
-    // rsync preserves modes/symlinks; argv form — no shell.
-    const srcSlashed = payloadDir.endsWith('/') ? payloadDir : `${payloadDir}/`;
-    const stagingSlashed = stagingDir.endsWith('/') ? stagingDir : `${stagingDir}/`;
-    execFileSync('rsync', ['-a', srcSlashed, stagingSlashed], { stdio: 'inherit' });
-
-    // Swap into place: remove any prior install, then atomic rename. The brief
-    // window between rm and rename is unavoidable with a same-name dir, but the
-    // staged copy guarantees the NEW contents are fully present before we touch
-    // the live location.
-    if (fs.existsSync(destDir)) {
-      fs.rmSync(destDir, { recursive: true, force: true });
-    }
-    fs.renameSync(stagingDir, destDir);
-  } finally {
-    if (fs.existsSync(stagingDir)) {
-      fs.rmSync(stagingDir, { recursive: true, force: true });
-    }
-  }
-  return destDir;
-}
-
-/**
- * Stamp the install-time `source:` into the destination package.yaml. This is
- * the only on-disk record of which `recommended_packages[].source` produced
- * each installed pack. `core/scripts/setup.sh` (hq-core >=14.2.x) reads
- * `^source:` from every installed `core/packages/<name>/package.yaml` to dedup
- * against `core/core.yaml:recommended_packages` — without this stamp, the
- * dedup set is empty and every recommended pack is re-prompted on every
- * setup.sh run.
- *
- * Idempotent: re-installs (and `hq update`) replace any pre-existing
- * top-level `source:` line rather than duplicating it. Nested `source:`
- * fields under `contributes:` (or any other block) are left untouched.
- *
- * The value is YAML double-quoted so `github:` sources containing `#`
- * survive round-trip (an unquoted `#` would be parsed as a comment).
- *
- * If the manifest opens with a `---` YAML document marker, the source line is
- * inserted *after* the marker — otherwise the prepend would create a
- * two-document stream that single-doc `yaml.load` callers in this codebase
- * cannot read.
- *
- * Exported for tests.
- */
-export function stampInstallSource(destDir: string, source: string): void {
-  const manifestPath = path.join(destDir, 'package.yaml');
-  if (!fs.existsSync(manifestPath)) {
-    // installToPackages already validated the payload contained package.yaml.
-    // If it's gone by the time we stamp, something deleted it between calls —
-    // fail loud so the regression surfaces in tests.
-    throw new Error(`stampInstallSource: ${manifestPath} not found`);
-  }
-  const original = fs.readFileSync(manifestPath, 'utf-8');
-  // Strip any existing top-level `source:` line. Match only lines starting at
-  // column 0 so nested `source:` fields (none in spec today, but defensive)
-  // are not touched.
-  const lines = original.split('\n').filter((line) => !/^source\s*:/.test(line));
-  const quoted = `"${source.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-  const sourceLine = `source: ${quoted}`;
-
-  // Detect a leading YAML document marker (`---`, optionally followed by
-  // trailing whitespace or a comment). If present, the source line goes
-  // *after* it so the manifest stays a single document.
-  let insertAt = 0;
-  while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
-  const opensWithDocMarker =
-    insertAt < lines.length && /^---(\s|#|$)/.test(lines[insertAt]);
-  if (opensWithDocMarker) {
-    lines.splice(insertAt + 1, 0, sourceLine);
-  } else {
-    // Drop any leading blank lines we walked past so the file doesn't grow a
-    // blank-line gutter on every re-stamp.
-    lines.splice(0, insertAt, sourceLine);
-  }
-  fs.writeFileSync(manifestPath, lines.join('\n'));
-}
-
-/**
- * Run `<hqRoot>/core/scripts/scan-packages.sh` to wire the newly installed
- * pack's contributions into the host paths (skills, hooks, policies, etc.).
- * Skipping with a dim warning if the script is missing keeps fresh HQs (or
- * older templates) usable — the next session start picks them up via its
- * own scan.
- *
- * Exported for tests.
- *
- * `quiet` keeps the script's stdout off our stdout (it routes only stderr
- * through, and sets HQ_SCAN_QUIET=1) so callers emitting machine-readable
- * JSON — e.g. `hq packs uninstall --json` — produce clean output.
- */
-export function runScanPackages(hqRoot: string, opts: { quiet?: boolean } = {}): void {
-  const script = path.join(hqRoot, 'core', 'scripts', 'scan-packages.sh');
-  if (!fs.existsSync(script)) {
-    if (!opts.quiet) {
-      console.log(
-        chalk.dim(
-          `  (core/scripts/scan-packages.sh not present — skipping auto-wire; ` +
-            `will run on next session start)`
-        )
-      );
-    }
-    return;
-  }
-  const r = spawnSync('bash', [script], {
-    cwd: hqRoot,
-    env: { ...process.env, HQ_ROOT: hqRoot, ...(opts.quiet ? { HQ_SCAN_QUIET: '1' } : {}) },
-    stdio: opts.quiet ? ['ignore', 'ignore', 'inherit'] : 'inherit',
-  });
-  if (r.status !== 0 && !opts.quiet) {
-    console.log(chalk.yellow('  scan-packages.sh exited non-zero; see output above.'));
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Public entry
-// ---------------------------------------------------------------------------
-
-export interface InstallPackOptions {
-  allowHooks?: boolean;
-  /** Company context for online authorization of install-time MCP secret refs. */
-  company?: string;
-  /**
-   * 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
-   * stdout) so a caller emitting machine-readable JSON keeps stdout clean.
-   * The fetch tools are already quiet/stderr-only (`npm pack --silent`,
-   * `rsync -a`, `git clone` progress -> stderr), so this is sufficient.
-   */
-  quiet?: boolean;
-  /**
-   * US-021 marketplace artifact integrity. When provided (a marketplace listing
-   * carries a pinned content hash + signature + public key), the downloaded
-   * tarball is verified BEFORE extraction; a mismatch aborts the install. US-006
-   * populates this from the listing detail response.
-   */
-  integrity?: ArtifactIntegrity;
-  /**
-   * US-006 marketplace transport seams (resolve/refresh/download), injected for
-   * tests. When omitted, `defaultMarketplaceDeps()` (public listings API +
-   * presigned S3) is used. Only consulted when `source` is `marketplace:...`.
-   */
-  marketplaceDeps?: MarketplaceDeps;
-  /**
-   * US-006: require a valid signature for marketplace artifacts. Default false
-   * during the signing-key-deferral window (the content hash is still ALWAYS
-   * verified); set true once platform signing keys are provisioned.
-   */
-  requireSignature?: boolean;
-}
-
-export async function installPack(
-  source: string,
-  opts: InstallPackOptions = {}
-): Promise<void> {
-  // NOTE: the HQ_API_KEY fail-closed gate is NOT enforced here. `installPack`
-  // is a shared primitive called both by the top-level `hq install` CLI route
-  // (where Cognito-only is the right gate — checked there instead) AND by
-  // `hq packs update` (packs.ts:runUpdate), which un-wires an existing pack's
-  // contributions BEFORE re-installing. Throwing from inside `installPack`
-  // would leave an update mid-flight (unwired, not reinstalled) whenever
-  // HQ_API_KEY happened to be set. Restricting the assertion to the install
-  // entrypoint keeps `hq packs update` fail-closed at its own call site
-  // instead (checked before it un-wires anything).
-  const transport = classify(source);
-  const hqRoot = findHqRoot();
-  // `readHqVersion` (shared with `hq packs`) reads the CANONICAL
-  // `core/core.yaml` (hq-core ≥v14), falling back to the legacy
-  // `<root>/core.yaml` only when the nested file is absent. The previous local
-  // reader looked at `<root>/core.yaml` ONLY, so on a post-v12→v15 tree it
-  // picked up a STALE leftover root copy (e.g. hqVersion 12.1.0) and wrongly
-  // rejected packs requiring a newer hqCore (feedback_57d7edcf, symptom b).
-  const hqVersion = readHqVersion(hqRoot);
-  const say: (...a: unknown[]) => void = opts.quiet
-    ? (...a) => console.error(...a)
-    : (...a) => console.log(...a);
-
-  say(chalk.dim(`-> transport: ${transport}; source: ${source}`));
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-pack-'));
-  try {
-    let fetched: FetchResult;
-    switch (transport) {
-      case 'npm':
-        fetched = fetchNpm(source, tmpDir, opts.integrity);
-        break;
-      case 'git':
-        fetched = fetchGit(source, tmpDir, opts.followBranch ?? false);
-        break;
-      case 'local':
-        fetched = fetchLocal(source, tmpDir);
-        break;
-      case 'marketplace':
-        fetched = await fetchMarketplace(
-          source,
-          tmpDir,
-          opts.marketplaceDeps ?? defaultMarketplaceDeps(),
-          { requireSignature: opts.requireSignature },
-        );
-        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) {
-        say(
-          chalk.red(
-            'Install aborted (conditional predicate not approved).',
-          ),
-        );
-        return;
-      }
-      const ok = evalConditional(pkg.conditional);
-      if (!ok) {
-        say(
-          chalk.yellow(
-            `Skipping ${pkg.name}: conditional "${pkg.conditional}" returned non-zero.`
-          )
-        );
-        return;
-      }
-    }
-
-    const confirmed = await confirmHooks(pkg, opts.allowHooks ?? false);
-    if (!confirmed) {
-      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
-    // removed the orphan top-level `modules/` tree alongside the canonical
-    // `core/`). The one piece of install-time provenance we DO record is the
-    // input `source` string, stamped into the destination `package.yaml` so
-    // setup.sh can dedup against `core/core.yaml:recommended_packages` on
-    // re-runs. Stamping the literal input (not the resolved SHA/version)
-    // matches the verbatim equality check in setup.sh.
-    //
-    // US-006 EXCEPTION: for the marketplace transport we stamp the RESOLVED
-    // source (`marketplace:<slug>@<version>`) rather than the literal input.
-    // The version is what lets `hq packs update` detect a newer listing — the
-    // bare `marketplace:<slug>` input carries no version to compare against.
-    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 } = await wireMcpServers(
-        pkg,
-        destDir,
-        opts.company,
-      );
-      // 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.`
-      )
-    );
-    // US-005 — when the pack declares an `initialization` block, print a safe,
-    // auto-generated "get started" line right after the success output. PHASE 1
-    // derives the line from `initialization.entrypoint` ONLY (never the
-    // free-text `initialization.prompt` prose), and matches the HQ Sync desktop
-    // wording for consistency. Absent block → nothing extra (backwards-compat).
-    const getStarted = getStartedLine(pkg.initialization);
-    if (getStarted) say(chalk.cyan(getStarted));
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-}