@expo/code-review-cli 0.12.2 → 0.12.4

package/build/core/research.js

@@ -1,4 +1,4 @@
-// @ref LLP 0013#query-and-prompt-boundary [implements] — derive identifiers only; validate, bound, and sanitize MCP evidence
+// @ref LLP 0013#query-and-prompt-boundary [implements] — validate, bound, and sanitize reviewer-requested MCP evidence
 // @ref LLP 0013#one-package-two-binaries [implements] — resolve the package-relative MCP entry instead of PATH/configured commands
 // @ref LLP 0013#research-provenance-and-citations [implements] — bounded query/result audit records plus exact citation grounding
 import { existsSync } from "node:fs";
@@ -6,364 +6,15 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { z } from "zod";
 import { readResearchAudit } from "../research-mcp/audit.js";
-import { run } from "./exec.js";
 export { OPENCODE_RESEARCH_TOOLS } from "./tools.js";
+export const RESEARCH_DECISION_COUNT_LIMIT = 16;
+export const RESEARCH_DECISION_BYTES_LIMIT = 20_000;
 export const RESEARCH_MCP_SERVER_NAME = "platform_docs";
 export const CLAUDE_RESEARCH_TOOLS = [
     `mcp__${RESEARCH_MCP_SERVER_NAME}__search_platform_docs`,
     `mcp__${RESEARCH_MCP_SERVER_NAME}__fetch_platform_doc`,
 ];
-const APPLE_EXTENSIONS = /\.(?:swift|m|mm)$/i;
-const ANDROID_EXTENSIONS = /\.(?:kt|java|gradle|gradle\.kts)$/i;
-const REACT_NATIVE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
-const QUERY_TOKEN = /[A-Za-z][A-Za-z0-9_.:-]{1,79}/g;
-const MAX_ANALYZED_PATCH_LINE_LENGTH = 4096;
-const TYPE_TOKEN = /\b[A-Z][A-Za-z0-9_]{2,}(?:\.[A-Za-z_][A-Za-z0-9_]*)*/g;
-const MEMBER_TOKEN = /\.([a-z][A-Za-z0-9_]{3,})\s*(?:\(|\b)/g;
-const ECOSYSTEM_CALL_TOKEN = /\b((?:create|enable|make|measure|run|schedule|scrollTo|use|with)[A-Z][A-Za-z0-9_]*)\s*\(/g;
-const IGNORED_TYPES = new Set([
-    "Array",
-    "Bool",
-    "Boolean",
-    "Class",
-    "Data",
-    "Double",
-    "Error",
-    "Exception",
-    "Float",
-    "Int",
-    "Integer",
-    "List",
-    "Long",
-    "Map",
-    "Object",
-    "Promise",
-    "Set",
-    "String",
-    "URL",
-    "Unit",
-]);
-const IGNORED_MEMBERS = new Set([
-    "apply",
-    "build",
-    "copy",
-    "equals",
-    "filter",
-    "first",
-    "get",
-    "hashCode",
-    "invoke",
-    "last",
-    "let",
-    "map",
-    "remove",
-    "run",
-    "set",
-    "toString",
-]);
-function startsModuleSpecifier(code) {
-    return /(?:\b(?:from|import)\s*|\brequire\s*\(\s*)$/.test(code);
-}
-function analyzePatchLine(source, state, collectProviderSignals, providerSignals) {
-    let code = "";
-    const finishModuleSpecifier = () => {
-        const value = state.moduleSpecifier;
-        if (value && /^[A-Za-z0-9@._/+~-]{1,200}$/.test(value))
-            providerSignals.push(value);
-        state.moduleSpecifier = null;
-    };
-    for (let index = 0; index < source.length;) {
-        if (state.mode === "block-comment") {
-            if (source.startsWith("*/", index)) {
-                state.mode = "code";
-                code += "  ";
-                index += 2;
-            }
-            else {
-                code += " ";
-                index++;
-            }
-            continue;
-        }
-        if (state.mode === "triple-single-quote" || state.mode === "triple-double-quote") {
-            const delimiter = state.mode === "triple-single-quote" ? "'''" : '"""';
-            if (source.startsWith(delimiter, index)) {
-                state.mode = "code";
-                code += "   ";
-                index += 3;
-            }
-            else {
-                code += " ";
-                index++;
-            }
-            continue;
-        }
-        if (state.mode === "single-quote" ||
-            state.mode === "double-quote" ||
-            state.mode === "template") {
-            const delimiter = state.mode === "single-quote" ? "'" : state.mode === "double-quote" ? '"' : "`";
-            const character = source[index];
-            if (state.escaped) {
-                if (state.moduleSpecifier !== null)
-                    state.moduleSpecifier += character;
-                state.escaped = false;
-                code += " ";
-                index++;
-            }
-            else if (character === "\\") {
-                state.escaped = true;
-                code += " ";
-                index++;
-            }
-            else if (character === delimiter) {
-                finishModuleSpecifier();
-                state.mode = "code";
-                code += " ";
-                index++;
-            }
-            else {
-                if (state.moduleSpecifier !== null)
-                    state.moduleSpecifier += character;
-                code += " ";
-                index++;
-            }
-            continue;
-        }
-        if (source.startsWith("//", index)) {
-            code += " ".repeat(source.length - index);
-            break;
-        }
-        if (source.startsWith("/*", index)) {
-            state.mode = "block-comment";
-            code += "  ";
-            index += 2;
-            continue;
-        }
-        if (source.startsWith("'''", index) || source.startsWith('"""', index)) {
-            state.mode = source.startsWith("'''", index) ? "triple-single-quote" : "triple-double-quote";
-            state.moduleSpecifier = null;
-            code += "   ";
-            index += 3;
-            continue;
-        }
-        const character = source[index];
-        if (character === "'" || character === '"' || character === "`") {
-            state.mode =
-                character === "'" ? "single-quote" : character === '"' ? "double-quote" : "template";
-            state.escaped = false;
-            state.moduleSpecifier =
-                collectProviderSignals && character !== "`" && startsModuleSpecifier(code) ? "" : null;
-            code += " ";
-            index++;
-            continue;
-        }
-        code += character;
-        index++;
-    }
-    // JavaScript/TypeScript, Swift, and Kotlin single/double-quoted strings do not
-    // continue onto the next physical line unless the final character escapes the
-    // newline. Reset malformed prose-like quotes (notably JSX apostrophes) here so
-    // they cannot invert how later patch lines are classified. Templates, triple
-    // quotes, and block comments intentionally retain their multiline state.
-    const continuesQuotedLine = (state.mode === "single-quote" || state.mode === "double-quote") && state.escaped;
-    if ((state.mode === "single-quote" || state.mode === "double-quote") && !continuesQuotedLine) {
-        state.mode = "code";
-        state.moduleSpecifier = null;
-    }
-    state.escaped = false;
-    return code.trim();
-}
-/**
- * Analyze the resulting side of a unified diff while keeping lexical state across
- * lines. Provider routing may retain only import/require module specifiers; those
- * strings are kept separate and can never become outbound query text.
- */
-function analyzeAddedPatch(patch) {
-    const codeLines = [];
-    const providerSignals = [];
-    const state = { mode: "code", escaped: false, moduleSpecifier: null };
-    for (const patchLine of patch.split("\n")) {
-        if (patchLine.startsWith("@@")) {
-            state.mode = "code";
-            state.escaped = false;
-            state.moduleSpecifier = null;
-            continue;
-        }
-        if (patchLine.startsWith("+++") || patchLine.startsWith("---"))
-            continue;
-        const isAdded = patchLine.startsWith("+");
-        const isContext = patchLine.startsWith(" ");
-        if (!isAdded && !isContext)
-            continue;
-        const source = patchLine.slice(1);
-        if (source.length > MAX_ANALYZED_PATCH_LINE_LENGTH) {
-            // A quote startsModuleSpecifier check examines the accumulated line prefix.
-            // Stop this file before an attacker-controlled giant line can turn that
-            // bounded research prepass into quadratic work. Abandoning later lines also
-            // avoids guessing whether the skipped input opened a multiline literal.
-            break;
-        }
-        const code = analyzePatchLine(source, state, isAdded, providerSignals);
-        if (isAdded && code)
-            codeLines.push(code);
-    }
-    return {
-        codeLines,
-        providerSignals: providerSignals.join("\n").slice(0, 256_000).toLowerCase(),
-    };
-}
-function normalizeQuery(parts) {
-    const tokens = parts.join(" ").match(QUERY_TOKEN) ?? [];
-    return [...new Set(tokens)].join(" ").slice(0, 120).trim();
-}
-function platformFor(file) {
-    const normalized = file.path.replace(/\\/g, "/");
-    if (APPLE_EXTENSIONS.test(normalized) || /(?:^|\/)ios(?:\/|$)/i.test(normalized)) {
-        return "apple";
-    }
-    if (ANDROID_EXTENSIONS.test(normalized) || /(?:^|\/)android(?:\/|$)/i.test(normalized)) {
-        return "android";
-    }
-    if (REACT_NATIVE_EXTENSIONS.test(normalized))
-        return "react-native";
-    return null;
-}
-const REACT_NATIVE_PROVIDERS = new Set([
-    "expo",
-    "react-native",
-    "react-native-reanimated",
-    "react-native-gesture-handler",
-    "react-native-screens",
-    "react-native-worklets",
-]);
-function providersFor(file, code, signals) {
-    const path = file.path.toLowerCase();
-    const text = code.toLowerCase();
-    const providers = [];
-    const add = (provider, matches) => {
-        if (matches && !providers.includes(provider))
-            providers.push(provider);
-    };
-    add("react-native-reanimated", /react-native-reanimated/.test(signals) || path.includes("react-native-reanimated"));
-    add("react-native-gesture-handler", /react-native-gesture-handler/.test(signals) || path.includes("react-native-gesture-handler"));
-    add("react-native-screens", /react-native-screens/.test(signals) || path.includes("react-native-screens"));
-    add("react-native-worklets", /react-native-worklets/.test(signals) || path.includes("react-native-worklets"));
-    add("expo", /(?:^|\n)(?:expo|expo-[a-z0-9-]+|@expo\/[a-z0-9-]+)(?:\n|$)/.test(signals) ||
-        /(?:^|\/)packages\/expo(?:-[^/]+)?(?:\/|$)/.test(path));
-    add("react-native", /(?:^|\n)react-native(?:\/[^\n]+)?(?:\n|$)/.test(signals));
-    if (providers.length > 0)
-        return providers;
-    if (/androidx\.media3|mediasessionservice|\bexoplayer\b/.test(text))
-        return ["media3"];
-    if (/com\.bumptech\.glide|\bglide\b/.test(text))
-        return ["glide"];
-    if (/okhttp3|\bokhttpclient\b|\brequest\.builder\b/.test(text))
-        return ["okhttp"];
-    if (/kotlinx\.coroutines|\bcoroutinescope\b|\bmutable(?:state|shared)flow\b/.test(text)) {
-        return ["kotlin-coroutines"];
-    }
-    if (/\.gradle(?:\.kts)?$/.test(path) || /(?:^|\/)build\.gradle/.test(path)) {
-        return /com\.android|android\s*\{|compilesdk|targetsdk/.test(text)
-            ? ["agp", "gradle"]
-            : ["gradle"];
-    }
-    const platform = platformFor(file);
-    if (platform === "apple")
-        return ["apple"];
-    if (platform === "android")
-        return ["android"];
-    return ["react-native"];
-}
-function lineQuery(line) {
-    const declared = line.match(/\b(?:class|struct|enum|interface|protocol)\s+([A-Z][A-Za-z0-9_]*)/)?.[1];
-    const types = [...line.matchAll(TYPE_TOKEN)]
-        .map((match) => match[0])
-        .filter((value) => value !== declared && !IGNORED_TYPES.has(value.split(".")[0]));
-    if (types.length === 0) {
-        const call = [...line.matchAll(ECOSYSTEM_CALL_TOKEN)][0]?.[1];
-        return call ? normalizeQuery([call]) : null;
-    }
-    const members = [...line.matchAll(MEMBER_TOKEN)]
-        .map((match) => match[1])
-        .filter((value) => !IGNORED_MEMBERS.has(value));
-    const primary = types[0];
-    const member = members.find((value) => !primary.toLowerCase().includes(value.toLowerCase()));
-    return normalizeQuery(member ? [primary, member] : [primary]);
-}
-function addQuery(target, seen, platform, providers, query) {
-    const normalized = normalizeQuery([query]);
-    if (!normalized)
-        return;
-    const key = `${platform}|${providers.join(",")}|${normalized.toLowerCase()}`;
-    if (seen.has(key))
-        return;
-    seen.add(key);
-    target.push({ platform, providers, query: normalized });
-}
-/**
- * Derive bounded documentation searches from code identifiers only. String literals,
- * comments, removed lines, paths, and raw source snippets never become query text.
- */
-export function deriveResearchQueries(files, maxQueries = 8) {
-    const queries = [];
-    const seen = new Set();
-    for (const file of files) {
-        const platform = platformFor(file);
-        if (!platform)
-            continue;
-        const { codeLines: lines, providerSignals } = analyzeAddedPatch(file.patch);
-        const code = lines.join("\n").slice(0, 256_000);
-        const providers = providersFor(file, code, providerSignals);
-        for (const provider of providers) {
-            let addedForProvider = 0;
-            for (const line of lines) {
-                const query = lineQuery(line);
-                if (!query)
-                    continue;
-                const before = queries.length;
-                addQuery(queries, seen, REACT_NATIVE_PROVIDERS.has(provider) ? "react-native" : platform, [provider], query);
-                if (queries.length > before && ++addedForProvider >= 2)
-                    break;
-                if (queries.length >= maxQueries)
-                    return queries;
-            }
-        }
-        if (platform === "apple" &&
-            /\b(?:actor|MainActor|Sendable|TaskGroup|Task\.sleep)\b/.test(code)) {
-            const concept = code.match(/\b(?:MainActor|Sendable|TaskGroup|actor|Task\.sleep)\b/)?.[0];
-            if (concept)
-                addQuery(queries, seen, "apple", ["swift-evolution"], concept);
-        }
-        if (platform === "android" && /\b(?:VERSION_CODES|SDK_INT|targetSdk|compileSdk)\b/.test(code)) {
-            const api = code.match(/\b(?:VERSION_CODES(?:\.[A-Z_]+)?|SDK_INT|targetSdk|compileSdk)\b/)?.[0];
-            if (api)
-                addQuery(queries, seen, "android", ["android-releases"], api);
-        }
-        if (queries.length >= maxQueries)
-            return queries.slice(0, maxQueries);
-    }
-    return queries.slice(0, maxQueries);
-}
-const ToolResultSchema = z.object({
-    content: z.array(z.object({
-        type: z.string(),
-        text: z.string().optional(),
-    })),
-});
-const SearchPayloadSchema = z.object({
-    warnings: z.array(z.string().max(500)).max(10).optional(),
-    results: z.array(z.object({
-        id: z.string().min(1).max(240).optional(),
-        provider: z.string().min(1).max(80),
-        sourceKind: z.string().min(1).max(80),
-        title: z.string().min(1).max(500),
-        url: z.string().url().max(2_000),
-        passage: z.string().max(5_000),
-        availability: z.array(z.string().max(240)).max(20).optional(),
-    })),
-});
 const RESEARCH_PROXY_ENV_KEYS = [
     "HTTP_PROXY",
     "HTTPS_PROXY",
@@ -440,7 +91,7 @@ export async function createResearchMcpRuntime(config) {
     };
 }
 export async function researchProvenanceFromAudit(auditPath) {
-    const records = await readResearchAudit(auditPath);
+    const { records, rejections } = await readResearchAudit(auditPath);
     const queries = [];
     const evidence = [];
     const warnings = [];
@@ -478,9 +129,22 @@ export async function researchProvenanceFromAudit(auditPath) {
         queries,
         evidence,
         warnings: [...new Set(warnings)].slice(0, 10),
-        promptText: "",
     };
-    return { provenance: toResearchProvenance(run), evidence };
+    const provenance = toResearchProvenance(run);
+    if (rejections.length > 0) {
+        const counts = new Map();
+        for (const rejection of rejections) {
+            const key = `${rejection.tool}\0${rejection.reason}`;
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        provenance.rejections = [...counts.entries()]
+            .map(([key, count]) => {
+            const [tool = "", reason = ""] = key.split("\0");
+            return { tool: cleanEvidenceText(tool, 80), reason: cleanEvidenceText(reason, 80), count };
+        })
+            .sort((left, right) => `${left.tool}${left.reason}`.localeCompare(`${right.tool}${right.reason}`));
+    }
+    return { provenance, evidence };
 }
 function cleanEvidenceText(value, maxLength) {
     return (value
@@ -492,25 +156,6 @@ function cleanEvidenceText(value, maxLength) {
         .slice(0, maxLength)
         .trim());
 }
-export function formatResearchEvidence(evidence) {
-    if (evidence.length === 0)
-        return "";
-    const body = evidence
-        .map((item) => {
-        const availability = item.availability?.length
-            ? `\nAvailability: ${cleanEvidenceText(item.availability.join(", "), 500)}`
-            : "";
-        return [
-            `Query: ${cleanEvidenceText(item.query.query, 120)}`,
-            `Provider: ${cleanEvidenceText(item.provider, 80)} (${cleanEvidenceText(item.sourceKind, 80)})`,
-            `Source: ${cleanEvidenceText(item.title, 240)} — ${item.url}${availability}`,
-            "Passage:",
-            cleanEvidenceText(item.passage, 1200),
-        ].join("\n");
-    })
-        .join("\n\n");
-    return cleanEvidenceText(body, 16_000);
-}
 function researchQueryKey(query) {
     return `${query.platform}\0${query.providers.join(",")}\0${query.query}`;
 }
@@ -524,7 +169,7 @@ export function toResearchProvenance(run) {
             sourceKind: cleanEvidenceText(item.sourceKind, 80),
             title: cleanEvidenceText(item.title, 240),
             url: item.url,
-            passage: cleanEvidenceText(item.passage, 1_200),
+            passage: cleanEvidenceText(item.passage, 20_000),
             ...(item.availability?.length
                 ? { availability: item.availability.map((value) => cleanEvidenceText(value, 240)) }
                 : {}),
@@ -554,6 +199,9 @@ export function formatResearchProgress(provenance) {
             lines.push(`    result: ${cleanEvidenceText(result.title, 160)} (${result.provider}/${result.sourceKind}) — ${result.url}`);
         }
     }
+    for (const rejection of provenance.rejections ?? []) {
+        lines.push(`  research: ${rejection.count} ${rejection.tool} call(s) rejected before execution (${rejection.reason})`);
+    }
     for (const warning of provenance.warnings) {
         lines.push(`  research warning: ${cleanEvidenceText(warning, 500)}`);
     }
@@ -594,6 +242,9 @@ export function renderResearchMarkdown(provenance) {
             lines.push(`  - [${escapeMarkdownLabel(result.title)}](<${result.url}>) — ${escapeMarkdownLabel(result.provider)}/${escapeMarkdownLabel(result.sourceKind)}`);
         }
     }
+    for (const rejection of provenance.rejections ?? []) {
+        lines.push(`- ⚠️ ${rejection.count} \`${escapeMarkdownLabel(rejection.tool)}\` call(s) rejected before execution (${escapeMarkdownLabel(rejection.reason)}).`);
+    }
     for (const warning of provenance.warnings) {
         lines.push(`- ⚠️ ${escapeMarkdownLabel(warning)}`);
     }
@@ -614,108 +265,158 @@ export function mergeResearchSources(...groups) {
     })
         .slice(0, 5);
 }
-/** Keep only exact URLs returned by the trusted research prepass and restore their canonical titles. */
+/**
+ * Fragment-insensitive lookup key. Models frequently normalize a copied URL by
+ * dropping its `#fragment`; the page identity is unchanged, so a fragment
+ * mismatch must not silently discard an otherwise exact citation. The audited
+ * URL (never the model's variant) is always what gets restored.
+ */
+function citationKey(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.hash = "";
+        return parsed.href;
+    }
+    catch {
+        return url;
+    }
+}
+/** Exact-URL map plus a fragment-insensitive fallback; first audited entry wins. */
+function allowedSourceMaps(evidence) {
+    const exact = new Map();
+    const byKey = new Map();
+    for (const item of evidence) {
+        const canonical = { title: cleanEvidenceText(item.title, 240), url: item.url };
+        if (!exact.has(item.url))
+            exact.set(item.url, canonical);
+        const key = citationKey(item.url);
+        if (!byKey.has(key))
+            byKey.set(key, canonical);
+    }
+    return { exact, byKey };
+}
+function resolveClaimedSource(source, maps) {
+    return maps.exact.get(source.url) ?? maps.byKey.get(citationKey(source.url));
+}
+/** Keep only audited URLs from this review's MCP calls and restore canonical titles. */
 export function groundResearchSources(findings, evidence) {
-    const allowed = new Map(evidence.map((item) => [
-        item.url,
-        { title: cleanEvidenceText(item.title, 240), url: item.url },
-    ]));
+    const maps = allowedSourceMaps(evidence);
     return findings.map((finding) => {
         const { sources: claimed, ...withoutSources } = finding;
         const sources = mergeResearchSources(claimed?.flatMap((source) => {
-            const canonical = allowed.get(source.url);
+            const canonical = resolveClaimedSource(source, maps);
             return canonical ? [canonical] : [];
         }));
         return sources.length > 0 ? { ...withoutSources, sources } : withoutSources;
     });
 }
-export async function collectPlatformResearch(files, config) {
-    const queries = deriveResearchQueries(files, config.maxQueries);
-    if (!config.enabled || queries.length === 0) {
-        return { queries, evidence: [], warnings: [], promptText: "" };
-    }
-    const calls = queries.map((query, index) => ({
-        jsonrpc: "2.0",
-        id: index + 2,
-        method: "tools/call",
-        params: {
-            name: "search_platform_docs",
-            arguments: {
-                platform: query.platform,
-                providers: query.providers,
-                query: query.query,
-                limit: config.resultsPerQuery,
-            },
-        },
-    }));
-    const messages = [
-        {
-            jsonrpc: "2.0",
-            id: 1,
-            method: "initialize",
-            params: {
-                protocolVersion: "2025-06-18",
-                capabilities: {},
-                clientInfo: { name: "expo-code-review-cli", version: "0.0.0" },
+/**
+ * Keep only reviewer decisions backed by an exact URL from this run's MCP audit.
+ * An ungrounded declaration is discarded so model output cannot inflate usefulness.
+ */
+export function groundResearchDecisions(decisions, evidence, agent) {
+    const maps = allowedSourceMaps(evidence);
+    return decisions.flatMap((decision) => {
+        const sources = mergeResearchSources(decision.sources.flatMap((source) => {
+            const canonical = resolveClaimedSource(source, maps);
+            return canonical ? [canonical] : [];
+        }));
+        if (sources.length === 0)
+            return [];
+        return [
+            {
+                outcome: decision.outcome,
+                summary: cleanEvidenceText(decision.summary, 240),
+                sources,
+                agent: cleanEvidenceText(agent, 120),
             },
-        },
-        { jsonrpc: "2.0", method: "notifications/initialized", params: {} },
-        ...calls,
-    ];
-    const server = bundledResearchServer();
-    const serverArgs = [
-        ...server.args,
-        "serve",
-        ...(config.indexPath ? ["--index", config.indexPath] : []),
-    ];
-    const result = await run(server.command, serverArgs, {
-        input: `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`,
-        cwd: tmpdir(),
-        env: researchChildEnvironment(),
-        timeout: config.timeoutMs,
-        maxBuffer: 2 * 1024 * 1024,
-        check: false,
+        ];
+    });
+}
+/**
+ * Bound the cross-agent decision channel after grounding. Reviewer tasks finish
+ * concurrently, so sort before applying limits to keep the retained set stable.
+ */
+export function boundResearchDecisions(decisions) {
+    const sorted = [...decisions].sort((left, right) => {
+        const leftKey = `${left.agent}\0${left.outcome}\0${left.summary}\0${left.sources[0]?.url ?? ""}`;
+        const rightKey = `${right.agent}\0${right.outcome}\0${right.summary}\0${right.sources[0]?.url ?? ""}`;
+        return leftKey.localeCompare(rightKey);
     });
-    if (result.timedOut)
-        throw new Error("platform research MCP timed out");
-    if (result.overflowed)
-        throw new Error("platform research MCP output exceeded 2 MB");
-    if (result.code !== 0) {
-        throw new Error(`platform research MCP exited ${result.code}: ${result.stderr.slice(0, 500)}`);
+    const kept = sorted.slice(0, RESEARCH_DECISION_COUNT_LIMIT);
+    let omitted = sorted.length - kept.length;
+    while (kept.length > 0 &&
+        Buffer.byteLength(JSON.stringify(kept), "utf8") > RESEARCH_DECISION_BYTES_LIMIT) {
+        kept.pop();
+        omitted++;
     }
-    const responses = new Map();
-    for (const line of result.stdout.split("\n")) {
-        if (!line.trim())
-            continue;
-        const parsed = JSON.parse(line);
-        if (typeof parsed.id === "number") {
-            if (parsed.error)
-                throw new Error(`platform research MCP error for request ${parsed.id}`);
-            responses.set(parsed.id, parsed.result);
-        }
+    return { decisions: kept, omitted };
+}
+/**
+ * Heuristic for external-behavior assertions: an OS-version or API-level claim,
+ * or documented-lifecycle wording. Deliberately narrow — it flags the claim
+ * shapes that most need documentation, not every mention of a platform.
+ */
+const EXTERNAL_CLAIM_PATTERN = /\b(?:iOS|iPadOS|macOS|watchOS|tvOS|visionOS|Android)\s?\d+(?:\.\d+)?\b|\bAPI level\s?\d+\b|\b(?:deprecated|introduced|available|removed)\s+(?:in|since|from|as of)\b|\brequires\s+(?:iOS|iPadOS|macOS|watchOS|tvOS|visionOS|Android|API level|SDK)\b/i;
+/** Final findings asserting external platform behavior with no grounded citation. */
+export function countUngroundedExternalClaims(findings) {
+    return findings.filter((finding) => !finding.sources?.length &&
+        EXTERNAL_CLAIM_PATTERN.test(`${finding.title}\n${finding.rationale}`)).length;
+}
+/** Count unique audited results that materially affected the final review. */
+export function summarizeResearchUsefulness(provenance, findings) {
+    const resultUrls = new Set(provenance.results.map((result) => result.url));
+    const citedUrls = new Set(findings.flatMap((finding) => (finding.sources ?? []).flatMap((source) => (resultUrls.has(source.url) ? [source.url] : []))));
+    const decisions = provenance.decisions ?? [];
+    const decisionUrls = new Set(decisions.flatMap((decision) => decision.sources.flatMap((source) => (resultUrls.has(source.url) ? [source.url] : []))));
+    const utilizedUrls = new Set([...citedUrls, ...decisionUrls]);
+    return {
+        finalFindingsWithSources: findings.filter((finding) => (finding.sources ?? []).some((source) => resultUrls.has(source.url))).length,
+        citedResultCount: citedUrls.size,
+        supportedFindingCandidates: decisions.filter((decision) => decision.outcome === "supported-finding").length,
+        dismissedCandidates: decisions.filter((decision) => decision.outcome === "dismissed-candidate")
+            .length,
+        decisionResultCount: decisionUrls.size,
+        utilizedResultCount: utilizedUrls.size,
+        unusedResultCount: Math.max(0, resultUrls.size - utilizedUrls.size),
+        externalClaimFindingsWithoutSources: countUngroundedExternalClaims(findings),
+    };
+}
+export function formatResearchUsefulness(usefulness) {
+    const ungrounded = usefulness.externalClaimFindingsWithoutSources > 0
+        ? `; ${usefulness.externalClaimFindingsWithoutSources} finding(s) assert external platform behavior without a citation`
+        : "";
+    return (`  research usefulness: ${usefulness.finalFindingsWithSources} final finding(s) cited ` +
+        `${usefulness.citedResultCount} unique result(s); ` +
+        `${usefulness.supportedFindingCandidates} supported and ` +
+        `${usefulness.dismissedCandidates} dismissed candidate(s); ` +
+        `${usefulness.utilizedResultCount} result(s) materially used, ` +
+        `${usefulness.unusedResultCount} unused${ungrounded}`);
+}
+export function renderResearchUsefulnessMarkdown(provenance) {
+    const usefulness = provenance.usefulness;
+    if (!usefulness)
+        return "";
+    const totalUniqueResults = usefulness.utilizedResultCount + usefulness.unusedResultCount;
+    const lines = [
+        "### 📚 Documentation research usefulness",
+        "",
+        `- Final findings with grounded citations: **${usefulness.finalFindingsWithSources}**`,
+        `- Unique results cited by final findings: **${usefulness.citedResultCount}**`,
+        `- Candidate decisions: **${usefulness.supportedFindingCandidates} supported**, **${usefulness.dismissedCandidates} dismissed**`,
+        `- Unique results materially used: **${usefulness.utilizedResultCount}/${totalUniqueResults}**`,
+    ];
+    if (usefulness.externalClaimFindingsWithoutSources > 0) {
+        lines.push(`- ⚠️ Findings asserting external platform behavior without a citation: **${usefulness.externalClaimFindingsWithoutSources}**`);
     }
-    if (!responses.has(1))
-        throw new Error("platform research MCP did not initialize");
-    const evidence = [];
-    const warnings = [];
-    for (let index = 0; index < queries.length; index++) {
-        const query = queries[index];
-        const toolResult = ToolResultSchema.parse(responses.get(index + 2));
-        const text = toolResult.content.find((block) => block.type === "text")?.text;
-        if (!text)
-            continue;
-        const payload = SearchPayloadSchema.parse(JSON.parse(text));
-        warnings.push(...(payload.warnings ?? []).map((warning) => cleanEvidenceText(warning, 500)).filter(Boolean));
-        for (const item of payload.results.slice(0, config.resultsPerQuery)) {
-            if (!item.url.startsWith("https://") || !query.providers.includes(item.provider))
-                continue;
-            evidence.push({ query, ...item });
+    if (provenance.decisions?.length) {
+        lines.push("", "Grounded candidate decisions:");
+        for (const decision of provenance.decisions) {
+            const sources = decision.sources
+                .map((source) => `[${escapeMarkdownLabel(source.title)}](<${source.url}>)`)
+                .join(", ");
+            lines.push(`- **${decision.outcome === "supported-finding" ? "Supported finding" : "Dismissed candidate"}** (${escapeMarkdownLabel(decision.agent)}): ${escapeMarkdownLabel(decision.summary)} — ${sources}`);
         }
     }
-    return {
-        queries,
-        evidence,
-        warnings: [...new Set(warnings)].slice(0, 10),
-        promptText: formatResearchEvidence(evidence),
-    };
+    return lines.join("\n");
 }