@expo/code-review-cli 0.12.4 → 0.12.5

package/README.md

@@ -190,7 +190,7 @@ Enable it only in the root config, which CI loads from the PR's trusted base:
     "enabled": true,
     "maxQueries": 8,
     "resultsPerQuery": 2,
-    "timeoutMs": 15000
+    "timeoutMs": 30000
   }
 }
 ```
@@ -205,13 +205,26 @@ the current absolute Node executable, so a PR-owned `PATH` entry cannot replace
 either component. Each review gets an owner-only temporary MCP config and append-only
 audit. Claude receives that explicit config under `--strict-mcp-config`, with project
 settings and slash commands disabled; OpenCode receives the same fixed local command.
-The Brave credential is passed to the MCP child, not the model process.
 
-The MCP is the outbound security boundary. Search queries are normalized before
+That command is a wrapper, not the server. Both engines merge a configured MCP `env`
+onto their own environment instead of replacing it, so the declared block alone cannot
+bound the child — the engine's model credential reaches it, and OpenCode additionally
+passes down the runner's whole ambient environment. The wrapper therefore rebuilds the
+environment from an explicit allowlist before starting the server, and loads no parser
+and opens no socket of its own. The server process sees the search key, the call
+bounds, and locale/proxy settings; it never sees a model credential. The Brave
+credential travels the same way and is never added to the model process env.
+
+The MCP bounds the shape, host, and volume of outbound requests. It is not a
+confidentiality boundary: the reviewing model chooses the query terms and URLs, and a
+low-entropy identifier can carry repository-derived data past every check below.
+Enable research only where repository-derived terms may be shared with Brave and the
+documentation providers. Search queries are normalized before
 logging or networking: quoted literals, URLs, email addresses, paths, prose stop
 words, overlong/high-entropy tokens, and unsupported punctuation are removed;
-credential-shaped or secret-labeled input fails closed. The remaining query must be
-at most eight short tokens and contain an API-like symbol. Direct URLs must use plain
+credential-shaped or secret-labeled input fails closed. The remaining query must be at
+most eight short tokens and either contain an API-like symbol or be a short multi-word
+lowercase concept phrase. Direct URLs must use plain
 HTTPS with no credentials, port, query string, or fragment; suspicious/high-entropy
 path segments fail closed. The fixed provider host/path allowlist and redirect,
 response-size, content-type, and timeout checks still apply after that first gate.
@@ -219,6 +232,17 @@ These deterministic checks greatly reduce accidental exfiltration; they are not
 proof that every low-entropy string is harmless, so reviewer prompts also forbid
 sending repository text and the review-wide MCP budget defaults to eight calls.
 
+`maxQueries` bounds MCP calls, not network requests. One search selects up to four
+providers, and each issues its own discovery request plus a page fetch per candidate,
+so eight calls can mean roughly thirty discovery requests and over a hundred page
+downloads. Every call therefore reports its own ledger — discovery requests, page
+fetches, redirect hops, total HTTP requests, and elapsed time — and the review log and
+Actions summary report the totals. `timeoutMs` is the MCP's own end-to-end deadline for
+one call, enforced by the server across discovery, redirects, retrieval, and
+extraction; a call that hits it returns what it already has rather than failing. It has
+to live there because OpenCode's `timeout` bounds only tool discovery and Claude
+provides no per-call timeout at all.
+
 For non-Expo providers, discovery sends a fixed, provider-owned `site:` scope plus
 the bounded query to Brave's fixed Web Search endpoint. Search snippets and titles
 are never treated as evidence. ECR independently rejects off-allowlist result URLs,
@@ -276,8 +300,11 @@ same audit trail in the step summary, while `.runs/reviews.jsonl` keeps the quer
 plus bounded returned passages for short-lived operational inspection. Reviewers
 are instructed to attach `sources` only when documentation materially supports a
 finding. ECR accepts only exact URLs returned during that review, restores canonical
-titles, carries citations through coordination, and renders them below the finding;
-invented or unrelated citations are dropped.
+titles, carries citations through coordination, and renders them below the finding.
+A citation to a URL this review never retrieved is dropped outright. Relatedness is a
+separate, weaker guarantee: a cited finding is escalated to the verifier with the
+audited passage inline, which judges whether that passage actually supports the claim
+and strips the citation when it does not.
 
 Reviewers also emit a bounded `researchDecisions` record only when documentation
 materially confirms a finding candidate or proves one safe. ECR grounds those records

package/build/config/load.js

@@ -31,7 +31,7 @@ const RESEARCH_CONFIG_DEFAULTS = {
     enabled: false,
     maxQueries: 8,
     resultsPerQuery: 2,
-    timeoutMs: 15_000,
+    timeoutMs: 30_000,
 };
 /** Default OpenCode tool toggles for a reviewer: read the repo, never mutate it. */
 const DEFAULT_AGENT_TOOLS = toolMap(["read", "grep", "glob", "list"]);

package/build/core/research.js

@@ -7,6 +7,8 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readResearchAudit } from "../research-mcp/audit.js";
+import { researchChildEnvironment } from "../research-mcp/child-env.js";
+import { totalResearchNetwork } from "../research-mcp/network.js";
 export { OPENCODE_RESEARCH_TOOLS } from "./tools.js";
 export const RESEARCH_DECISION_COUNT_LIMIT = 16;
 export const RESEARCH_DECISION_BYTES_LIMIT = 20_000;
@@ -15,33 +17,17 @@ export const CLAUDE_RESEARCH_TOOLS = [
     `mcp__${RESEARCH_MCP_SERVER_NAME}__search_platform_docs`,
     `mcp__${RESEARCH_MCP_SERVER_NAME}__fetch_platform_doc`,
 ];
-const RESEARCH_PROXY_ENV_KEYS = [
-    "HTTP_PROXY",
-    "HTTPS_PROXY",
-    "NO_PROXY",
-    "http_proxy",
-    "https_proxy",
-    "no_proxy",
-];
-const RESEARCH_SEARCH_API_KEY = "BRAVE_SEARCH_API_KEY";
-export function researchChildEnvironment(source = process.env) {
-    const environment = {
-        LANG: "C.UTF-8",
-        LC_ALL: "C.UTF-8",
-        ...(process.platform === "win32" && source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}),
-    };
-    for (const key of RESEARCH_PROXY_ENV_KEYS) {
-        if (source[key])
-            environment[key] = source[key];
-    }
-    if (source[RESEARCH_SEARCH_API_KEY]) {
-        environment[RESEARCH_SEARCH_API_KEY] = source[RESEARCH_SEARCH_API_KEY];
-    }
-    return environment;
-}
+export { researchChildEnvironment };
+/**
+ * The engine spawns the WRAPPER, not the server. Both Claude Code and OpenCode
+ * merge the config's `env` block onto their own environment instead of replacing
+ * it, so the block below cannot bound the child on its own; the wrapper rebuilds
+ * the environment from an explicit allowlist before the real server starts. See
+ * research-mcp/wrapper.ts.
+ */
 export function bundledResearchServer() {
-    const builtEntry = fileURLToPath(new URL("../research-mcp/cli.js", import.meta.url));
-    const sourceEntry = fileURLToPath(new URL("../research-mcp/cli.ts", import.meta.url));
+    const builtEntry = fileURLToPath(new URL("../research-mcp/wrapper.js", import.meta.url));
+    const sourceEntry = fileURLToPath(new URL("../research-mcp/wrapper.ts", import.meta.url));
     return {
         command: process.execPath,
         args: [existsSync(builtEntry) ? builtEntry : sourceEntry],
@@ -49,8 +35,12 @@ export function bundledResearchServer() {
 }
 /**
  * Create one owner-only MCP configuration and append-only audit for a review run.
- * The model process receives only the config path; the Brave credential is passed
- * directly to the bounded MCP child and never added to the model process env.
+ * The model process receives only the config path.
+ *
+ * The `env` block below is a request the engine merges rather than applies — see
+ * bundledResearchServer. The wrapper it names is what actually bounds the server's
+ * environment, so the Brave credential and these limits are the only things the
+ * server can see, whatever the engine passed down.
  */
 export async function createResearchMcpRuntime(config) {
     if (!config.enabled)
@@ -70,6 +60,10 @@ export async function createResearchMcpRuntime(config) {
         REVIEW_RESEARCH_AUDIT_PATH: auditPath,
         REVIEW_RESEARCH_MAX_CALLS: String(config.maxQueries),
         REVIEW_RESEARCH_MAX_RESULTS: String(config.resultsPerQuery),
+        // The MCP enforces this itself as a per-call deadline. OpenCode's `timeout`
+        // only bounds tool DISCOVERY and Claude has no equivalent, so neither engine
+        // can bound how long a call actually runs — the server has to.
+        REVIEW_RESEARCH_TIMEOUT_MS: String(config.timeoutMs),
     }).flatMap(([key, value]) => (value === undefined ? [] : [[key, value]])));
     await writeFile(claudeConfigPath, `${JSON.stringify({
         mcpServers: {
@@ -131,6 +125,9 @@ export async function researchProvenanceFromAudit(auditPath) {
         warnings: [...new Set(warnings)].slice(0, 10),
     };
     const provenance = toResearchProvenance(run);
+    const ledgers = records.flatMap((record) => (record.network ? [record.network] : []));
+    if (ledgers.length > 0)
+        provenance.network = totalResearchNetwork(ledgers);
     if (rejections.length > 0) {
         const counts = new Map();
         for (const rejection of rejections) {
@@ -199,6 +196,11 @@ export function formatResearchProgress(provenance) {
             lines.push(`    result: ${cleanEvidenceText(result.title, 160)} (${result.provider}/${result.sourceKind}) — ${result.url}`);
         }
     }
+    if (provenance.network) {
+        const { searchRequests, documentRequests, redirects, totalRequests } = provenance.network;
+        lines.push(`  research network: ${searchRequests} search request(s), ${documentRequests} page fetch(es), ` +
+            `${redirects} redirect(s) — ${totalRequests} HTTP request(s) total`);
+    }
     for (const rejection of provenance.rejections ?? []) {
         lines.push(`  research: ${rejection.count} ${rejection.tool} call(s) rejected before execution (${rejection.reason})`);
     }
@@ -242,6 +244,12 @@ export function renderResearchMarkdown(provenance) {
             lines.push(`  - [${escapeMarkdownLabel(result.title)}](<${result.url}>) — ${escapeMarkdownLabel(result.provider)}/${escapeMarkdownLabel(result.sourceKind)}`);
         }
     }
+    if (provenance.network) {
+        const { searchRequests, documentRequests, redirects, totalRequests, elapsedMs } = provenance.network;
+        lines.push("", `Outbound: **${searchRequests}** search request(s), **${documentRequests}** page fetch(es), ` +
+            `**${redirects}** redirect(s) — **${totalRequests}** HTTP request(s) across ` +
+            `${(elapsedMs / 1000).toFixed(1)}s of call time.`);
+    }
     for (const rejection of provenance.rejections ?? []) {
         lines.push(`- ⚠️ ${rejection.count} \`${escapeMarkdownLabel(rejection.tool)}\` call(s) rejected before execution (${escapeMarkdownLabel(rejection.reason)}).`);
     }

package/build/research-mcp/audit.js

@@ -129,7 +129,7 @@ export class ResearchAudit {
         });
         return requestId;
     }
-    async complete(requestId, tool, input, results, warnings = []) {
+    async complete(requestId, tool, input, results, warnings = [], network) {
         await this.append({
             type: "completed",
             requestId,
@@ -137,6 +137,7 @@ export class ResearchAudit {
             input,
             results: results.map(boundedResult),
             warnings: warnings.slice(0, 10).map((warning) => warning.slice(0, 500)),
+            ...(network ? { network } : {}),
             timestamp: new Date().toISOString(),
         });
     }

package/build/research-mcp/child-env.js

@@ -0,0 +1,74 @@
+// @ref LLP 0013#one-package-two-binaries [implements] — the bounded MCP's environment is constructed, never inherited
+/**
+ * The single definition of what the bounded documentation MCP is allowed to see
+ * in its environment.
+ *
+ * Two callers share it, and they need it for different reasons:
+ *
+ *  - `createResearchMcpRuntime` writes `researchChildEnvironment()` into the
+ *    engine's MCP configuration. That block is a REQUEST, not a guarantee: both
+ *    Claude Code and OpenCode merge it onto the environment the engine already
+ *    has rather than replacing it, so the declared allowlist alone never bounds
+ *    the child.
+ *  - `wrapper.ts` applies `researchWrapperEnvironment()` when it spawns the real
+ *    server. That IS the guarantee — the server process is handed a constructed
+ *    environment, so whatever the engine merged in stops at the wrapper.
+ *
+ * Nothing here imports a parser, a network client, or the config schema: the
+ * wrapper must stay loadable without pulling untrusted-content machinery into
+ * the one process that still holds the engine's credentials.
+ */
+const PROXY_ENV_KEYS = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+];
+export const RESEARCH_SEARCH_API_KEY = "BRAVE_SEARCH_API_KEY";
+/**
+ * Bounds ECR sets on the child through the config env block. These are inputs to
+ * the server, so the wrapper must forward them; every one is a number, a path ECR
+ * itself chose, or both, and none is a credential.
+ */
+export const RESEARCH_RUNTIME_ENV_KEYS = [
+    "REVIEW_RESEARCH_AUDIT_PATH",
+    "REVIEW_RESEARCH_INDEX_PATH",
+    "REVIEW_RESEARCH_MAX_CALLS",
+    "REVIEW_RESEARCH_MAX_RESULTS",
+    "REVIEW_RESEARCH_TIMEOUT_MS",
+];
+/**
+ * Locale, proxy configuration, and the search-only credential — the environment
+ * the MCP actually needs to do its job.
+ *
+ * NODE_OPTIONS is deliberately absent: it is arbitrary code injection into the
+ * process that parses untrusted remote documents. So are PATH and HOME — the
+ * wrapper spawns the server by absolute path and the server writes only to the
+ * audit path it is given.
+ */
+export function researchChildEnvironment(source = process.env) {
+    const environment = {
+        LANG: "C.UTF-8",
+        LC_ALL: "C.UTF-8",
+        ...(process.platform === "win32" && source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}),
+    };
+    for (const key of PROXY_ENV_KEYS) {
+        if (source[key])
+            environment[key] = source[key];
+    }
+    if (source[RESEARCH_SEARCH_API_KEY]) {
+        environment[RESEARCH_SEARCH_API_KEY] = source[RESEARCH_SEARCH_API_KEY];
+    }
+    return environment;
+}
+/** The child environment plus the bounds ECR passes through the config block. */
+export function researchWrapperEnvironment(source = process.env) {
+    const environment = researchChildEnvironment(source);
+    for (const key of RESEARCH_RUNTIME_ENV_KEYS) {
+        if (source[key] !== undefined)
+            environment[key] = source[key];
+    }
+    return environment;
+}

package/build/research-mcp/cli.js

@@ -58,6 +58,7 @@ async function main() {
                 : {}),
             maxCalls: boundedInteger("REVIEW_RESEARCH_MAX_CALLS", 8, 1, 20),
             maxResultsPerCall: boundedInteger("REVIEW_RESEARCH_MAX_RESULTS", 3, 1, 3),
+            timeoutMs: boundedInteger("REVIEW_RESEARCH_TIMEOUT_MS", 30_000, 1_000, 60_000),
             ...(process.env.BRAVE_SEARCH_API_KEY
                 ? { braveApiKey: process.env.BRAVE_SEARCH_API_KEY }
                 : {}),

package/build/research-mcp/network.js

@@ -0,0 +1,75 @@
+/** Discovery endpoints. Everything else is a documentation page or asset. */
+const SEARCH_ENDPOINTS = [
+    "https://api.search.brave.com/",
+    "https://qex7pb7d46-dsn.algolia.net/",
+    "https://lysine.dev/okhttp/search/search_index.json",
+];
+export class ResearchDeadlineError extends Error {
+    constructor(timeoutMs) {
+        super(`Documentation research call exceeded its ${timeoutMs}ms deadline`);
+        this.name = "ResearchDeadlineError";
+    }
+}
+export function createResearchNetwork(base, timeoutMs) {
+    const startedAt = Date.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new ResearchDeadlineError(timeoutMs)), timeoutMs);
+    // The MCP is a short-lived stdio process; never hold the loop open for this.
+    timer.unref?.();
+    let searchRequests = 0;
+    let documentRequests = 0;
+    let redirects = 0;
+    let totalRequests = 0;
+    const wrapped = async (input, init) => {
+        if (controller.signal.aborted)
+            throw new ResearchDeadlineError(timeoutMs);
+        const href = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const isSearch = SEARCH_ENDPOINTS.some((endpoint) => href.startsWith(endpoint));
+        totalRequests++;
+        if (isSearch)
+            searchRequests++;
+        else
+            documentRequests++;
+        // Keep the caller's own per-attempt timeout AND add the call deadline, so a
+        // single slow hop still fails fast while the whole call stays bounded.
+        const signal = init?.signal
+            ? AbortSignal.any([init.signal, controller.signal])
+            : controller.signal;
+        const response = await base(input, { ...init, signal });
+        if (response.status >= 300 && response.status < 400) {
+            redirects++;
+            // A redirect hop is a round trip, not a distinct resource, so undo the
+            // classification count. It has to be the SAME counter that was
+            // incremented: the search backends use `redirect: "manual"` too and treat
+            // a 3xx as an error, so unconditionally decrementing documentRequests
+            // drives it negative the first time a discovery endpoint redirects.
+            if (isSearch)
+                searchRequests--;
+            else
+                documentRequests--;
+        }
+        return response;
+    };
+    return {
+        fetch: wrapped,
+        signal: controller.signal,
+        expired: () => controller.signal.aborted,
+        counts: () => ({
+            searchRequests,
+            documentRequests,
+            redirects,
+            totalRequests,
+            elapsedMs: Date.now() - startedAt,
+        }),
+    };
+}
+/** Sum per-call ledgers into one review-wide total. */
+export function totalResearchNetwork(counts) {
+    return counts.reduce((total, entry) => ({
+        searchRequests: total.searchRequests + entry.searchRequests,
+        documentRequests: total.documentRequests + entry.documentRequests,
+        redirects: total.redirects + entry.redirects,
+        totalRequests: total.totalRequests + entry.totalRequests,
+        elapsedMs: total.elapsedMs + entry.elapsedMs,
+    }), { searchRequests: 0, documentRequests: 0, redirects: 0, totalRequests: 0, elapsedMs: 0 });
+}

package/build/research-mcp/remote-search.js

@@ -175,7 +175,9 @@ export async function searchRemoteDocumentation(providerId, query, limit, option
     // downloading every discovery candidate.
     const fetched = [];
     let candidateIndex = 0;
-    while (fetched.length < limit && candidateIndex < candidates.length) {
+    while (fetched.length < limit &&
+        candidateIndex < candidates.length &&
+        !options.deadline?.aborted) {
         const outstanding = limit - fetched.length;
         const batch = candidates.slice(candidateIndex, candidateIndex + outstanding);
         candidateIndex += batch.length;

package/build/research-mcp/server.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ResearchAudit } from "./audit.js";
+import { createResearchNetwork } from "./network.js";
 import { sanitizeDocumentationQuery } from "./query-sanitizer.js";
 import { DIRECT_DOCUMENT_CONTEXT_MODES, fetchDocumentationUrl, resolveDirectDocumentationTarget, } from "./direct-fetch.js";
 import { searchExpoAlgolia } from "./expo-algolia.js";
@@ -26,7 +27,9 @@ export async function createDocumentationServer(options = {}) {
     const index = options.indexPath ? await loadSearchIndex(options.indexPath) : undefined;
     const maxCalls = Math.min(20, Math.max(1, options.maxCalls ?? 8));
     const maxResultsPerCall = Math.min(3, Math.max(1, options.maxResultsPerCall ?? 3));
+    const timeoutMs = Math.min(60_000, Math.max(1_000, options.timeoutMs ?? 30_000));
     const audit = new ResearchAudit(options.auditPath, maxCalls);
+    const baseFetch = options.fetchImplementation ?? fetch;
     const server = new McpServer({
         name: "review-research-mcp",
         version: "0.2.0",
@@ -89,6 +92,8 @@ export async function createDocumentationServer(options = {}) {
             query: sanitizedQuery,
         };
         const requestId = await audit.reserve("search_platform_docs", auditInput);
+        // One deadline and one request ledger for everything this call issues.
+        const network = createResearchNetwork(baseFetch, timeoutMs);
         try {
             const localResults = index
                 ? searchDocumentation(index, sanitizedQuery, {
@@ -114,7 +119,7 @@ export async function createDocumentationServer(options = {}) {
                         };
                     }
                     try {
-                        const documents = await searchExpoAlgolia(sanitizedQuery, perProviderLimit, options.fetchImplementation ?? fetch);
+                        const documents = await searchExpoAlgolia(sanitizedQuery, perProviderLimit, network.fetch);
                         return {
                             results: documents.map((document, position) => ({
                                 id: `expo-algolia:${document.url}`,
@@ -142,7 +147,7 @@ export async function createDocumentationServer(options = {}) {
                     (!sourceKinds || sourceKinds.includes("official-guide")) &&
                     !language) {
                     try {
-                        const results = await searchOkHttpDocumentation(sanitizedQuery, perProviderLimit, options.fetchImplementation ?? fetch);
+                        const results = await searchOkHttpDocumentation(sanitizedQuery, perProviderLimit, network.fetch);
                         if (results.length > 0) {
                             return { results, warnings: [] };
                         }
@@ -163,9 +168,8 @@ export async function createDocumentationServer(options = {}) {
                 try {
                     return await searchRemoteDocumentation(provider, sanitizedQuery, perProviderLimit, {
                         apiKey: options.braveApiKey,
-                        ...(options.fetchImplementation
-                            ? { fetchImplementation: options.fetchImplementation }
-                            : {}),
+                        fetchImplementation: network.fetch,
+                        deadline: network.signal,
                         ...(language ? { language } : {}),
                         ...(sourceKinds ? { sourceKinds } : {}),
                     });
@@ -201,10 +205,13 @@ export async function createDocumentationServer(options = {}) {
             })
                 .slice(0, boundedLimit);
             const uniqueWarnings = [...new Set(warnings)].slice(0, 10);
+            const network_ = network.counts();
             const payload = {
                 notice: untrustedMaterialNotice,
                 retrieval: {
                     scopedWebSearch: Boolean(options.braveApiKey),
+                    // What this single budget unit actually cost.
+                    network: network_,
                     expoSearch: selectedProviders.includes("expo"),
                     localIndex: index
                         ? {
@@ -216,7 +223,7 @@ export async function createDocumentationServer(options = {}) {
                 ...(uniqueWarnings.length > 0 ? { warnings: uniqueWarnings } : {}),
                 results,
             };
-            await audit.complete(requestId, "search_platform_docs", auditInput, results, uniqueWarnings);
+            await audit.complete(requestId, "search_platform_docs", auditInput, results, uniqueWarnings, network_);
             return {
                 content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
             };
@@ -294,16 +301,18 @@ export async function createDocumentationServer(options = {}) {
             context,
         };
         const requestId = await audit.reserve("fetch_platform_doc", auditInput);
+        // A single URL still costs up to six round trips through the redirect
+        // chain, so this call needs the same deadline and ledger as a search.
+        const network = createResearchNetwork(baseFetch, timeoutMs);
         try {
             const fetched = await fetchDocumentationUrl(target.url.href, {
                 provider: target.provider,
                 ...(sanitizedQuery ? { query: sanitizedQuery } : {}),
                 context,
                 limit,
-                ...(options.fetchImplementation
-                    ? { fetchImplementation: options.fetchImplementation }
-                    : {}),
+                fetchImplementation: network.fetch,
             });
+            const network_ = network.counts();
             const payload = {
                 notice: untrustedMaterialNotice,
                 retrieval: {
@@ -312,6 +321,7 @@ export async function createDocumentationServer(options = {}) {
                     sourceKind: fetched.sourceKind,
                     canonicalUrl: fetched.canonicalUrl,
                     context: fetched.context,
+                    network: network_,
                 },
                 results: fetched.results,
             };
@@ -320,7 +330,7 @@ export async function createDocumentationServer(options = {}) {
                 platform: getProvider(fetched.provider).platform,
                 providers: [fetched.provider],
                 url: fetched.canonicalUrl,
-            }, fetched.results);
+            }, fetched.results, [], network_);
             return {
                 content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
             };

package/build/research-mcp/wrapper.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// @ref LLP 0013#one-package-two-binaries [implements] — the environment boundary the engine's MCP config cannot provide
+/**
+ * Environment boundary for the bounded documentation MCP.
+ *
+ * ECR declares a minimal `env` in the engine's MCP configuration, but neither
+ * engine treats that as a replacement: Claude Code and OpenCode both MERGE it
+ * onto the environment the engine already holds. Verified by spawning each
+ * engine against a probe MCP that records variable names — the child saw the
+ * engine's model credential on both, and OpenCode additionally passed through
+ * the runner's whole ambient environment.
+ *
+ * So the boundary has to be ours. The engine spawns this wrapper; the wrapper
+ * spawns the real server with an environment it CONSTRUCTS. Whatever the engine
+ * merged in reaches this process and stops here.
+ *
+ * This file deliberately does almost nothing. It loads no HTML/JSON parser and
+ * opens no socket, because it is the one process in the chain that still holds
+ * the engine's credentials. Everything that touches untrusted remote content
+ * runs in the child, which never receives them.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants } from "node:os";
+import { fileURLToPath } from "node:url";
+import { researchWrapperEnvironment } from "./child-env.js";
+const builtEntry = fileURLToPath(new URL("./cli.js", import.meta.url));
+const sourceEntry = fileURLToPath(new URL("./cli.ts", import.meta.url));
+const child = spawn(
+// The current interpreter by absolute path, never a PATH lookup: during a
+// review the cwd is the untrusted PR-head tree.
+process.execPath, [existsSync(builtEntry) ? builtEntry : sourceEntry, ...process.argv.slice(2)], {
+    env: researchWrapperEnvironment(process.env),
+    // The child owns the engine's stdio directly, so the wrapper never sits in
+    // the MCP byte stream and cannot truncate, buffer, or reorder a message.
+    stdio: "inherit",
+});
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+for (const signal of FORWARDED_SIGNALS) {
+    // The engine signals the process it spawned — us. Pass it on, or the server
+    // outlives the review and keeps its audit lock.
+    process.on(signal, () => {
+        child.kill(signal);
+    });
+}
+child.on("error", (error) => {
+    process.stderr.write(`review-research-mcp: failed to start bounded server: ${error.message}\n`);
+    process.exitCode = 1;
+});
+child.on("exit", (code, signal) => {
+    // Report a signal death as the conventional 128+n rather than a silent 0, so a
+    // killed server is distinguishable from a clean shutdown.
+    process.exitCode = signal ? 128 + (constants.signals[signal] ?? 0) : (code ?? 1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {

package/templates/config.jsonc

@@ -26,10 +26,20 @@
 
   // Optional bounded platform research (ROOT-ONLY; off by default). Reviewer and
   // cross-file passes can call ECR's bundled MCP for exact API-symbol searches and
-  // supported documentation URLs. The MCP sanitizes queries, uses fixed provider
-  // allowlists, audits results, and never receives model credentials. BRAVE_SEARCH_API_KEY
-  // enables fixed site-scoped discovery; Expo uses its public documentation search.
-  // indexPath remains an optional offline fallback only.
+  // supported documentation URLs. The MCP uses fixed provider allowlists and audits
+  // every call. It runs behind a wrapper that rebuilds its environment from an
+  // explicit allowlist, because both engines MERGE the configured env onto their own
+  // rather than replacing it — so the server sees the search key and these limits,
+  // and never the model credential. BRAVE_SEARCH_API_KEY enables fixed site-scoped
+  // discovery; Expo uses its public documentation search.
+  //
+  // Queries are shape-checked, not confidentiality-checked: the reviewing model
+  // chooses the outbound terms, so enable this only where repository-derived terms
+  // may be shared with Brave and the documentation providers.
+  //
+  // maxQueries bounds MCP CALLS, not requests — one search can issue a discovery
+  // request per provider plus a page fetch per candidate. timeoutMs is the MCP's own
+  // end-to-end deadline per call. indexPath remains an optional offline fallback.
   // "research": {
   //   "enabled": true,
   //   "maxQueries": 8,