@opengsd/gsd-core 1.8.0 → 1.9.1

package/gsd-core/bin/lib/capability-trust.cjs

@@ -1,6 +1,7 @@
 "use strict";
 /**
- * Capability trust gate — ADR-1244 Phase 4 (Decision D5 + the compatibility half of D6).
+ * Capability trust gate — ADR-1244 Phase 4 (Decision D5 + the compatibility half of D6), extended
+ * by ADR-2782 Phase 3 (#2796) with a FOURTH executable-surface class: the reviewer lane.
  *
  * PURE module. It computes *what* a capability would do and *whether* policy allows it; it
  * never mutates the filesystem and never performs I/O beyond reading staged files to confirm
@@ -10,15 +11,28 @@
  *
  * LEAF MODULE — imports ONLY: node:fs, node:path, and ./semver-compare.cjs.
  *
+ * ADR-2782 D5 (#2796): a `reviewer` lane is piped the plan text, requirements, research findings
+ * and CONTEXT.md decisions, then its output is read back into REVIEWS.md — making it an executable
+ * surface exactly like a hook, command module, or MCP server, and it is disclosed and consent-bound
+ * the same way. `disclosureSignature` appends the lane element to its output ONLY when at least one
+ * lane is declared (D4.5) — a lane-free manifest's signature stays byte-identical to before this
+ * class existed, so no already-consented capability re-prompts on upgrade. The RESOLVED host (as
+ * opposed to the declared `hostConfigKey`) is disclosed to a human but deliberately EXCLUDED from
+ * the signature — the loader has no config resolver and must compute the same signature as the
+ * lifecycle (constraint 2, `.gsd/phase/chore-2796-reviewer-trust-disclosure/40-design.md`).
+ *
  * Exports:
  *   RESERVED_NAMESPACES               — id prefixes third parties may not claim
- *   discloseExecutableSurfaces(...)   — enumerate hooks / command modules / mcpServers
+ *   discloseExecutableSurfaces(...)   — enumerate hooks / command modules / mcpServers / reviewer lanes
+ *   collectReviewerLaneSurfaces(...)  — the reviewer-lane collector, independently testable
  *   checkReservedNamespace(id)        — is this id in a reserved namespace?
  *   evaluateSourceAllowed(parsed,...) — strictKnownRegistries enforcement
  *   checkEngines(manifest, host)      — engines.gsd hard gate + compatVersions downgrade
  *   evaluateInstallTrust(args)        — compose: source + namespace + engines + disclosure
  *   executableSetChanged(old, new)    — did the executable surface set change between versions?
  *   summarizeDisclosure(disclosure)   — human-readable consent-prompt lines
+ *   UNRESOLVED_HOST_MARKER            — the non-blank marker for an unresolved openai-http host
+ *   EGRESS_PAYLOAD_CLASSES            — the named data classes every reviewer lane receives
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -36,6 +50,26 @@ const semverMod = require('./semver-compare.cjs');
  * one. Match is case-insensitive on the normalized id.
  */
 const RESERVED_NAMESPACES = ['gsd-', 'gsd-core-', 'anthropic-'];
+/**
+ * ADR-2782 D5's gating requirement (#2796): every reviewer lane is piped the plan text,
+ * requirements, research findings and CONTEXT.md decisions. Named explicitly here so disclosure
+ * says exactly this — never the unhelpful "sends data to the tool" (design section B5).
+ */
+const EGRESS_PAYLOAD_CLASSES = ['plan text', 'requirements', 'research findings', 'CONTEXT.md decisions'];
+/**
+ * B3 (#2796 matrix): `resolvedHost` must never be a blank string — a blank reads as "no
+ * destination" rather than "not resolved". This marker is disclosed for an `openai-http` lane
+ * when no resolver was supplied to `collectReviewerLaneSurfaces`, or the supplied resolver could
+ * not resolve the declared `hostConfigKey`. Deliberately NOT part of `disclosureSignature`'s input
+ * (see the lane signature line) — only the human-facing surface carries it.
+ */
+const UNRESOLVED_HOST_MARKER = '(unresolved — no host resolver was supplied at disclosure time)';
+/**
+ * Loopback hostnames recognized LITERALLY, never by substring (an evil host must not spoof this,
+ * e.g. `notlocalhost.example`). D5: localhost is not "safe by default" — it is disclosed and
+ * FLAGGED, never omitted (matrix B4).
+ */
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0']);
 // ---------------------------------------------------------------------------
 // Disclosure
 // ---------------------------------------------------------------------------
@@ -43,24 +77,161 @@ function asString(v) {
     return typeof v === 'string' ? v : '';
 }
 /**
- * Enumerate every executable surface a capability manifest declares.
+ * Run `fn`, returning `fallback` instead of throwing. Makes each per-class collector total: a
+ * hostile manifest (a Proxy with a throwing trap, a throwing getter, or a non-object/null root)
+ * degrades ONE surface class to empty rather than crashing disclosure for the other three classes
+ * behind it in the same manifest (ADR-2782 #2796 — disclosure runs before validation and must never
+ * throw; matrix C5/E2).
+ */
+function safeCollect(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Recognize a loopback/local destination from a RESOLVED openai-http host value (matrix B4). Matches
+ * literally, never by substring — an evil host must not spoof `localhost` via e.g.
+ * `notlocalhost.example`. Falls back to a scheme-less leading-segment match so a bare config value
+ * like `localhost:1234` or `192.168.1.5:8080` (no `http://` prefix) is still recognized.
  *
- * Recognizes the three executable surface kinds a capability can ship:
- *   - `hooks`:   [{ event, script }]              — scripts run as runtime hook commands
- *   - `commands`:[{ family, module, router? }]    — modules require()'d into the CLI process
- *   - `mcpServers`: { <name>: {...} } | [{ name }] — servers spawned by the host runtime
+ * The fallback triggers on EITHER `new URL()` throwing (a value that is not parseable as an absolute
+ * URL at all, e.g. `192.168.1.5:8080` — WHATWG scheme names cannot start with a digit) OR it
+ * succeeding with an EMPTY hostname: `new URL('localhost:1234')` does NOT throw — it mis-parses the
+ * scheme-less `host:port` shape as an opaque URL whose "scheme" IS the hostname text
+ * (`protocol: "localhost:"`, `hostname: ""`), which would otherwise silently fail to recognize a
+ * bare local config value as local.
+ */
+function isLocalHostValue(hostValue) {
+    let hostname = '';
+    try {
+        hostname = new URL(hostValue).hostname;
+    }
+    catch {
+        hostname = '';
+    }
+    if (!hostname) {
+        hostname = extractBareHost(hostValue);
+    }
+    // WHATWG returns an IPv6 hostname bracketed; a bare config value may not be.
+    const lower = hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '');
+    if (LOOPBACK_HOSTNAMES.has(lower))
+        return true;
+    if (isLoopbackIpv6(lower))
+        return true;
+    return isLoopbackIpv4(lower);
+}
+/**
+ * Pull the host out of a value `new URL()` could not parse — a scheme-less
+ * `host:port`, or one carrying a path/query/fragment.
  *
- * `mcpServers` is not a first-party capability.json field today, but a third-party manifest may
- * declare it, so the trust gate discloses it whenever present (honest disclosure over the
- * narrower first-party schema). Pure: when `stagedDir` is provided, declared script/module
- * files are existence-checked and any missing ones reported, but nothing is mutated.
+ * IPv6 needs explicit handling: splitting on `:` mangles `[::1]:8080` to `[`,
+ * which then matches nothing and silently reports a loopback destination as
+ * remote. A bracketed literal is taken through its closing bracket; an unbracketed
+ * value with two or more colons is treated as a bare IPv6 address rather than
+ * `host:port`, since a host:port has exactly one.
  */
-function discloseExecutableSurfaces(manifest, stagedDir) {
+function extractBareHost(hostValue) {
+    let s = String(hostValue).trim();
+    const schemeEnd = s.indexOf('://');
+    if (schemeEnd >= 0)
+        s = s.slice(schemeEnd + 3);
+    s = s.split(/[/?#]/)[0] || '';
+    if (s.startsWith('[')) {
+        const close = s.indexOf(']');
+        return close > 0 ? s.slice(1, close) : s;
+    }
+    const colons = (s.match(/:/g) || []).length;
+    if (colons >= 2)
+        return s;
+    return colons === 1 ? s.slice(0, s.indexOf(':')) : s;
+}
+/**
+ * Render one declared argv member for the human consent prompt.
+ *
+ * A string prints as itself. Anything else prints in a form that makes its
+ * presence and shape visible rather than vanishing: an argv member the host
+ * still receives, but which the user was never shown, is a surface consented to
+ * unseen. Never throws — a circular or BigInt member must not break the prompt.
+ */
+function renderArgForHuman(arg) {
+    if (typeof arg === 'string')
+        return arg;
+    if (typeof arg === 'bigint')
+        return `<${String(arg)}n>`;
+    try {
+        const json = JSON.stringify(arg);
+        return json === undefined ? `<${typeof arg}>` : `<${json}>`;
+    }
+    catch {
+        return `<${typeof arg}>`;
+    }
+}
+/** `::1`, its expanded forms, and IPv4-mapped loopback (`::ffff:127.0.0.1`). */
+function isLoopbackIpv6(host) {
+    if (!host.includes(':'))
+        return false;
+    if (host === '::1')
+        return true;
+    const mapped = /^::ffff:(.+)$/i.exec(host);
+    if (mapped)
+        return isLoopbackIpv4(mapped[1]);
+    const groups = host.split(':').filter((g) => g !== '');
+    if (groups.length === 0)
+        return false;
+    return groups.every((g, i) => (i === groups.length - 1 ? /^0*1$/.test(g) : /^0*$/.test(g)));
+}
+/**
+ * 127.0.0.0/8 under inet_aton semantics, which is what a browser, curl and the
+ * OS resolver all accept. `127.1`, `2130706433`, `0x7f000001` and `0177.0.0.1`
+ * are every bit as loopback as `127.0.0.1`; a disclosure that flags only the
+ * dotted-quad form understates a local destination for the other four.
+ */
+function isLoopbackIpv4(host) {
+    const parts = host.split('.');
+    if (parts.length < 1 || parts.length > 4)
+        return false;
+    const nums = [];
+    for (const part of parts) {
+        let n;
+        if (/^0[xX][0-9a-fA-F]+$/.test(part))
+            n = parseInt(part, 16);
+        else if (/^0[0-7]+$/.test(part))
+            n = parseInt(part, 8);
+        else if (/^\d+$/.test(part))
+            n = parseInt(part, 10);
+        else
+            return false;
+        if (!Number.isFinite(n) || n < 0)
+            return false;
+        nums.push(n);
+    }
+    // inet_aton: the final part absorbs every remaining octet.
+    let addr;
+    if (nums.length === 1)
+        addr = nums[0];
+    else if (nums.length === 2)
+        addr = ((nums[0] & 0xff) * 0x1000000) + (nums[1] & 0xffffff);
+    else if (nums.length === 3)
+        addr = ((nums[0] & 0xff) * 0x1000000) + ((nums[1] & 0xff) * 0x10000) + (nums[2] & 0xffff);
+    else
+        addr = ((nums[0] & 0xff) * 0x1000000) + ((nums[1] & 0xff) * 0x10000) + ((nums[2] & 0xff) * 0x100) + (nums[3] & 0xff);
+    if (!Number.isFinite(addr) || addr < 0 || addr > 0xffffffff)
+        return false;
+    return Math.floor(addr / 0x1000000) === 127;
+}
+/**
+ * Collect the `hooks` executable-surface class: [{ event, script }] — scripts run as runtime hook
+ * commands. Extracted from the former monolithic `discloseExecutableSurfaces` (ADR-2782 #2796,
+ * cyclomatic 51 / cognitive 99 / 110 lines / `risk_level: critical`) — BEHAVIOR UNCHANGED, only
+ * isolated so it is independently testable and the orchestrator shrinks instead of growing a fourth
+ * class inline. `missingArtifacts` is a shared accumulator the orchestrator passes to every collector
+ * that can populate it.
+ */
+function collectHookSurfaces(manifest, stagedDir, missingArtifacts) {
     const hooks = [];
-    const commandModules = [];
-    const mcpServers = [];
-    const missingArtifacts = [];
-    // hooks: [{ event, script }]
     if (Array.isArray(manifest.hooks)) {
         for (const h of manifest.hooks) {
             if (typeof h !== 'object' || h === null)
@@ -76,7 +247,14 @@ function discloseExecutableSurfaces(manifest, stagedDir) {
             }
         }
     }
-    // commands: [{ family, module, router? }]
+    return hooks;
+}
+/**
+ * Collect the `commands` executable-surface class: [{ family, module, router? }] — modules
+ * require()'d into the GSD CLI process. Extracted, BEHAVIOR UNCHANGED — see `collectHookSurfaces`.
+ */
+function collectCommandSurfaces(manifest, stagedDir, missingArtifacts) {
+    const commandModules = [];
     if (Array.isArray(manifest.commands)) {
         for (const c of manifest.commands) {
             if (typeof c !== 'object' || c === null)
@@ -94,9 +272,20 @@ function discloseExecutableSurfaces(manifest, stagedDir) {
             }
         }
     }
-    // mcpServers: object map { name: { command, args } } OR array [{ name, command, args }]
-    // (or array [{ name, config: { command, args } }]). Capture the COMMAND, not just the name —
-    // the command is the executable that actually runs, and consent must disclose it (Codex R1 H1).
+    return commandModules;
+}
+/**
+ * Collect the `mcpServers` executable-surface class: object map { name: { command, args } } OR
+ * array [{ name, command, args }] (or array [{ name, config: { command, args } }]). Captures the
+ * COMMAND, not just the name — the command is the executable that actually runs, and consent must
+ * disclose it (Codex R1 H1). Extracted, BEHAVIOR UNCHANGED — see `collectHookSurfaces`. Unlike
+ * hooks/commands, an MCP server's command is never existence-checked against `stagedDir` (exactly
+ * like a reviewer lane's `binary` — see `collectReviewerLaneSurfaces` — it may be any PATH
+ * executable, not necessarily a bundle artifact), so this collector takes no `missingArtifacts`
+ * accumulator.
+ */
+function collectMcpSurfaces(manifest) {
+    const mcpServers = [];
     if (manifest.mcpServers && typeof manifest.mcpServers === 'object') {
         const pushServer = (name, config) => {
             if (!name)
@@ -169,8 +358,152 @@ function discloseExecutableSurfaces(manifest, stagedDir) {
             }
         }
     }
-    const hasExecutable = hooks.length > 0 || commandModules.length > 0 || mcpServers.length > 0;
-    return { hooks, commandModules, mcpServers, hasExecutable, missingArtifacts };
+    return mcpServers;
+}
+/**
+ * Collect the reviewer-lane executable-surface class (ADR-2782 D5, #2796): 0 or 1 entries, since a
+ * capability manifest carries AT MOST ONE `reviewer` body (Phase 2's validator rejects an array
+ * shape outright — matrix C2b). The array return shape matches the other three collectors so
+ * `Disclosure`/`disclosureSignature` treat it uniformly (sort-then-fold), even though today it can
+ * never hold more than one entry.
+ *
+ * TOTAL and absent-safe (matrix C1–C5): no `reviewer` key, `reviewer: null`, a non-object body
+ * (array/boolean/number), a malformed `invoke`, non-array `flags`, or the whole manifest being a
+ * throwing Proxy/getter all degrade to "no lane" rather than throwing — disclosure runs BEFORE
+ * Phase 2's validation, on a manifest validation would reject outright.
+ *
+ * `resolveHost` is optional — supplied by the lifecycle (never the loader, which has no config
+ * access) to disclose the REAL destination of an `openai-http` lane to a human at install/upgrade
+ * time. Its return value is NEVER folded into `disclosureSignature` (design constraint 2: the
+ * signature must stay a pure function of the manifest, or the loader and lifecycle would compute
+ * different signatures for the same manifest and produce a permanent false re-consent loop).
+ */
+function collectReviewerLaneSurfaces(manifest, resolveHost) {
+    return safeCollect(() => {
+        const r = manifest.reviewer;
+        // C1 (no reviewer key) / C2a (null) / C2b (non-object: array, boolean, number) all disclose no
+        // lane — never an error at this layer. Validation of a malformed body is Phase 2's job.
+        if (typeof r !== 'object' || r === null || Array.isArray(r))
+            return [];
+        const rec = r;
+        const slug = asString(rec['slug']);
+        const transport = asString(rec['transport']);
+        const handler = asString(rec['handler']);
+        // C3: `invoke` absent/malformed still discloses a lane, with empty binary/args/rawArgs rather
+        // than crashing — validating `invoke`'s shape is Phase 2's job, not disclosure's.
+        const invokeRaw = rec['invoke'];
+        const invoke = (typeof invokeRaw === 'object' && invokeRaw !== null && !Array.isArray(invokeRaw))
+            ? invokeRaw
+            : {};
+        const binary = asString(invoke['binary']);
+        // B1b: the RAW declared args (may contain non-strings the host still receives) is what the
+        // signature binds; `args` is the string-filtered RENDERED view for a human summary — the exact
+        // argv/rawArgs split MCP servers already use for the same reason (TRUST2-4, #1459).
+        const rawArgsDeclared = Array.isArray(invoke['args']) ? invoke['args'] : [];
+        const args = rawArgsDeclared.filter((a) => typeof a === 'string');
+        const hostConfigKey = asString(invoke['hostConfigKey']);
+        const promptChannel = asString(invoke['promptChannel']);
+        // An EMPTY (or wholly unrecognised) reviewer body declares no lane and must
+        // not be treated as one. Without this, `reviewer: {}` alone flips
+        // hasExecutable true and perturbs the disclosure signature — producing a
+        // re-consent prompt whose only content is "(no binary declared)". That is a
+        // prompt carrying no security information, which is exactly the
+        // click-through-training harm this design refuses for reviewsSection and
+        // timeoutFloorMs; refusing it there and permitting it here would be
+        // inconsistent.
+        //
+        // The test is deliberately BROAD — any one recognised field with a value is
+        // enough. Requiring specifically a binary, or specifically a slug, would let
+        // a lane declaring only the other slip through unconsented, which is the far
+        // worse failure.
+        const declaresSomething = Boolean(slug || transport || handler || binary || hostConfigKey || promptChannel
+            || rawArgsDeclared.length > 0);
+        if (!declaresSomething)
+            return [];
+        // B2/B3/B4: resolvedHost/isLocalDestination are only meaningful for an openai-http lane — a
+        // spawn lane has no destination concept, so both stay at their inapplicable defaults ('' /
+        // false), mirroring McpServerSurface's existing empty-when-inapplicable convention (e.g.
+        // `url: ''` for a stdio server). For openai-http, resolvedHost never ends up '' — it is either a
+        // real resolved value or the explicit UNRESOLVED_HOST_MARKER (never a blank read as "no
+        // destination").
+        // The shape test is deliberately WIDER than an exact transport match, and the
+        // human summary uses the same one. Disclosure runs BEFORE validation, so a
+        // mis-cased or unrecognised `transport` reaches here; keying only on the exact
+        // string would leave a lane that plainly declares a hostConfigKey with a BLANK
+        // destination, which reads as "no destination" — the precise thing B3 forbids.
+        const hasHttpShape = transport === 'openai-http' || (!binary && Boolean(hostConfigKey));
+        let resolvedHost = '';
+        let isLocalDestination = false;
+        if (hasHttpShape) {
+            resolvedHost = UNRESOLVED_HOST_MARKER;
+            if (typeof resolveHost === 'function') {
+                let resolved;
+                try {
+                    resolved = resolveHost(hostConfigKey);
+                }
+                catch {
+                    resolved = undefined;
+                }
+                if (typeof resolved === 'string' && resolved)
+                    resolvedHost = resolved;
+            }
+            if (resolvedHost !== UNRESOLVED_HOST_MARKER) {
+                isLocalDestination = isLocalHostValue(resolvedHost);
+            }
+        }
+        const surface = {
+            slug,
+            transport,
+            binary,
+            args,
+            rawArgs: rawArgsDeclared,
+            hostConfigKey,
+            resolvedHost,
+            isLocalDestination,
+            promptChannel,
+            handler,
+            // B5: every lane receives the same named egress payload classes — a fresh copy per surface so
+            // no caller can mutate the shared constant through a returned surface.
+            egressPayloadClasses: [...EGRESS_PAYLOAD_CLASSES],
+        };
+        return [surface];
+    }, []);
+}
+/**
+ * Enumerate every executable surface a capability manifest declares.
+ *
+ * Recognizes the FOUR executable surface kinds a capability can ship:
+ *   - `hooks`:    [{ event, script }]              — scripts run as runtime hook commands
+ *   - `commands`: [{ family, module, router? }]    — modules require()'d into the CLI process
+ *   - `mcpServers`: { <name>: {...} } | [{ name }] — servers spawned by the host runtime
+ *   - `reviewer`: { slug, transport, invoke, ... }  — an external reviewer lane (ADR-2782 D5, #2796)
+ *
+ * `mcpServers` is not a first-party capability.json field today, but a third-party manifest may
+ * declare it, so the trust gate discloses it whenever present (honest disclosure over the
+ * narrower first-party schema). Pure: when `stagedDir` is provided, declared hook/command-module
+ * files are existence-checked and any missing ones reported, but nothing is mutated. A reviewer
+ * lane's `binary` is NEVER existence-checked against `stagedDir` (matrix C6) — like an MCP server's
+ * command, it is a PATH lookup on the user's machine, never a bundle artifact; existence-checking it
+ * would block every lane install.
+ *
+ * TOTAL: never throws, for any manifest shape — including a non-object manifest, a Proxy with
+ * throwing traps, or a property with a throwing getter (matrix C5, E2). Disclosure runs BEFORE
+ * Phase 2's validation, on a manifest validation would reject outright, so it must tolerate what
+ * validation does not. Each surface class is collected independently (`safeCollect`) so a hostile
+ * value in ONE class degrades only that class to empty rather than losing the other three.
+ *
+ * `resolveHost` (optional, #2796) is forwarded to `collectReviewerLaneSurfaces` so a caller with
+ * config access (the lifecycle, never the loader — see `signatureForManifest`) can disclose the REAL
+ * destination of an `openai-http` lane. It never affects the returned signature.
+ */
+function discloseExecutableSurfaces(manifest, stagedDir, resolveHost) {
+    const missingArtifacts = [];
+    const hooks = safeCollect(() => collectHookSurfaces(manifest, stagedDir, missingArtifacts), []);
+    const commandModules = safeCollect(() => collectCommandSurfaces(manifest, stagedDir, missingArtifacts), []);
+    const mcpServers = safeCollect(() => collectMcpSurfaces(manifest), []);
+    const reviewerLanes = safeCollect(() => collectReviewerLaneSurfaces(manifest, resolveHost), []);
+    const hasExecutable = hooks.length > 0 || commandModules.length > 0 || mcpServers.length > 0 || reviewerLanes.length > 0;
+    return { hooks, commandModules, mcpServers, reviewerLanes, hasExecutable, missingArtifacts };
 }
 /**
  * Existence-check a manifest-declared artifact path under stagedDir, refusing to follow it
@@ -358,7 +691,7 @@ function checkEngines(manifest, hostVersion) {
  * is defense-in-depth and lets callers surface a compatVersions downgrade hint.
  */
 function evaluateInstallTrust(args) {
-    const { parsed, manifest, stagedDir, strictKnownRegistries, hostVersion } = args;
+    const { parsed, manifest, stagedDir, strictKnownRegistries, hostVersion, resolveHost } = args;
     const blockReasons = [];
     const src = evaluateSourceAllowed(parsed, strictKnownRegistries);
     if (!src.allowed && src.reason)
@@ -375,7 +708,10 @@ function evaluateInstallTrust(args) {
             : '';
         blockReasons.push(`capability requires engines.gsd "${engines.range}" but host is ${hostVersion}${hint}`);
     }
-    const disclosure = discloseExecutableSurfaces(manifest, stagedDir);
+    // #2796: resolveHost is optional and, when supplied, discloses the REAL destination of an
+    // openai-http reviewer lane to the human at install/upgrade time — it never affects the
+    // consent-binding signature (disclosureSignature never reads resolvedHost; design constraint 2).
+    const disclosure = discloseExecutableSurfaces(manifest, stagedDir, resolveHost);
     // A manifest that declares a hook script or command module NOT present in the staged bundle
     // (missing, or escaping the bundle via an absolute/`..` path) is rejected: such an artifact
     // would run from outside the integrity-pinned, reversible install root. Only enforced when a
@@ -395,15 +731,61 @@ function evaluateInstallTrust(args) {
  * reordering. Used to fold an MCP server's `env` map into the disclosure signature: ADDING or
  * CHANGING any env entry changes the signature (forces re-consent), but merely REORDERING the keys
  * does NOT (no false re-prompt). TRUST-2 (#1459).
+ *
+ * TOTAL (#2796, matrix C5c/E2): a value declared inside an unvalidated manifest — e.g. a reviewer
+ * lane's `invoke.args` — may contain a BigInt (which `JSON.stringify` throws on) or a circular
+ * reference (which unguarded recursion stack-overflows on). Both are handled without throwing:
+ * a BigInt renders as its decimal string; a cycle (an object that is its OWN ancestor in the current
+ * recursion path — tracked via `seen`, added before recursing into children and removed once fully
+ * processed) renders as the literal string `"[Circular]"`. Neither case is reachable for the golden
+ * hooks/mods/mcp fixtures this phase's byte-identity tests pin down, so their output is unaffected.
+ *
+ * KNOWN LIMIT — signature collision on non-JSON numerics (#2796 isolated review, finding E).
+ * `NaN`, `Infinity`, `-Infinity` and `undefined` all render as `null` here, inheriting
+ * `JSON.stringify`'s own coercion. Two materially different manifests could therefore share a
+ * consent signature. This is NOT reachable through any production path: every manifest arrives via
+ * `readManifestBounded`'s strict `JSON.parse`, and the JSON grammar has no `NaN`/`Infinity`/
+ * `undefined` literal — such input throws before disclosure runs. `0` vs `-0` IS expressible in
+ * valid JSON and does collide, but is inert: `String(0) === String(-0)`, so a spawned process
+ * receives identical argv either way.
+ *
+ * Recorded here rather than only in the PR that found it: reachability rests entirely on the ingest
+ * path staying `JSON.parse`-only. Anyone who adds a loader that builds a manifest by other means
+ * (a JS config file, a deserializer, a test double promoted to production) re-opens this, and needs
+ * to see it at the point they would break it.
  */
-function stableJson(value) {
-    if (value === null || typeof value !== 'object')
-        return JSON.stringify(value) ?? 'null';
-    if (Array.isArray(value))
-        return `[${value.map(stableJson).join(',')}]`;
-    const obj = value;
-    const keys = Object.keys(obj).sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableJson(obj[k])}`).join(',')}}`;
+function stableJson(value, seen) {
+    if (typeof value === 'bigint')
+        return JSON.stringify(`${value.toString()}n`);
+    if (value === null || typeof value !== 'object') {
+        try {
+            return JSON.stringify(value) ?? 'null';
+        }
+        catch {
+            // A non-object value whose serialization still throws (defensive; JSON.stringify does not
+            // throw for any other typeof today, but this keeps the contract TOTAL against future engines).
+            return 'null';
+        }
+    }
+    const seenSet = seen ?? new Set();
+    if (seenSet.has(value))
+        return '"[Circular]"';
+    try {
+        seenSet.add(value);
+        if (Array.isArray(value)) {
+            return `[${value.map((v) => stableJson(v, seenSet)).join(',')}]`;
+        }
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${stableJson(obj[k], seenSet)}`).join(',')}}`;
+    }
+    catch {
+        // A Proxy with a throwing trap, or a getter that throws on read — never propagate (matrix C5).
+        return '"[unserializable]"';
+    }
+    finally {
+        seenSet.delete(value);
+    }
 }
 function disclosureSignature(d) {
     // TRUST2-1 (#1459): build EVERY surface line via stableJson of an ARRAY of its components, so each
@@ -441,7 +823,23 @@ function disclosureSignature(d) {
         s.rawConfig || {},
     ]))
         .sort();
-    return JSON.stringify([hooks, mods, mcp]);
+    // ADR-2782 D5 (#2796): fold in slug/transport/binary/rawArgs/hostConfigKey/promptChannel/handler —
+    // every field that changes WHAT runs, WHERE it sends data, or WHAT CODE post-processes its output
+    // (matrix A3–A9). Deliberately ABSENT from this line: `reviewsSection` and `timeoutFloorMs` (matrix
+    // A10/A13 — cosmetic fields; folding them in would force a re-consent prompt that carries no
+    // security information, training users to click through) and the RESOLVED host (design constraint
+    // 2 — the loader has no config resolver and must compute the SAME signature as the lifecycle, or a
+    // resolver-bearing caller and a resolver-less caller would permanently disagree on one manifest's
+    // signature).
+    const lanes = d.reviewerLanes
+        .map((l) => stableJson(['lane', l.slug, l.transport, l.binary, l.rawArgs || [], l.hostConfigKey, l.promptChannel, l.handler]))
+        .sort();
+    // D4.5 (the highest-consequence line in this phase): the lane element is appended ONLY when at
+    // least one lane is declared. A lane-free manifest's signature stays BYTE-IDENTICAL to before this
+    // class existed (matrix A1a/A1b/A1c) — appending unconditionally would change every already-
+    // installed capability's signature and re-prompt every user for every capability on next upgrade,
+    // whether or not they use any reviewer lane at all.
+    return lanes.length > 0 ? JSON.stringify([hooks, mods, mcp, lanes]) : JSON.stringify([hooks, mods, mcp]);
 }
 /**
  * Did the executable surface set change between two versions? Auto-update must re-prompt for
@@ -527,6 +925,36 @@ function summarizeDisclosure(disclosure) {
                 lines.push(`        cwd: ${s.cwd}`);
         }
     }
+    if (disclosure.reviewerLanes.length > 0) {
+        lines.push(`  reviewer lane (${disclosure.reviewerLanes.length}): an external reviewer receives plan/review data on every run`);
+        for (const l of disclosure.reviewerLanes) {
+            // B1/B2/B3/B4: disclose binary+args for a spawn lane, or hostConfigKey+resolved destination
+            // (flagged local when applicable, never omitted as "safe") for an openai-http lane — never
+            // curl/the transport name alone, which would be true and useless (design B2).
+            // Branch on the DECLARED SHAPE, not on an exact transport string. A lane
+            // whose transport is mis-cased or unrecognised still has a hostConfigKey,
+            // and falling through to the spawn branch would print "(no binary
+            // declared)" for a lane that in fact egresses to a live remote host —
+            // understating the disclosure precisely when it matters. Disclosure runs
+            // BEFORE validation, so a non-canonical transport does reach this code.
+            if (l.transport === 'openai-http' || (!l.binary && l.hostConfigKey)) {
+                const localTag = l.isLocalDestination ? ' [local]' : '';
+                lines.push(`    - ${l.slug || '(slug?)'} -> [openai-http] ${l.hostConfigKey || '(hostConfigKey?)'} => ${l.resolvedHost}${localTag}`);
+            }
+            else {
+                // Render the RAW declared args, not the string-filtered view. The raw
+                // array is what the host receives and what the consent signature binds,
+                // so a non-string member that is invisible here is a surface the user
+                // consented to without being shown — the opposite of the disclosure's
+                // whole purpose.
+                const cmd = [l.binary, ...l.rawArgs.map(renderArgForHuman)].filter(Boolean).join(' ');
+                lines.push(`    - ${l.slug || '(slug?)'} -> ${cmd || '(no binary declared)'}`);
+            }
+            if (l.handler)
+                lines.push(`        handler: ${l.handler}`);
+            lines.push(`        sends: ${l.egressPayloadClasses.join(', ')}`);
+        }
+    }
     if (disclosure.missingArtifacts.length > 0) {
         lines.push('  WARNING — declared artifacts not found in the staged bundle:');
         for (const a of disclosure.missingArtifacts) {
@@ -538,6 +966,9 @@ function summarizeDisclosure(disclosure) {
 module.exports = {
     RESERVED_NAMESPACES,
     discloseExecutableSurfaces,
+    // #2796: the reviewer-lane collector, exported for independent testability (ADR-2782's own
+    // argument for extracting per-class collectors rather than growing the switch inline).
+    collectReviewerLaneSurfaces,
     checkReservedNamespace,
     evaluateSourceAllowed,
     checkEngines,
@@ -547,4 +978,8 @@ module.exports = {
     // #1459: the consent-binding signature (single source of truth for loader + lifecycle consent).
     disclosureSignature,
     signatureForManifest,
+    // #2796: the non-blank unresolved-host marker and the named egress payload classes, exported so
+    // tests can assert exact equality rather than a loose substring match.
+    UNRESOLVED_HOST_MARKER,
+    EGRESS_PAYLOAD_CLASSES,
 };