@expo/code-review-cli 0.12.4 → 0.12.6

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
@@ -298,14 +325,11 @@ downloads the fixed official `lysine.dev` static search index, validates and ind
 it in memory once per MCP process, and rejects any entry outside the existing OkHttp
 allowlist. Brave remains a fallback if that official index is unavailable.
 
-An absolute `research.indexPath` remains available as an optional local fallback.
-The MCP and its trusted updater ship with ECR: build that fallback from this
-repository with `bun run research:update`, or from an installed package with
-`review-research-mcp update`. This is operator/scheduled offline tooling, not a
-step to run before each review. The built-in seed catalog lives in
-`research/sources.json`; `seedUrls` are deterministic starting pages for the
-bounded crawler, and extraction/indexing use no LLM. Installations requiring a fully
-offline review can supply a separately built, verified index and omit the Brave key.
+There is no offline index. Every passage a review sees is fetched live from the
+provider allowlist during that review, so evidence is never served from a local
+artifact whose contents ECR cannot vouch for. The crawler, its seed catalog, and
+`research.indexPath` were removed once live discovery replaced them; a config still
+naming `indexPath` fails to parse rather than silently ignoring it.
 Installation-specific provider configuration is intentionally
 deferred: when added, it should follow the trusted root-config model used for agents
 without permitting PR-controlled URLs, commands, or executable parsers. Expo skills

package/build/commands/ci.js

@@ -463,10 +463,10 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
     // Dynamic stack context and model-backed reply adjudication have inputs outside
     // the scoped diff. Keep those paths fresh until their inputs join the cache key.
     // A maintainer's explicit /review is also always a real rerun.
-    // Research output depends on the mounted index contents, not merely its configured
-    // path. Until a signed index digest joins the cache key, a researched review must
-    // run fresh rather than reuse evidence from an older artifact at the same path.
-    const cacheAllowed = !bypassTriggerGate && !stack && !feedback && !config.research.enabled && metadata !== undefined;
+    // Research no longer forces a fresh run: with the local index gone, every result
+    // is fetched live from an allowlisted host during the run, so there is no mounted
+    // artifact whose contents could drift out from under the cache key.
+    const cacheAllowed = !bypassTriggerGate && !stack && !feedback && metadata !== undefined;
     let inputHash;
     try {
         if (cacheAllowed) {

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/config/schema.js

@@ -61,10 +61,13 @@ export const ReviewConfigSchema = z.object({
     research: z
         .object({
         enabled: z.boolean().default(false),
+        // Removed with the offline index. An unknown key would be stripped silently,
+        // so name it explicitly: a config carrying it is stale, and quietly ignoring
+        // the setting is worse than refusing to start.
         indexPath: z
-            .string()
-            .min(1)
-            .refine((value) => path.isAbsolute(value), "research.indexPath must be an absolute path")
+            .never({
+            error: "research.indexPath was removed — documentation is now always fetched live from the provider allowlist. Delete this key.",
+        })
             .optional(),
         maxQueries: z.number().int().min(1).max(20).default(8),
         resultsPerQuery: z.number().int().min(1).max(3).default(2),

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)
@@ -59,17 +49,17 @@ export async function createResearchMcpRuntime(config) {
     const auditPath = path.join(directory, "audit.jsonl");
     const claudeConfigPath = path.join(directory, "mcp.json");
     const server = bundledResearchServer();
-    const args = [
-        ...server.args,
-        "serve",
-        ...(config.indexPath ? ["--index", config.indexPath] : []),
-    ];
+    const args = [...server.args, "serve"];
     const child = researchChildEnvironment();
     const environment = Object.fromEntries(Object.entries({
         ...child,
         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 +121,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 +192,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 +240,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,73 @@
+// @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_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

@@ -1,25 +1,18 @@
 #!/usr/bin/env node
-// @ref LLP 0013#one-package-two-binaries [implements] — the package's second binary owns serve/update dispatch
-// @ref LLP 0013#search-fetch-and-optional-index-boundary [implements] — review-facing serve and operator-only update stay separate
-import { parseArgs } from "node:util";
-import { defaultConfigPath } from "./paths.js";
+// @ref LLP 0013#one-package-two-binaries [implements] — the package's second binary serves the bounded MCP
+// @ref LLP 0013#search-fetch-and-optional-index-boundary [implements] — live discovery is the only evidence path
 import { runStdioServer } from "./server.js";
-import { PLATFORMS } from "./types.js";
 function printHelp() {
     process.stdout.write(`review-research-mcp
 
 Usage:
   review-research-mcp [serve]
-  review-research-mcp serve [--index PATH]
-  review-research-mcp update [--config PATH] [--output PATH]
-                             [--platform apple|android|react-native] [--max-pages NUMBER]
 
-The serve command uses BRAVE_SEARCH_API_KEY for scoped web discovery, fetches only
-allowlisted official pages, and optionally falls back to a local index. Expo-provider
-searches use Expo's public documentation index. Its fetch_platform_doc tool can fetch
-one exact allowlisted documentation URL without a search key and return focused,
-section, or bounded-document extracted context. The update command is
-an optional offline crawler for operator-managed fallback indexes.
+The serve command uses BRAVE_SEARCH_API_KEY for scoped web discovery and fetches only
+allowlisted official pages. Expo-provider searches use Expo's public documentation
+index. Its fetch_platform_doc tool can fetch one exact allowlisted documentation URL
+without a search key and return focused, section, or bounded-document extracted
+context.
 `);
 }
 function boundedInteger(name, fallback, minimum, maximum) {
@@ -43,60 +36,22 @@ async function main() {
             printHelp();
             return;
         }
-        const { values } = parseArgs({
-            args: rest,
-            options: {
-                index: { type: "string" },
-            },
-            strict: true,
-        });
-        const indexPath = values.index ?? process.env.REVIEW_RESEARCH_INDEX_PATH;
+        if (rest.length > 0) {
+            throw new Error(`Unexpected argument: ${rest[0]}`);
+        }
         await runStdioServer({
-            ...(indexPath ? { indexPath } : {}),
             ...(process.env.REVIEW_RESEARCH_AUDIT_PATH
                 ? { auditPath: process.env.REVIEW_RESEARCH_AUDIT_PATH }
                 : {}),
             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 }
                 : {}),
         });
         return;
     }
-    if (command === "update") {
-        if (rest.includes("--help") || rest.includes("-h")) {
-            printHelp();
-            return;
-        }
-        const { values } = parseArgs({
-            args: rest,
-            options: {
-                config: { type: "string" },
-                output: { type: "string" },
-                platform: { type: "string", multiple: true },
-                "max-pages": { type: "string" },
-            },
-            strict: true,
-        });
-        const invalidPlatform = values.platform?.find((platform) => !PLATFORMS.includes(platform));
-        if (invalidPlatform) {
-            throw new Error(`Unknown platform: ${invalidPlatform}`);
-        }
-        const maxPages = values["max-pages"] ? Number(values["max-pages"]) : undefined;
-        if (maxPages !== undefined && (!Number.isInteger(maxPages) || maxPages < 1)) {
-            throw new Error("--max-pages must be a positive integer");
-        }
-        const { updateDocumentationIndex } = await import("./crawler.js");
-        const result = await updateDocumentationIndex({
-            configPath: values.config ?? defaultConfigPath,
-            ...(values.output ? { outputPath: values.output } : {}),
-            ...(values.platform ? { platforms: values.platform } : {}),
-            ...(maxPages ? { maxPagesPerProvider: maxPages } : {}),
-        });
-        process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
-        return;
-    }
     throw new Error(`Unknown command: ${command}`);
 }
 main().catch((error) => {

package/build/research-mcp/direct-fetch.js

@@ -55,7 +55,7 @@ function withScore(chunk, score = 0) {
 function rankedAnchor(chunks, document, provider, query) {
     if (!query?.trim())
         return chunks[0] ? withScore(chunks[0]) : undefined;
-    const index = buildSearchIndex(chunks, 1);
+    const index = buildSearchIndex(chunks);
     return (searchDocumentation(index, query, {
         platform: document.platform,
         providers: [provider],

package/build/research-mcp/fetch-document.js

@@ -5,9 +5,6 @@ import { resolveAllowedRequestUrl, resolveAllowedUrl, } from "./providers.js";
 import { readBodyWithLimit } from "./response.js";
 import { extractYouTrackIssue } from "./youtrack.js";
 export const onDemandFetchLimits = {
-    maxPagesPerProvider: 10,
-    maxDepth: 0,
-    delayMs: 0,
     timeoutMs: 10_000,
     maxResponseBytes: 5_000_000,
 };

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/okhttp-search.js

@@ -54,7 +54,7 @@ async function loadOkHttpSearchIndex(fetchImplementation) {
         }
     });
     const chunks = documents.flatMap((document) => chunkDocument(document, indexedAt));
-    return buildSearchIndex(chunks, documents.length, indexedAt);
+    return buildSearchIndex(chunks);
 }
 function cachedOkHttpSearchIndex(fetchImplementation) {
     const cached = indexCache.get(fetchImplementation);

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

@@ -101,7 +101,7 @@ function bestPassage(document, query, indexedAt) {
     if (chunks.length === 0) {
         return { passage: document.body.slice(0, 1_400), relevance: 0 };
     }
-    const index = buildSearchIndex(chunks, 1, indexedAt);
+    const index = buildSearchIndex(chunks);
     const result = searchDocumentation(index, query, {
         platform: document.platform,
         providers: document.provider ? [document.provider] : undefined,
@@ -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/search-index.js

@@ -1,5 +1,3 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import path from "node:path";
 import MiniSearch from "minisearch";
 const miniSearchOptions = {
     fields: ["title", "passage", "framework", "symbol", "provider"],
@@ -20,37 +18,15 @@ const miniSearchOptions = {
         "indexedAt",
     ],
 };
-export function buildSearchIndex(chunks, documentCount, generatedAt = new Date().toISOString()) {
+/**
+ * Build a throwaway in-memory index over one fetch's chunks, purely to rank them.
+ * Nothing is serialized or persisted: since the offline index was removed, every
+ * caller builds this per request and discards it.
+ */
+export function buildSearchIndex(chunks) {
     const miniSearch = new MiniSearch(miniSearchOptions);
     miniSearch.addAll(chunks);
-    const providers = [
-        ...new Set(chunks.map((chunk) => chunk.provider ?? chunk.platform)),
-    ].sort();
-    return {
-        miniSearch,
-        serialized: {
-            schemaVersion: 1,
-            generatedAt,
-            documentCount,
-            chunkCount: chunks.length,
-            providers,
-            searchIndex: miniSearch.toJSON(),
-        },
-    };
-}
-export async function writeSearchIndex(filePath, index) {
-    await mkdir(path.dirname(filePath), { recursive: true });
-    const temporaryPath = `${filePath}.tmp-${process.pid}`;
-    await writeFile(temporaryPath, `${JSON.stringify(index)}\n`, { mode: 0o644 });
-    await rename(temporaryPath, filePath);
-}
-export async function loadSearchIndex(filePath) {
-    const serialized = JSON.parse(await readFile(filePath, "utf8"));
-    if (serialized.schemaVersion !== 1 || typeof serialized.searchIndex !== "object") {
-        throw new Error(`Unsupported or invalid search index at ${filePath}`);
-    }
-    const miniSearch = MiniSearch.loadJSON(JSON.stringify(serialized.searchIndex), miniSearchOptions);
-    return { serialized, miniSearch };
+    return { miniSearch };
 }
 function searchOptions(combineWith, exact = false) {
     return {