@indigoai-us/hq-cli 5.49.0 → 5.50.1

package/dist/commands/mcp-status.d.ts

@@ -0,0 +1,130 @@
+import { Command } from 'commander';
+import { type SafeWriteEnv } from './mcp-registration.js';
+/** A server's presence on ONE runtime surface. */
+export type PresenceState = 
+/** The server def is present (and parsed) on this runtime. */
+'present'
+/** The runtime parsed fine but this server is not registered there. */
+ | 'absent'
+/** The runtime's config is malformed (unparseable) — presence is unknowable. */
+ | 'unparseable'
+/** The runtime is not installed (Codex only: `~/.codex` missing). */
+ | 'not-installed';
+/** Per-runtime, per-server status. */
+export interface RuntimeServerStatus {
+    /** present / absent / unparseable / not-installed. */
+    presence: PresenceState;
+    /** The transport read off this runtime's def (undefined when absent). */
+    transport?: string;
+    /** The target (url or command+args) read off this runtime's def (undefined when absent). */
+    target?: string;
+    /** Header KEYS present on this runtime's def (values are NEVER captured). */
+    headerKeys?: string[];
+    /** Env KEYS present on this runtime's def (values are NEVER captured). */
+    envKeys?: string[];
+}
+/** A single HQ-owned MCP server's cross-runtime status. */
+export interface McpServerStatus {
+    /** The bare server name (the `mcpServers` / `mcp_servers` key). */
+    server: string;
+    /** The pack that owns it (`_hqPack` provenance). */
+    pack: string;
+    /** The transport (from whichever runtime has the def; '' when neither). */
+    transport: string;
+    /** The target — url (http/sse) or command+args (stdio); '' when unknown. NEVER a secret. */
+    target: string;
+    /** Claude-runtime status. */
+    claude: RuntimeServerStatus;
+    /** Codex-runtime status. */
+    codex: RuntimeServerStatus;
+    /**
+     * True iff the server is present on EXACTLY ONE of the two runtimes (a partial
+     * registration). When Codex is not installed and the server is Claude-only, this
+     * is still PARTIAL — `partialReason` names the missing runtime.
+     */
+    partial: boolean;
+    /** Human-readable reason naming the missing runtime when `partial`. */
+    partialReason?: string;
+    /**
+     * True iff the server is present on BOTH runtimes but the transport-relevant
+     * content differs (transport, target, or header/env KEY sets). Header VALUES are
+     * never compared.
+     */
+    drifted: boolean;
+}
+/** A runtime's top-level status. */
+export interface RuntimeStatus {
+    /** Whether the runtime is installed (Claude is always; Codex iff `~/.codex` exists). */
+    installed: boolean;
+    /** Whether the runtime's config parsed (false => unparseable). */
+    parses: boolean;
+    /** The config file path inspected. */
+    configPath: string;
+}
+/** The structured `hq mcp status` report. */
+export interface McpStatusReport {
+    /** Every HQ-owned server, keyed by name, with cross-runtime status. */
+    servers: McpServerStatus[];
+    /** Per-runtime top-level status. */
+    runtimes: {
+        claude: RuntimeStatus;
+        codex: RuntimeStatus;
+    };
+    /** The backup root + the most-recent backup directory names (restore targets). */
+    backups: {
+        /** `~/.hq/backups/mcp` — where US-006 writes pre-write snapshots. */
+        root: string;
+        /** The most-recent backup dir NAMES (`<iso>-<pack>`), newest first (capped). */
+        recent: string[];
+    };
+}
+/**
+ * Compute the cross-runtime MCP status report. PURE (modulo filesystem reads):
+ * reads `~/.claude.json` + `~/.codex/config.toml` (Codex only when installed),
+ * enumerates HQ-owned servers (those with a non-empty `_hqPack`), and annotates
+ * each with per-runtime presence, PARTIAL (present in exactly one runtime, missing
+ * runtime named), and DRIFT (present in both but transport/target/header-keys
+ * differ). A malformed config marks that runtime `parses:false`/`unparseable`
+ * rather than throwing. Header VALUES are never read into the report.
+ */
+export declare function computeMcpStatus(env: SafeWriteEnv): McpStatusReport;
+/**
+ * Render the report as human-readable text. Per server: name, pack, transport,
+ * target, and a per-runtime line. PARTIAL servers are marked loudly with the
+ * missing runtime NAMED; DRIFT is flagged. Header/env VALUES are rendered as
+ * {@link SECRET_REDACTION} — never the value. Ends with the backup restore hint.
+ */
+export declare function renderMcpStatus(report: McpStatusReport): string;
+/** The structured capability advertisement for this hq-cli. */
+export interface McpCapabilities {
+    /** This hq-cli supports MCP pack registration. */
+    supportsMcp: boolean;
+    /** The pack contribution types this CLI can register (currently just `mcp`). */
+    contributes: string[];
+    /** The agent runtimes MCP servers are registered into. */
+    runtimes: string[];
+    /** The MCP transports this CLI can emit. */
+    transports: string[];
+}
+/**
+ * Compute this hq-cli's MCP capability advertisement. PURE — no IO, no env: the
+ * answer is a property of the CLI build itself (it supports `contributes.mcp`
+ * dual-runtime registration), so it returns a static structured object. Kept as a
+ * helper (not inlined into the action) so tests / CI can assert the advert shape
+ * without commander, mirroring {@link computeMcpStatus}.
+ */
+export declare function computeMcpCapabilities(): McpCapabilities;
+/** Render the capability advert as human-readable text. */
+export declare function renderMcpCapabilities(caps: McpCapabilities): string;
+/**
+ * Wire the `hq mcp` command group with a read-only `status` subcommand and a
+ * `capabilities` advertisement subcommand (US-012). `status` resolves the
+ * production env (real home), computes the report, and prints either
+ * `JSON.stringify(report, null, 2)` (`--json`, for CI / US-013) or the
+ * human-readable {@link renderMcpStatus} text. `capabilities` advertises that this
+ * hq-cli supports `contributes.mcp` ({@link computeMcpCapabilities} /
+ * {@link renderMcpCapabilities}). Follows the commander pattern used by
+ * {@link registerReindexCommand} and the subcommand-group pattern in index.ts.
+ */
+export declare function registerMcpCommand(program: Command): void;
+//# sourceMappingURL=mcp-status.d.ts.map

package/dist/commands/mcp-status.js

@@ -0,0 +1,406 @@
+/**
+ * hq mcp status — read-only observability over installed MCP packs across BOTH
+ * runtimes (Claude + Codex). US-011.
+ *
+ * This closes the US-009 gap: the old symlink-only `linkStatus` structurally
+ * cannot see a JSON/TOML *merge* (an MCP server is MERGED into the shared agent
+ * configs, never symlinked). So status reads the PROVENANCE marker `_hqPack`
+ * directly off the server defs in `~/.claude.json` + `~/.codex/config.toml`,
+ * enumerates every HQ-owned server, and reports — PER runtime — present? parses?
+ * matches-or-drifted? It surfaces PARTIAL explicitly (registered in one runtime
+ * but not the other, naming the missing runtime) and lists the most-recent
+ * backups so a corrupted config has a discoverable restore target.
+ *
+ * SECRET SAFETY (hard rule): header/env VALUES are NEVER rendered in the clear.
+ * Status reads configs that hold RESOLVED secrets (the runtime needs real
+ * headers), and we do NOT have the raw secret-set at status time — so we redact
+ * by KEY presence: header/env KEYS are shown, every value is rendered as
+ * {@link SECRET_REDACTION}, and no value is ever compared in the clear.
+ *
+ * The pure {@link computeMcpStatus} + {@link renderMcpStatus} functions are
+ * exported so tests (and CI / US-013) can drive them WITHOUT going through
+ * commander; {@link registerMcpCommand} wires the `hq mcp status` command group.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="518fe2be-89c1-53a6-b2fd-263fccc128ba")}catch(e){}}();
+import * as fs from 'fs';
+import { HQ_PACK_PROVENANCE_KEY, SECRET_REDACTION, backupRoot, claudeConfigFormat, claudeConfigPath, codexConfigFormat, codexConfigPath, CODEX_MCP_SERVERS_KEY, ConfigParseError, isCodexInstalled, readConfigDoc, resolveEnv, } from './mcp-registration.js';
+// ---------------------------------------------------------------------------
+// Pure status computation.
+// ---------------------------------------------------------------------------
+/** How many recent backup dirs to surface. */
+const MAX_RECENT_BACKUPS = 5;
+/** Read provenance (`_hqPack`) off a def; non-empty string => HQ-owned. */
+function provenanceOf(def) {
+    if (def === null || typeof def !== 'object' || Array.isArray(def))
+        return undefined;
+    const stamp = def[HQ_PACK_PROVENANCE_KEY];
+    return typeof stamp === 'string' && stamp.length > 0 ? stamp : undefined;
+}
+/** The transport string off a def (`type`), or '' when not a string. */
+function transportOf(def) {
+    return typeof def.type === 'string' ? def.type : '';
+}
+/**
+ * The target off a def — url (http/sse) or command(+args) (stdio). NEVER a
+ * header/secret. '' when neither a url nor a command is present.
+ */
+function targetOf(def) {
+    const type = transportOf(def);
+    if ((type === 'http' || type === 'sse') && typeof def.url === 'string')
+        return def.url;
+    if (typeof def.command === 'string') {
+        const args = Array.isArray(def.args) && def.args.length > 0 ? ` ${def.args.join(' ')}` : '';
+        return `${def.command}${args}`;
+    }
+    if (typeof def.url === 'string')
+        return def.url;
+    return '';
+}
+/** Header KEYS off a def (values NEVER captured). */
+function headerKeysOf(def) {
+    const h = def.headers;
+    if (!h || typeof h !== 'object' || Array.isArray(h))
+        return [];
+    return Object.keys(h).sort();
+}
+/** Env KEYS off a def (values NEVER captured). */
+function envKeysOf(def) {
+    const e = def.env;
+    if (!e || typeof e !== 'object' || Array.isArray(e))
+        return [];
+    return Object.keys(e).sort();
+}
+/** Summarize a def into its transport-relevant, value-FREE content (for drift). */
+function summarizeDef(def) {
+    return {
+        transport: transportOf(def),
+        target: targetOf(def),
+        headerKeys: headerKeysOf(def),
+        envKeys: envKeysOf(def),
+    };
+}
+/** True iff two def summaries differ in any transport-relevant field (header VALUES never compared). */
+function summariesDiffer(a, b) {
+    return JSON.stringify(a) !== JSON.stringify(b);
+}
+/** Scan the Claude runtime: read `~/.claude.json`, collect HQ-owned servers. */
+function scanClaude(env) {
+    const configPath = claudeConfigPath(env);
+    const hqServers = new Map();
+    let parses = true;
+    try {
+        const { doc } = readConfigDoc(configPath, claudeConfigFormat);
+        const servers = doc.mcpServers;
+        if (servers && typeof servers === 'object' && !Array.isArray(servers)) {
+            for (const [name, def] of Object.entries(servers)) {
+                const pack = provenanceOf(def);
+                if (pack !== undefined) {
+                    hqServers.set(name, { def: def, pack });
+                }
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof ConfigParseError) {
+            parses = false; // malformed — report unparseable, do NOT crash the command.
+        }
+        else {
+            throw e; // ConfigPermissionError or anything unexpected — surface it.
+        }
+    }
+    return { installed: true, parses, configPath, hqServers };
+}
+/** Scan the Codex runtime: only when installed; read `~/.codex/config.toml`. */
+function scanCodex(env) {
+    const configPath = codexConfigPath(env);
+    const hqServers = new Map();
+    if (!isCodexInstalled(env)) {
+        return { installed: false, parses: true, configPath, hqServers };
+    }
+    let parses = true;
+    try {
+        const { doc } = readConfigDoc(configPath, codexConfigFormat);
+        const servers = doc.value[CODEX_MCP_SERVERS_KEY];
+        if (servers && typeof servers === 'object' && !Array.isArray(servers)) {
+            for (const [name, def] of Object.entries(servers)) {
+                const pack = provenanceOf(def);
+                if (pack !== undefined) {
+                    hqServers.set(name, { def: def, pack });
+                }
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof ConfigParseError) {
+            parses = false;
+        }
+        else {
+            throw e;
+        }
+    }
+    return { installed: true, parses, configPath, hqServers };
+}
+/** Build the per-runtime, per-server status from a scan (or its absence). */
+function runtimeServerStatus(scan, name) {
+    if (!scan.installed)
+        return { presence: 'not-installed' };
+    if (!scan.parses)
+        return { presence: 'unparseable' };
+    const found = scan.hqServers.get(name);
+    if (!found)
+        return { presence: 'absent' };
+    return {
+        presence: 'present',
+        transport: transportOf(found.def),
+        target: targetOf(found.def),
+        headerKeys: headerKeysOf(found.def),
+        envKeys: envKeysOf(found.def),
+    };
+}
+/** List the most-recent backup dir names under `backupRoot` (newest first, capped). */
+function recentBackups(env) {
+    const root = backupRoot(env);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        // ENOENT (no backups yet) or unreadable — surface an empty list.
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        // Names are `<iso>-<pack>` with a sortable UTC stamp prefix — desc = newest first.
+        .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0))
+        .slice(0, MAX_RECENT_BACKUPS);
+}
+/**
+ * Compute the cross-runtime MCP status report. PURE (modulo filesystem reads):
+ * reads `~/.claude.json` + `~/.codex/config.toml` (Codex only when installed),
+ * enumerates HQ-owned servers (those with a non-empty `_hqPack`), and annotates
+ * each with per-runtime presence, PARTIAL (present in exactly one runtime, missing
+ * runtime named), and DRIFT (present in both but transport/target/header-keys
+ * differ). A malformed config marks that runtime `parses:false`/`unparseable`
+ * rather than throwing. Header VALUES are never read into the report.
+ */
+export function computeMcpStatus(env) {
+    const claudeScan = scanClaude(env);
+    const codexScan = scanCodex(env);
+    // Union of every HQ-owned server name across both runtimes.
+    const names = new Set([...claudeScan.hqServers.keys(), ...codexScan.hqServers.keys()]);
+    const servers = [];
+    for (const name of [...names].sort()) {
+        const claude = runtimeServerStatus(claudeScan, name);
+        const codex = runtimeServerStatus(codexScan, name);
+        // Prefer whichever runtime has the def for the top-level transport/target.
+        const claudeFound = claudeScan.hqServers.get(name);
+        const codexFound = codexScan.hqServers.get(name);
+        const repDef = claudeFound?.def ?? codexFound?.def;
+        const pack = claudeFound?.pack ?? codexFound?.pack ?? '';
+        const transport = repDef ? transportOf(repDef) : '';
+        const target = repDef ? targetOf(repDef) : '';
+        const onClaude = claude.presence === 'present';
+        const onCodex = codex.presence === 'present';
+        // PARTIAL = present in exactly one runtime. Name the missing runtime.
+        let partial = false;
+        let partialReason;
+        if (onClaude && !onCodex) {
+            partial = true;
+            partialReason = codexScan.installed
+                ? 'registered in Claude but NOT in Codex'
+                : 'registered in Claude; Codex runtime not installed (server not registered in Codex)';
+        }
+        else if (onCodex && !onClaude) {
+            partial = true;
+            partialReason = 'registered in Codex but NOT in Claude';
+        }
+        // DRIFT = present in both but transport-relevant content differs (no header VALUES).
+        let drifted = false;
+        if (onClaude && onCodex && claudeFound && codexFound) {
+            drifted = summariesDiffer(summarizeDef(claudeFound.def), summarizeDef(codexFound.def));
+        }
+        servers.push({
+            server: name,
+            pack,
+            transport,
+            target,
+            claude,
+            codex,
+            partial,
+            partialReason,
+            drifted,
+        });
+    }
+    return {
+        servers,
+        runtimes: {
+            claude: {
+                installed: claudeScan.installed,
+                parses: claudeScan.parses,
+                configPath: claudeScan.configPath,
+            },
+            codex: {
+                installed: codexScan.installed,
+                parses: codexScan.parses,
+                configPath: codexScan.configPath,
+            },
+        },
+        backups: {
+            root: backupRoot(env),
+            recent: recentBackups(env),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Human-readable rendering.
+// ---------------------------------------------------------------------------
+/** Render one runtime's per-server line. Header/env VALUES are NEVER printed. */
+function renderRuntimeLine(label, st) {
+    switch (st.presence) {
+        case 'present': {
+            const parts = [`present`];
+            if (st.headerKeys && st.headerKeys.length > 0) {
+                parts.push(`headers: ${st.headerKeys.map((k) => `${k}=${SECRET_REDACTION}`).join(', ')}`);
+            }
+            if (st.envKeys && st.envKeys.length > 0) {
+                parts.push(`env: ${st.envKeys.map((k) => `${k}=${SECRET_REDACTION}`).join(', ')}`);
+            }
+            return `    ${label}: ${parts.join('  |  ')}`;
+        }
+        case 'absent':
+            return `    ${label}: absent`;
+        case 'unparseable':
+            return `    ${label}: UNPARSEABLE (config malformed)`;
+        case 'not-installed':
+            return `    ${label}: not installed`;
+    }
+}
+/**
+ * Render the report as human-readable text. Per server: name, pack, transport,
+ * target, and a per-runtime line. PARTIAL servers are marked loudly with the
+ * missing runtime NAMED; DRIFT is flagged. Header/env VALUES are rendered as
+ * {@link SECRET_REDACTION} — never the value. Ends with the backup restore hint.
+ */
+export function renderMcpStatus(report) {
+    const lines = [];
+    lines.push('HQ MCP status — installed packs across Claude + Codex');
+    lines.push('');
+    // Runtime header.
+    const c = report.runtimes.claude;
+    const x = report.runtimes.codex;
+    lines.push(`Runtimes:  Claude [${c.parses ? 'ok' : 'UNPARSEABLE'}]  ` +
+        `Codex [${!x.installed ? 'not installed' : x.parses ? 'ok' : 'UNPARSEABLE'}]`);
+    lines.push('');
+    if (report.servers.length === 0) {
+        lines.push('No HQ-owned MCP servers registered (no _hqPack provenance found in either runtime).');
+    }
+    else {
+        for (const s of report.servers) {
+            const flags = [];
+            if (s.partial)
+                flags.push('PARTIAL');
+            if (s.drifted)
+                flags.push('DRIFTED');
+            const flagStr = flags.length > 0 ? `  <<< ${flags.join(' + ')}` : '';
+            lines.push(`• ${s.server}  (pack: ${s.pack})${flagStr}`);
+            lines.push(`    transport: ${s.transport || '(unknown)'}    target: ${s.target || '(none)'}`);
+            lines.push(renderRuntimeLine('Claude', s.claude));
+            lines.push(renderRuntimeLine('Codex ', s.codex));
+            if (s.partial && s.partialReason) {
+                lines.push(`    PARTIAL: ${s.partialReason}`);
+            }
+            if (s.drifted) {
+                lines.push(`    DRIFTED: Claude and Codex defs differ (transport/target/header-keys)`);
+            }
+            lines.push('');
+        }
+    }
+    // Backups (restore targets for a corrupted config).
+    lines.push(`Backups:   ${report.backups.root}`);
+    if (report.backups.recent.length > 0) {
+        lines.push(`  Most recent:`);
+        for (const b of report.backups.recent) {
+            lines.push(`    - ${b}`);
+        }
+        lines.push(`  To restore a corrupted config, copy the snapshot from the newest dir above back into place.`);
+    }
+    else {
+        lines.push(`  (no backups yet)`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Compute this hq-cli's MCP capability advertisement. PURE — no IO, no env: the
+ * answer is a property of the CLI build itself (it supports `contributes.mcp`
+ * dual-runtime registration), so it returns a static structured object. Kept as a
+ * helper (not inlined into the action) so tests / CI can assert the advert shape
+ * without commander, mirroring {@link computeMcpStatus}.
+ */
+export function computeMcpCapabilities() {
+    return {
+        supportsMcp: true,
+        contributes: ['mcp'],
+        runtimes: ['claude', 'codex'],
+        transports: ['http', 'stdio', 'sse'],
+    };
+}
+/** Render the capability advert as human-readable text. */
+export function renderMcpCapabilities(caps) {
+    const lines = [];
+    lines.push('HQ MCP capabilities — what this hq-cli supports');
+    lines.push('');
+    lines.push(`  supports MCP: ${caps.supportsMcp ? 'yes' : 'no'}`);
+    lines.push(`  contributes:  ${caps.contributes.join(', ')}`);
+    lines.push(`  runtimes:     ${caps.runtimes.join(', ')}`);
+    lines.push(`  transports:   ${caps.transports.join(', ')}`);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Command wiring.
+// ---------------------------------------------------------------------------
+/**
+ * Wire the `hq mcp` command group with a read-only `status` subcommand and a
+ * `capabilities` advertisement subcommand (US-012). `status` resolves the
+ * production env (real home), computes the report, and prints either
+ * `JSON.stringify(report, null, 2)` (`--json`, for CI / US-013) or the
+ * human-readable {@link renderMcpStatus} text. `capabilities` advertises that this
+ * hq-cli supports `contributes.mcp` ({@link computeMcpCapabilities} /
+ * {@link renderMcpCapabilities}). Follows the commander pattern used by
+ * {@link registerReindexCommand} and the subcommand-group pattern in index.ts.
+ */
+export function registerMcpCommand(program) {
+    const mcp = program
+        .command('mcp')
+        .description('MCP pack observability (read-only) across Claude + Codex');
+    mcp
+        .command('status')
+        .description('Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)')
+        .option('--json', 'Emit the structured report as JSON (for CI / scripting)')
+        .action((opts) => {
+        const env = resolveEnv();
+        const report = computeMcpStatus(env);
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(`${renderMcpStatus(report)}\n`);
+        }
+    });
+    mcp
+        .command('capabilities')
+        .description('Advertise that this hq-cli supports contributes.mcp (dual-runtime Claude+Codex registration)')
+        .option('--json', 'Emit the structured capability object as JSON (for CI / scripting)')
+        .action((opts) => {
+        const caps = computeMcpCapabilities();
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(caps, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(`${renderMcpCapabilities(caps)}\n`);
+        }
+    });
+}
+//# sourceMappingURL=mcp-status.js.map
+//# debugId=518fe2be-89c1-53a6-b2fd-263fccc128ba

package/dist/commands/pack-install.d.ts

@@ -34,6 +34,7 @@
  * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 import { type KeyObject } from 'node:crypto';
+import { type SecretResolver } from './mcp-registration.js';
 import type { PackManifest } from '../types.js';
 export type Transport = 'npm' | 'git' | 'local' | 'marketplace';
 /** Prefix that routes a source through the HQ marketplace transport (US-006). */
@@ -237,6 +238,26 @@ export declare function computeArtifactHash(tarballBytes: Uint8Array): string;
  * full strings rather than prefixes.
  */
 export declare function verifyArtifact(input: VerifyArtifactInput): void;
+/**
+ * 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 declare function validateMcpManifest(payloadDir: string, item: string): void;
 export declare function validateManifest(payloadDir: string, hqVersion: string | null): PackManifest;
 /**
  * Derive the safe, auto-generated "get started" line for a freshly installed
@@ -252,6 +273,40 @@ export declare function validateManifest(payloadDir: string, hqVersion: string |
  * the caller prints nothing extra).
  */
 export declare function getStartedLine(initialization?: PackManifest['initialization']): string | null;
+/**
+ * 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 declare function renderMcpServerLine(payloadDir: string, item: string): string;
+/**
+ * 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 declare function confirmMcp(pkg: PackManifest, payloadDir: string, allowMcp: boolean): Promise<boolean>;
+/**
+ * Build the install-time {@link SecretResolver} bound to the HQ vault's local
+ * secrets-cache (`~/.hq/secrets-cache/<scope>/<NAME>`, AES-256-GCM, 0600, TTL'd).
+ *
+ * Active-company resolution at install time is INDIRECT by design: `hq install`
+ * has no `--company` flag and runs OFFLINE (no token), so we cannot resolve a
+ * single active company UID the way `hq run` / `hq secrets` do (via
+ * `getEntityUid` over the network). Instead we probe EVERY cached scope
+ * (`cmp_*`/`prs_*` — whichever has minted secrets locally) for the requested
+ * name and return the first hit. This naturally resolves to whichever company
+ * context just provisioned the secret (e.g. the one `/connect-shopify` minted
+ * `VYG_API_KEY` under), without guessing, and works whether the vault scoped the
+ * key under a company or person entity.
+ *
+ * On MISS across all scopes (no cache, expired TTL, or key never minted) it
+ * returns `null` — which is exactly what {@link registerMcpServers}'s
+ * unresolvable-secret path keys off to defer that server gracefully. With no
+ * cached scopes at all (`listSecretCacheScopes()` → `[]`) it simply returns
+ * `null` for every name, the desired graceful-deferral behavior.
+ */
+export declare function makeInstallSecretResolver(): SecretResolver;
 /**
  * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
  * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships
@@ -308,6 +363,13 @@ export declare function runScanPackages(hqRoot: string, opts?: {
 }): void;
 export interface InstallPackOptions {
     allowHooks?: boolean;
+    /**
+     * US-010 install-time MCP trust prompt bypass (CI/ambient-trust). Mirrors
+     * `allowHooks`: when set, `confirmMcp` skips the prompt and prints a yellow
+     * notice. Absent/false → the operator is prompted (or, in a non-TTY shell,
+     * the install is refused with a "re-run with --allow-mcp" hint).
+     */
+    allowMcp?: boolean;
     followBranch?: boolean;
     /**
      * Route this function's human output to stderr (and silence scan-packages