@apmantza/greedysearch-pi 1.9.2 → 2.1.2

package/src/search/research.mjs

@@ -6,23 +6,56 @@
 // no-API browser engines and source fetchers instead of Firecrawl/OpenAI.
 
 import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
 	buildSourceRegistry,
+	classifySourceType,
 	computeCompositeScore,
 	mergeFetchDataIntoSources,
 	normalizeUrl,
 	trimText,
 } from "./sources.mjs";
 import { parseStructuredJson } from "./synthesis.mjs";
+import { RESEARCH_ENGINES } from "./constants.mjs";
 import { runGeminiPrompt } from "./synthesis-runner.mjs";
+import { classifyResearchComplexity } from "./scale-aware.mjs";
+import { runSimpleResearchMode } from "./simple-research.mjs";
+import { createProgressTracker } from "./progress.mjs";
 
 const __dir = fileURLToPath(new URL(".", import.meta.url)).replace(
 	/^\/([A-Z]:)/,
 	"$1",
 );
 const SEARCH_BIN = join(__dir, "..", "..", "bin", "search.mjs");
+const DEFAULT_RESEARCH_BUNDLE_ROOT = join(
+	process.cwd(),
+	".pi",
+	"greedysearch-research",
+);
+
+function slugifyResearchName(value) {
+	const slug = String(value || "research")
+		.toLowerCase()
+		.replaceAll(/[^a-z0-9]+/g, "-")
+		.replaceAll(/^-|-$/g, "")
+		.slice(0, 60);
+	return slug || "research";
+}
+
+function uniqueStrings(items, limit = Infinity) {
+	const seen = new Set();
+	const out = [];
+	for (const item of items || []) {
+		const clean = trimText(String(item || ""), 1000);
+		if (!clean || seen.has(clean)) continue;
+		seen.add(clean);
+		out.push(clean);
+		if (out.length >= limit) break;
+	}
+	return out;
+}
 
 async function fetchMultipleResearchSources(...args) {
 	const { fetchMultipleSources } = await import("./fetch-source.mjs");
@@ -327,22 +360,28 @@ export function buildFallbackQueriesFromGaps(
 ) {
 	const fallbacks = [];
 	const angles = [
-		{ template: (g) => `${g} official documentation`, label: "official docs" },
 		{
-			template: (g) => `${g} GitHub issues discussions`,
+			template: (gap) => `${gap} official documentation`,
+			label: "official docs",
+		},
+		{
+			template: (gap) => `${gap} GitHub issues discussions`,
 			label: "community signals",
 		},
 		{
-			template: (g) => `${g} benchmarks performance comparison`,
+			template: (gap) => `${gap} benchmarks performance comparison`,
 			label: "benchmarks",
 		},
-		{ template: (g) => `${g} limitations risks caveats`, label: "limitations" },
 		{
-			template: (g) => `${g} production deployment experience`,
+			template: (gap) => `${gap} limitations risks caveats`,
+			label: "limitations",
+		},
+		{
+			template: (gap) => `${gap} production deployment experience`,
 			label: "production usage",
 		},
 		{
-			template: (g) => `${originalQuery} ${g} counter evidence`,
+			template: (gap) => `${originalQuery} ${gap} counter evidence`,
 			label: "counter-evidence",
 		},
 	];
@@ -350,7 +389,7 @@ export function buildFallbackQueriesFromGaps(
 	for (let i = 0; i < gaps.length && fallbacks.length < nextBreadth; i++) {
 		const gap = gaps[i];
 		const angle = angles[i % angles.length];
-		const candidate = angle.template(originalQuery, gap);
+		const candidate = angle.template(gap);
 		if (!isDuplicateQuery(candidate, usedQueries, { roundIndex })) {
 			fallbacks.push({
 				query: candidate,
@@ -438,7 +477,9 @@ async function evaluateResearchQuality(
 
 function summarizeEngineAnswers(result) {
 	const summaries = {};
-	for (const engine of ["perplexity", "bing", "google"]) {
+	for (const engine of Object.keys(result || {}).filter(
+		(key) => !key.startsWith("_"),
+	)) {
 		const value = result?.[engine];
 		if (!value) continue;
 		summaries[engine] = value.error
@@ -598,9 +639,10 @@ async function executeResearchAction(
 				engines: ["fetch"],
 				engineCount: 1,
 				perEngine: {},
-				sourceType: classifySourceTypeFromDomain(
+				sourceType: classifySourceType(
 					domain,
 					fetchResult.title || "",
+					fetchResult.finalUrl || normalizedUrl,
 				),
 				isOfficial: false,
 				smartScore: 0,
@@ -737,30 +779,6 @@ function getDomainFromUrl(rawUrl) {
 	}
 }
 
-function classifySourceTypeFromDomain(domain, title = "") {
-	const { matchesDomain, SOCIAL_HOSTS, COMMUNITY_HOSTS, NEWS_HOSTS } =
-		require("./sources.mjs");
-	const lowerTitle = title.toLowerCase();
-
-	if (domain === "github.com" || domain === "gitlab.com") return "repo";
-	if (matchesDomain(domain, SOCIAL_HOSTS)) return "social";
-	if (matchesDomain(domain, COMMUNITY_HOSTS)) return "community";
-	if (matchesDomain(domain, NEWS_HOSTS)) return "news";
-	if (
-		domain.startsWith("docs.") ||
-		domain.startsWith("developer.") ||
-		domain.startsWith("developers.") ||
-		domain.startsWith("api.") ||
-		lowerTitle.includes("documentation") ||
-		lowerTitle.includes("docs") ||
-		lowerTitle.includes("reference")
-	) {
-		return "official-docs";
-	}
-	if (domain.startsWith("blog.")) return "maintainer-blog";
-	return "website";
-}
-
 /**
  * Normalize a GitHub root/tree URL into specific fetchable pages.
  * Expands github.com/owner/repo into [README, CONTRIBUTING, CHANGELOG, key files].
@@ -855,11 +873,161 @@ export function queriesToActions(queries) {
 		.filter((a) => a.query);
 }
 
+function sourceKey(source) {
+	return (
+		normalizeUrl(
+			source?.finalUrl || source?.canonicalUrl || source?.url || "",
+		) ||
+		source?.id ||
+		""
+	);
+}
+
+function buildEvidenceExtractionPrompt(
+	originalQuery,
+	questions,
+	fetchedSources,
+	alreadyExtracted = new Set(),
+) {
+	const openQuestions = (questions || [])
+		.filter((q) => q.status !== "closed")
+		.slice(0, 12)
+		.map((q) => ({ id: q.id, question: q.question }));
+	const sourceSnippets = (fetchedSources || [])
+		.filter((source) => source?.content || source?.snippet)
+		.filter((source) => !alreadyExtracted.has(sourceKey(source)))
+		.slice(0, 6)
+		.map((source, index) => ({
+			id: source.id || `F${index + 1}`,
+			title: source.title || "",
+			url: source.finalUrl || source.url || source.canonicalUrl || "",
+			content: trimText(source.content || source.snippet || "", 5000),
+		}));
+
+	return [
+		"You are doing goal-based evidence extraction for an iterative research run.",
+		"For each source, extract only information that helps answer the open questions.",
+		"Use original wording/details where useful. Do not invent answers; leave questions open if evidence is insufficient.",
+		"If a source answers one or more tracked questions, identify those question IDs explicitly.",
+		"Also propose genuinely new sub-questions discovered from the evidence.",
+		"",
+		`Original research question: ${originalQuery}`,
+		`Open question ledger: ${JSON.stringify(openQuestions, null, 2)}`,
+		`Fetched sources: ${JSON.stringify(sourceSnippets, null, 2)}`,
+		"",
+		"Respond ONLY with JSON wrapped in BEGIN_JSON / END_JSON markers:",
+		"BEGIN_JSON",
+		JSON.stringify(
+			{
+				extractions: [
+					{
+						sourceId: "S1",
+						url: "https://example.com/source",
+						rational: "why this source matters for the goal",
+						evidence:
+							"specific quoted/paraphrased evidence with numbers, dates, caveats",
+						summary: "concise contribution to the research question",
+						answers: [
+							{
+								id: "Q1",
+								evidence: "brief evidence that closes the question",
+							},
+						],
+						newQuestions: ["new sub-question raised by this source"],
+					},
+				],
+			},
+			null,
+			2,
+		),
+		"END_JSON",
+	].join("\n");
+}
+
+function normalizeEvidenceExtractions(payload, fetchedSources) {
+	const raw = Array.isArray(payload?.extractions) ? payload.extractions : [];
+	const byUrl = new Map();
+	const byId = new Map();
+	for (const source of fetchedSources || []) {
+		if (source?.id) byId.set(String(source.id), source);
+		const key = sourceKey(source);
+		if (key) byUrl.set(key, source);
+	}
+	return raw
+		.map((item) => {
+			const source =
+				byId.get(String(item?.sourceId || "")) ||
+				byUrl.get(normalizeUrl(item?.url || "") || "");
+			const sourceId = String(item?.sourceId || source?.id || "");
+			const url = normalizeUrl(
+				item?.url || source?.finalUrl || source?.url || "",
+			);
+			const answers = Array.isArray(item?.answers)
+				? item.answers
+						.map((answer) => ({
+							id: String(answer?.id || ""),
+							evidence: trimText(answer?.evidence || "", 500),
+							sourceIds: [sourceId].filter(Boolean),
+						}))
+						.filter((answer) => answer.id)
+				: [];
+			return {
+				sourceId,
+				url,
+				title: source?.title || item?.title || "",
+				rational: trimText(item?.rational || "", 700),
+				evidence: trimText(item?.evidence || "", 1600),
+				summary: trimText(item?.summary || "", 700),
+				answers,
+				newQuestions: uniqueStrings(item?.newQuestions || [], 6),
+			};
+		})
+		.filter(
+			(item) => item.sourceId || item.url || item.summary || item.evidence,
+		);
+}
+
+export async function extractEvidenceFromSources({
+	query,
+	questions,
+	fetchedSources,
+	extractedSourceKeys,
+}) {
+	const pending = (fetchedSources || []).filter(
+		(source) =>
+			(source?.content || source?.snippet) &&
+			!extractedSourceKeys.has(sourceKey(source)),
+	);
+	if (pending.length === 0) return { evidence: [], error: "" };
+	try {
+		const raw = await runGeminiPrompt(
+			buildEvidenceExtractionPrompt(
+				query,
+				questions,
+				pending,
+				extractedSourceKeys,
+			),
+			{ timeoutMs: 120000 },
+		);
+		const parsed = parseGeminiJson(raw, { extractions: [] });
+		const evidence = normalizeEvidenceExtractions(parsed, pending);
+		for (const source of pending) {
+			const key = sourceKey(source);
+			if (key) extractedSourceKeys.add(key);
+		}
+		return { evidence, error: "" };
+	} catch (error) {
+		return { evidence: [], error: error.message || String(error) };
+	}
+}
+
 function buildLearningPrompt(
 	originalQuery,
 	roundQueries,
 	searchSummaries,
 	fetchedSources,
+	questions = [],
+	evidenceItems = [],
 ) {
 	const sourceSnippets = fetchedSources
 		.filter((source) => source?.content || source?.snippet)
@@ -878,6 +1046,8 @@ function buildLearningPrompt(
 		"",
 		`Original research question: ${originalQuery}`,
 		`Round queries: ${JSON.stringify(roundQueries, null, 2)}`,
+		`Question ledger: ${JSON.stringify(questions, null, 2)}`,
+		`Extracted source evidence: ${JSON.stringify(evidenceItems.slice(-12), null, 2)}`,
 		`Engine summaries: ${JSON.stringify(searchSummaries, null, 2)}`,
 		`Fetched source snippets: ${JSON.stringify(sourceSnippets, null, 2)}`,
 		"",
@@ -886,6 +1056,14 @@ function buildLearningPrompt(
 		JSON.stringify(
 			{
 				learnings: ["concise, information-dense learning"],
+				answeredQuestions: [
+					{
+						id: "Q1",
+						evidence: "brief evidence that closes this question",
+						sourceIds: ["S1"],
+					},
+				],
+				newQuestions: ["new sub-question discovered from the evidence"],
 				followUpQueries: ["specific next search query"],
 				gaps: ["important uncertainty or missing evidence"],
 			},
@@ -896,7 +1074,13 @@ function buildLearningPrompt(
 	].join("\n");
 }
 
-function buildFinalReportPrompt(originalQuery, rounds, sources) {
+export function buildFinalReportPrompt(
+	originalQuery,
+	rounds,
+	sources,
+	questions = [],
+	evidenceItems = [],
+) {
 	const learnings = rounds.flatMap((round) => round.learnings || []);
 	const gaps = rounds.flatMap((round) => round.gaps || []);
 	const sourceRegistry = sources.slice(0, 12).map((source) => ({
@@ -932,6 +1116,8 @@ function buildFinalReportPrompt(originalQuery, rounds, sources) {
 		`Original research question: ${originalQuery}`,
 		`Learnings: ${JSON.stringify(learnings, null, 2)}`,
 		`Known gaps/caveats: ${JSON.stringify(gaps, null, 2)}`,
+		`Question ledger: ${JSON.stringify(questions, null, 2)}`,
+		`Goal-based extracted evidence: ${JSON.stringify(evidenceItems.slice(-20), null, 2)}`,
 		`Source registry: ${JSON.stringify(sourceRegistry, null, 2)}`,
 		"",
 		"Respond ONLY with JSON wrapped in BEGIN_JSON / END_JSON markers:",
@@ -961,6 +1147,81 @@ function buildFinalReportPrompt(originalQuery, rounds, sources) {
 	].join("\n");
 }
 
+/**
+ * Build a synthesis prompt that derives the final report directly from
+ * previously extracted evidence (no per-round learnings required). This is
+ * used as a fallback when the regular final-report path returns no
+ * structured learnings (for example when Gemini's input field rejected the
+ * per-round learning prompt but the goal-based extraction step succeeded).
+ */
+export function buildSynthesisFromEvidencePrompt(
+	originalQuery,
+	sources = [],
+	questions = [],
+	evidenceItems = [],
+) {
+	const sourceRegistry = sources.slice(0, 12).map((source) => ({
+		id: source.id,
+		title: source.title,
+		domain: source.domain,
+		url: source.canonicalUrl,
+		type: source.sourceType,
+		engines: source.engines,
+	}));
+	const evidenceSlice = evidenceItems.slice(-20);
+	const answerableQuestionIds = new Set();
+	for (const item of evidenceSlice) {
+		for (const ans of item.answers || []) {
+			if (ans?.id) answerableQuestionIds.add(ans.id);
+		}
+	}
+	const openQuestionSummary = (questions || [])
+		.filter((q) => q.status !== "closed")
+		.map((q) => ({ id: q.id, question: q.question }));
+
+	return [
+		"You are writing the final research report from goal-based extracted evidence.",
+		"Per-round learnings were not produced, but the per-source evidence extraction step succeeded.",
+		"Synthesize a thorough markdown report using ONLY the evidence below. Every substantive claim MUST be backed by an [S1] citation.",
+		"",
+		"Report structure:",
+		"1. ## Summary — A 2-4 sentence executive summary of findings",
+		"2. ## Key Findings — The main findings, organized by theme or question, each with inline citations",
+		"3. ## Limitations & Caveats — Important qualifiers, gaps, or uncertainties",
+		"",
+		`Original research question: ${originalQuery}`,
+		`Per-source extracted evidence: ${JSON.stringify(evidenceSlice, null, 2)}`,
+		`Source registry: ${JSON.stringify(sourceRegistry, null, 2)}`,
+		`Questions already answered by the evidence: ${JSON.stringify(Array.from(answerableQuestionIds))}`,
+		`Questions still open after this evidence: ${JSON.stringify(openQuestionSummary)}`,
+		"",
+		"Respond ONLY with JSON wrapped in BEGIN_JSON / END_JSON markers:",
+		"BEGIN_JSON",
+		JSON.stringify(
+			{
+				answer: "markdown report with sections and inline [S1] citations",
+				agreement: {
+					level: "high|medium|low|mixed|conflicting",
+					summary: "one-sentence confidence summary",
+				},
+				differences: ["notable disagreement or conflict between sources"],
+				caveats: ["important caveat or qualification"],
+				claims: [
+					{
+						claim: "specific factual statement supported by the evidence",
+						support: "strong|moderate|weak|conflicting",
+						sourceIds: ["S1", "S2"],
+					},
+				],
+				recommendedSources: ["S1", "S2"],
+			},
+			null,
+			2,
+		),
+		"END_JSON",
+	].join("\n");
+}
+
 async function runFastAllSearch(query, { locale = null, short = true } = {}) {
 	const args = [SEARCH_BIN, "all", "--inline", "--stdin", "--fast"];
 	if (!short) args.push("--full");
@@ -1046,7 +1307,9 @@ function shouldForwardChildStderr(line) {
 	return (
 		/^PROGRESS:/.test(line) ||
 		/^\[greedysearch\]/.test(line) ||
-		/^\[(bing|perplexity|google|gemini)\]/.test(line) ||
+		/^\[(bing|perplexity|google|gemini|chatgpt|logically|semantic-scholar)\]/.test(
+			line,
+		) ||
 		/^GreedySearch Chrome/.test(line) ||
 		/^Launching GreedySearch Chrome/.test(line) ||
 		/^Headless mode/.test(line) ||
@@ -1141,6 +1404,811 @@ export function auditCitations(answer, sources) {
 	};
 }
 
+/**
+ * Check reachability of cited source URLs via HEAD requests.
+ * Returns { reachable, dead, skipped } with per-URL status.
+ */
+export async function checkCitationUrls(
+	sources,
+	{ timeoutMs = 6000, concurrency = 4 } = {},
+) {
+	const safeConcurrency = Math.max(1, Math.floor(concurrency || 1));
+	const citedSources = (sources || []).filter(
+		(s) => s?.id && (s?.canonicalUrl || s?.finalUrl || s?.url),
+	);
+	if (citedSources.length === 0) {
+		return { reachable: [], dead: [], skipped: [], ok: true };
+	}
+
+	const reachable = [];
+	const dead = [];
+	const skipped = [];
+
+	// Process in batches to avoid overwhelming
+	for (let i = 0; i < citedSources.length; i += safeConcurrency) {
+		const batch = citedSources.slice(i, i + safeConcurrency);
+		const results = await Promise.allSettled(
+			batch.map(async (source) => {
+				const url =
+					source.fetch?.finalUrl ||
+					source.canonicalUrl ||
+					source.finalUrl ||
+					source.url;
+				if (!url) return { id: source.id, url: "", status: "skipped" };
+
+				// Skip non-HTTP URLs and known-unreachable patterns
+				try {
+					const parsed = new URL(url);
+					if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+						return { id: source.id, url, status: "skipped" };
+					}
+				} catch {
+					return { id: source.id, url, status: "skipped" };
+				}
+
+				try {
+					const controller = new AbortController();
+					const timer = setTimeout(() => controller.abort(), timeoutMs);
+					try {
+						const response = await fetch(url, {
+							method: "HEAD",
+							redirect: "follow",
+							signal: controller.signal,
+							headers: {
+								"User-Agent":
+									"Mozilla/5.0 (compatible; GreedySearch/2.0; +https://github.com/apmantza/greedysearch-pi)",
+							},
+						});
+						clearTimeout(timer);
+						const ok = response.status >= 200 && response.status < 400;
+						return {
+							id: source.id,
+							url,
+							status: ok ? "reachable" : "dead",
+							httpStatus: response.status,
+						};
+					} catch (fetchError) {
+						clearTimeout(timer);
+						return {
+							id: source.id,
+							url,
+							status: "dead",
+							error:
+								fetchError.name === "AbortError"
+									? "timeout"
+									: fetchError.message,
+						};
+					}
+				} catch (error) {
+					return {
+						id: source.id,
+						url,
+						status: "dead",
+						error: error.message,
+					};
+				}
+			}),
+		);
+
+		for (const result of results) {
+			const value =
+				result.status === "fulfilled"
+					? result.value
+					: {
+							id: "?",
+							url: "",
+							status: "dead",
+							error: result.reason?.message || "unknown",
+						};
+			if (value.status === "reachable") reachable.push(value);
+			else if (value.status === "dead") dead.push(value);
+			else skipped.push(value);
+		}
+	}
+
+	return {
+		reachable,
+		dead,
+		skipped,
+		ok: dead.length === 0,
+	};
+}
+
+/**
+ * Shared orchestration: run citation URL check with logging.
+ * Used by both runResearchMode() and runSimpleResearchMode() to avoid
+ * duplicating the try/catch/logging block.
+ */
+export async function runCitationUrlCheck(combinedSources) {
+	process.stderr.write("PROGRESS:research:check-urls\n");
+	try {
+		const citationUrls = await checkCitationUrls(combinedSources, {
+			timeoutMs: 6000,
+			concurrency: 4,
+		});
+		if (!citationUrls.ok) {
+			process.stderr.write(
+				`[greedysearch] ${citationUrls.dead.length} dead citation URL(s) detected\n`,
+			);
+		}
+		return citationUrls;
+	} catch (error) {
+		process.stderr.write(
+			`[greedysearch] URL reachability check failed: ${error.message}\n`,
+		);
+		return null;
+	}
+}
+
+export function computeResearchFloor({
+	sources = [],
+	fetchedSources = [],
+	synthesis = {},
+	citationAudit = null,
+	gaps = [],
+	questions = [],
+	rounds = [],
+	qualityScore = 0,
+	qualityThreshold = 8.5,
+	maxSources = 8,
+	requireCitations = true,
+	requireQuestions = true,
+} = {}) {
+	const fetchedOk = fetchedSources.filter(
+		(source) =>
+			source?.fetch?.ok ||
+			(source?.contentChars || 0) > 100 ||
+			String(source?.content || "").length > 100,
+	);
+	const primarySources = sources.filter((source) =>
+		["official-docs", "repo", "maintainer-blog", "academic"].includes(
+			String(source?.sourceType || ""),
+		),
+	);
+	const claims = Array.isArray(synthesis?.claims) ? synthesis.claims : [];
+	const citedCount = citationAudit ? citationAudit.cited?.length || 0 : 0;
+	const questionStats = questionProgress(questions);
+	// Follow-up questions discovered during a run are useful handoff gaps, not a
+	// reason to fail a short research run forever. The deterministic floor only
+	// requires the original/root questions to close; newly-created questions stay
+	// visible in STATUS.md and `gaps` for deeper follow-up rounds.
+	const requiredQuestions = (questions || []).filter(
+		(q) => !q.createdRound || q.reason === "Original research question",
+	);
+	const requiredQuestionStats = questionProgress(requiredQuestions);
+	// Scale the minimum fetched sources by the number of rounds. The
+	// simple research path runs 1 round with fewer sources, so requiring
+	// 2-4 sources would be too strict. Iterative research (2+ rounds)
+	// gets the full minFetched requirement.
+	const roundCount = (rounds || []).length;
+	const baseMin = Math.min(4, Math.max(2, Number(maxSources) || 8));
+	const minFetched = roundCount <= 1 ? Math.min(2, baseMin) : baseMin;
+	const checks = {
+		roundsRun: rounds.length >= 1,
+		fetchedSources: fetchedOk.length >= minFetched,
+		primarySources: primarySources.length >= 1,
+		qualityScore: qualityScore >= Math.min(qualityThreshold, 8),
+		claimsExtracted: !requireCitations || claims.length > 0,
+		citationsPresent: !requireCitations || citedCount > 0,
+		citationsValid: !requireCitations || citationAudit?.ok === true,
+		unfetchedCitations:
+			!requireCitations || (citationAudit?.unfetched || []).length === 0,
+		requiredQuestionsClosed:
+			!requireQuestions || requiredQuestionStats.open === 0,
+	};
+	return {
+		floorMet: Object.values(checks).every(Boolean),
+		checks,
+		metrics: {
+			fetchedOk: fetchedOk.length,
+			primarySources: primarySources.length,
+			claims: claims.length,
+			cited: citedCount,
+			gaps: gaps.length,
+			openQuestions: questionStats.open,
+			closedQuestions: questionStats.closed,
+			totalQuestions: questionStats.total,
+			openRequiredQuestions: requiredQuestionStats.open,
+			closedRequiredQuestions: requiredQuestionStats.closed,
+			totalRequiredQuestions: requiredQuestionStats.total,
+			qualityScore,
+			minFetched,
+		},
+	};
+}
+
+function annotateFetchedSourcesWithIds(fetchedSources, sources) {
+	const byUrl = new Map();
+	for (const source of sources || []) {
+		const key = normalizeUrl(
+			source?.canonicalUrl || source?.finalUrl || source?.url,
+		);
+		if (key && source?.id) byUrl.set(key, source.id);
+	}
+	return (fetchedSources || []).map((source, index) => {
+		const key = normalizeUrl(
+			source?.finalUrl || source?.canonicalUrl || source?.url,
+		);
+		return {
+			...source,
+			id: source?.id || byUrl.get(key) || `F${index + 1}`,
+		};
+	});
+}
+
+export function createQuestionLedger(query) {
+	return [
+		{
+			id: "Q1",
+			question: trimText(sanitizeResearchQuery(query), 320),
+			status: "open",
+			reason: "Original research question",
+			evidence: [],
+			sourceIds: [],
+		},
+	];
+}
+
+function nextQuestionId(questions) {
+	let max = 0;
+	for (const q of questions || []) {
+		const n = Number.parseInt(String(q.id || "").replace(/^Q/i, ""), 10);
+		if (Number.isFinite(n)) max = Math.max(max, n);
+	}
+	return `Q${max + 1}`;
+}
+
+function findSimilarQuestion(questions, question) {
+	const normalized = sanitizeResearchQuery(question).toLowerCase();
+	return (questions || []).find(
+		(q) =>
+			q.question?.toLowerCase() === normalized ||
+			jaccardSimilarity(q.question || "", normalized) >= 0.82,
+	);
+}
+
+function addQuestion(questions, question, { reason = "", round = null } = {}) {
+	const clean = trimText(sanitizeResearchQuery(question), 320);
+	if (!clean) return null;
+	const existing = findSimilarQuestion(questions, clean);
+	if (existing) return existing;
+	const item = {
+		id: nextQuestionId(questions),
+		question: clean,
+		status: "open",
+		reason: trimText(reason, 240),
+		createdRound: round,
+		evidence: [],
+		sourceIds: [],
+	};
+	questions.push(item);
+	return item;
+}
+
+function closeQuestion(
+	questions,
+	idOrQuestion,
+	{ evidence = "", sourceIds = [], round = null } = {},
+) {
+	const target =
+		questions.find((q) => q.id === idOrQuestion) ||
+		findSimilarQuestion(questions, idOrQuestion);
+	if (!target) return null;
+	target.status = "closed";
+	target.closedRound = target.closedRound || round;
+	if (evidence)
+		target.evidence = uniqueStrings([...(target.evidence || []), evidence], 4);
+	if (Array.isArray(sourceIds)) {
+		target.sourceIds = uniqueStrings(
+			[...(target.sourceIds || []), ...sourceIds],
+			8,
+		);
+	}
+	return target;
+}
+
+function questionProgress(questions) {
+	const total = questions.length;
+	const closed = questions.filter((q) => q.status === "closed").length;
+	return { total, closed, open: Math.max(0, total - closed) };
+}
+
+export function updateQuestionLedger(
+	questions,
+	{ roundNumber, actions = [], learningPayload = {} } = {},
+) {
+	for (const run of actions) {
+		const action = run?.action || run;
+		const goal =
+			action?.researchGoal && action.researchGoal !== "Original user query"
+				? action.researchGoal
+				: action?.query || action?.url || "";
+		if (goal) {
+			addQuestion(questions, goal, {
+				reason: "Planned research action",
+				round: roundNumber,
+			});
+		}
+	}
+
+	// Cap the open-question ledger growth. Discovered gap/follow-up questions
+	// are useful handoffs but Gemini tends to emit one per evidence slot, which
+	// blows up the ledger and inflates the `requiredQuestionsClosed` floor
+	// check. Keep at most MAX_OPEN_FOLLOWUPS of them across the whole run;
+	// older ones are auto-resolved as "covered by later evidence" so they
+	// don't block the floor forever.
+	const MAX_OPEN_FOLLOWUPS = 5;
+	const followupOpen = questions.filter(
+		(q) => q.status === "open" && q.reason === "Discovered gap/follow-up",
+	);
+	if (followupOpen.length > MAX_OPEN_FOLLOWUPS) {
+		const overflow = followupOpen
+			.sort((a, b) => (a.createdRound || 0) - (b.createdRound || 0))
+			.slice(0, followupOpen.length - MAX_OPEN_FOLLOWUPS);
+		for (const q of overflow) {
+			q.status = "resolved";
+			q.closedRound = roundNumber;
+			q.evidence = uniqueStrings(
+				[...(q.evidence || []), "Auto-resolved to cap open-question ledger"],
+				4,
+			);
+		}
+	}
+
+	const answered = Array.isArray(learningPayload.answeredQuestions)
+		? learningPayload.answeredQuestions
+		: [];
+	for (const item of answered) {
+		if (typeof item === "string") {
+			closeQuestion(questions, item, { round: roundNumber });
+			continue;
+		}
+		const id = item?.id || item?.question;
+		if (!id && item?.question) {
+			const added = addQuestion(questions, item.question, {
+				reason: "Answered during learning extraction",
+				round: roundNumber,
+			});
+			if (added) closeQuestion(questions, added.id, { round: roundNumber });
+			continue;
+		}
+		closeQuestion(questions, id, {
+			evidence: item?.evidence || item?.answer || "",
+			sourceIds: Array.isArray(item?.sourceIds) ? item.sourceIds : [],
+			round: roundNumber,
+		});
+	}
+
+	// Keep STATUS.md as a true question ledger, not a dump of every search query
+	// or caveat. Follow-up queries and raw gaps stay in their own fields; only
+	// explicit newQuestions become open ledger items.
+	const newQuestions = Array.isArray(learningPayload.newQuestions)
+		? learningPayload.newQuestions
+		: [];
+	for (const question of newQuestions) {
+		addQuestion(questions, question, {
+			reason: "Discovered gap/follow-up",
+			round: roundNumber,
+		});
+	}
+
+	return questions;
+}
+
+/**
+ * Pick direct-fetch targets from known academic source domains (arXiv,
+ * semanticscholar.org, DOI redirect). Returns the canonical URL plus a
+ * short label for the researchGoal. Filters out anything already fetched.
+ */
+function pickAcademicFetchTargets(combinedSources, usedUrls) {
+	if (!Array.isArray(combinedSources) || combinedSources.length === 0)
+		return [];
+	const ACADEMIC_HOSTS = ["arxiv.org", "semanticscholar.org", "doi.org"];
+	const seen = new Set();
+	const targets = [];
+	for (const source of combinedSources) {
+		const url = source?.canonicalUrl || source?.finalUrl || source?.url || "";
+		if (!url) continue;
+		let domain = "";
+		try {
+			domain = new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+		} catch {
+			continue;
+		}
+		if (!ACADEMIC_HOSTS.some((h) => domain === h || domain.endsWith(`.${h}`))) {
+			continue;
+		}
+		if (usedUrls.has(url) || seen.has(url)) continue;
+		seen.add(url);
+		// Prefer the HTML/abs page over PDF for direct fetch — the source
+		// fetcher handles both, but the HTML page gives the synthesizer
+		// readable text + abstract immediately.
+		const htmlUrl = url.includes("/pdf/")
+			? url.replace(/\/pdf\//, "/html/").replace(/\.pdf$/i, "")
+			: url;
+		targets.push({
+			url: htmlUrl,
+			label: source?.title || source?.id || domain,
+		});
+	}
+	return targets.slice(0, 2);
+}
+
+export function reconcileQuestionsFromSynthesis(
+	questions,
+	synthesis,
+	citationAudit,
+) {
+	if (!synthesis?.answer || citationAudit?.ok !== true) return questions;
+	const claims = Array.isArray(synthesis.claims) ? synthesis.claims : [];
+	const citedIds = Array.isArray(citationAudit.cited)
+		? citationAudit.cited
+		: [];
+	if (claims.length === 0 || citedIds.length === 0) return questions;
+
+	for (const question of questions) {
+		if (question.status === "closed") continue;
+		let bestClaim = null;
+		let bestScore = 0;
+		for (const claim of claims) {
+			const score = jaccardSimilarity(
+				question.question || "",
+				claim.claim || "",
+			);
+			if (score > bestScore) {
+				bestScore = score;
+				bestClaim = claim;
+			}
+		}
+		if (question.id === "Q1" || bestScore >= 0.18) {
+			closeQuestion(questions, question.id, {
+				evidence: bestClaim?.claim || "Answered in final cited synthesis",
+				sourceIds: Array.isArray(bestClaim?.sourceIds)
+					? bestClaim.sourceIds
+					: citedIds.slice(0, 4),
+			});
+		}
+	}
+	return questions;
+}
+
+function renderQuestionStatus(questions) {
+	if (!questions.length) return "No tracked questions.";
+	return questions
+		.map((q) => {
+			const ids = q.sourceIds?.length ? ` (${q.sourceIds.join(", ")})` : "";
+			return `- [${q.status === "closed" ? "x" : " "}] ${q.id}: ${q.question}${ids}`;
+		})
+		.join("\n");
+}
+
+function markdownList(items, fallback = "None recorded.") {
+	const unique = uniqueStrings(items);
+	return unique.length
+		? unique.map((item) => `- ${item}`).join("\n")
+		: fallback;
+}
+
+/**
+ * Write a human-readable provenance sidecar next to the research bundle.
+ * Records date, rounds, sources, verification status, and floor results.
+ */
+export function writeProvenanceSidecar(
+	dir,
+	{
+		query,
+		rounds,
+		sources,
+		fetchedSources,
+		citationAudit,
+		citationUrls,
+		floor,
+		manifest,
+	},
+) {
+	const fetchedOk = (fetchedSources || []).filter(
+		(s) => s?.contentChars > 100 || s?.fetch?.ok,
+	);
+	const primarySources = (sources || []).filter((s) =>
+		["official-docs", "repo", "maintainer-blog", "academic"].includes(
+			String(s?.sourceType || ""),
+		),
+	);
+	const citedIds = new Set(citationAudit?.cited || []);
+	const citedSources = (sources || []).filter((s) => citedIds.has(s?.id));
+
+	const lines = [
+		`# Provenance: ${query}`,
+		"",
+		`- **Date:** ${manifest?.startedAt || new Date().toISOString()}`,
+		`- **Duration:** ${manifest?.durationMs ? `${(manifest.durationMs / 1000).toFixed(1)}s` : "unknown"}`,
+		`- **Mode:** ${manifest?.terminationReason === "simple_single_pass" ? "simple (single-pass)" : "iterative"}`,
+		`- **Rounds:** ${manifest?.rounds || rounds?.length || 1}`,
+		"",
+		"## Sources",
+		"",
+		`- **Consulted:** ${sources?.length || 0}`,
+		`- **Fetched successfully:** ${fetchedOk.length}`,
+		`- **Primary sources:** ${primarySources.length}`,
+		`- **Cited in report:** ${citedSources.length}`,
+		"",
+	];
+
+	// Cited source details
+	if (citedSources.length > 0) {
+		lines.push("### Cited sources", "");
+		for (const source of citedSources) {
+			const url = source.canonicalUrl || source.finalUrl || source.url || "";
+			const fetched = source.fetch?.ok ? "✓" : "✗";
+			lines.push(
+				`- **${source.id}:** [${source.title || url}](${url}) (${source.sourceType || "unknown"}, fetched: ${fetched})`,
+			);
+		}
+		lines.push("");
+	}
+
+	// URL reachability
+	if (
+		citationUrls &&
+		(citationUrls.reachable.length > 0 || citationUrls.dead.length > 0)
+	) {
+		lines.push("## URL reachability", "");
+		if (citationUrls.dead.length > 0) {
+			lines.push("");
+			lines.push("**Dead links:**");
+			for (const d of citationUrls.dead) {
+				lines.push(
+					`- ${d.id}: ${d.url} (${d.httpStatus || d.error || "unknown"})`,
+				);
+			}
+		}
+		if (citationUrls.reachable.length > 0) {
+			lines.push("");
+			lines.push(
+				`**Reachable:** ${citationUrls.reachable.length}/${citationUrls.reachable.length + citationUrls.dead.length}`,
+			);
+		}
+		lines.push("");
+	}
+
+	// Verification status
+	const verificationStatus = !citationAudit
+		? "NOT CHECKED"
+		: citationAudit.ok && (citationUrls?.ok ?? true)
+			? "PASS"
+			: citationAudit.ok === false
+				? "FAIL (missing citations)"
+				: "FAIL (dead links)";
+
+	lines.push(
+		"## Verification",
+		"",
+		`- **Citations:** ${citationAudit?.ok ? "PASS" : `FAIL — missing: ${(citationAudit?.missing || []).join(", ")}`}`,
+		`- **URL reachability:** ${citationUrls ? (citationUrls.ok ? "PASS" : `FAIL — ${citationUrls.dead.length} dead`) : "SKIPPED"}`,
+		`- **Floor:** ${floor?.floorMet ? "PASS" : "PARTIAL"}`,
+		`- **Overall:** ${verificationStatus}`,
+		"",
+	);
+
+	// Floor checks
+	if (floor?.checks) {
+		lines.push("## Floor checks", "");
+		for (const [name, ok] of Object.entries(floor.checks)) {
+			lines.push(`- [${ok ? "x" : " "}] ${name}`);
+		}
+		lines.push("");
+	}
+
+	writeFileSync(join(dir, "provenance.md"), lines.join("\n"), "utf8");
+}
+
+export async function writeResearchBundle({
+	query,
+	rounds,
+	sources,
+	fetchedSources,
+	evidenceItems = [],
+	synthesis,
+	citationAudit,
+	floor,
+	manifest,
+	allGaps = [],
+	questions = [],
+	citationUrls = null,
+	outDir = null,
+}) {
+	const stamp = new Date().toISOString().replaceAll(/[:.]/g, "-").slice(0, 19);
+	const dir =
+		outDir ||
+		join(
+			DEFAULT_RESEARCH_BUNDLE_ROOT,
+			`${stamp}_${slugifyResearchName(query)}`,
+		);
+	const reportsDir = join(dir, "reports");
+	const sourcesDir = join(dir, "sources");
+	const dataDir = join(dir, "data");
+	mkdirSync(reportsDir, { recursive: true });
+	mkdirSync(sourcesDir, { recursive: true });
+	mkdirSync(dataDir, { recursive: true });
+
+	const sourceFiles = await writeResearchSourcesToFiles(
+		fetchedSources,
+		sourcesDir,
+	);
+	const gaps = uniqueStrings([
+		...allGaps,
+		...rounds.flatMap((round) => round.gaps || []),
+	]);
+	writeFileSync(
+		join(dir, "STATUS.md"),
+		[
+			floor.floorMet ? "STATUS: DONE" : "STATUS: PARTIAL",
+			"",
+			`Query: ${query}`,
+			`Stop reason: ${manifest.terminationReason || "max_rounds"}`,
+			"",
+			"## Deterministic floor checks",
+			...Object.entries(floor.checks).map(
+				([name, ok]) => `- [${ok ? "x" : " "}] ${name}`,
+			),
+			"",
+			"## Questions",
+			renderQuestionStatus(questions),
+			"",
+			"## Open gaps",
+			markdownList(gaps),
+			"",
+		].join("\n"),
+		"utf8",
+	);
+	writeFileSync(
+		join(dir, "OUTLINE.md"),
+		[
+			"# Research bundle outline",
+			"",
+			"- `reports/SUMMARY.md` — final cited report",
+			"- `reports/CLAIMS.md` — extracted claims with support/source IDs",
+			"- `reports/EVIDENCE.md` — goal-based source evidence",
+			"- `reports/GAPS.md` — remaining caveats and uncertainties",
+			"- `provenance.md` — human-readable run metadata and verification",
+			"- `sources/` — fetched source markdown files",
+			"- `data/manifest.json` — machine-readable run metadata",
+			"- `data/rounds.json` — per-round actions/learnings/gaps",
+			"- `data/sources.json` — ranked source registry",
+			"- `data/questions.json` — open/closed question ledger",
+			"",
+		].join("\n"),
+		"utf8",
+	);
+	writeFileSync(
+		join(reportsDir, "SUMMARY.md"),
+		String(synthesis.answer || ""),
+		"utf8",
+	);
+	writeFileSync(
+		join(reportsDir, "CLAIMS.md"),
+		[
+			"# Key claims",
+			"",
+			...(Array.isArray(synthesis.claims) && synthesis.claims.length
+				? synthesis.claims.map((claim) => {
+						const ids = Array.isArray(claim.sourceIds)
+							? claim.sourceIds.join(", ")
+							: "";
+						return `- ${claim.claim || ""} (${claim.support || "support unknown"}${ids ? `; ${ids}` : ""})`;
+					})
+				: ["No structured claims were extracted."]),
+			"",
+		].join("\n"),
+		"utf8",
+	);
+	writeFileSync(
+		join(reportsDir, "EVIDENCE.md"),
+		[
+			"# Extracted evidence",
+			"",
+			...(evidenceItems.length
+				? evidenceItems.map((item) =>
+						[
+							`## ${item.sourceId || item.url || "Source"}`,
+							item.url ? `<${item.url}>` : "",
+							item.rational ? `**Rational:** ${item.rational}` : "",
+							item.evidence ? `**Evidence:** ${item.evidence}` : "",
+							item.summary ? `**Summary:** ${item.summary}` : "",
+							"",
+						]
+							.filter(Boolean)
+							.join("\n"),
+					)
+				: ["No goal-based evidence was extracted."]),
+			"",
+		].join("\n"),
+		"utf8",
+	);
+	writeFileSync(
+		join(reportsDir, "GAPS.md"),
+		[
+			"# Gaps and caveats",
+			"",
+			"## Caveats",
+			markdownList(synthesis.caveats || []),
+			"",
+			"## Research gaps",
+			markdownList(gaps),
+			"",
+		].join("\n"),
+		"utf8",
+	);
+	writeFileSync(
+		join(dataDir, "manifest.json"),
+		JSON.stringify({ ...manifest, floor, citationAudit }, null, 2),
+		"utf8",
+	);
+	writeFileSync(
+		join(dataDir, "rounds.json"),
+		JSON.stringify(rounds, null, 2),
+		"utf8",
+	);
+	writeFileSync(
+		join(dataDir, "sources.json"),
+		JSON.stringify(sources, null, 2),
+		"utf8",
+	);
+	writeFileSync(
+		join(dataDir, "questions.json"),
+		JSON.stringify(questions, null, 2),
+		"utf8",
+	);
+	writeFileSync(
+		join(dataDir, "evidence.json"),
+		JSON.stringify(evidenceItems, null, 2),
+		"utf8",
+	);
+	writeFileSync(
+		join(sourcesDir, "index.md"),
+		[
+			"# Source index",
+			"",
+			...sourceFiles.map((source) => {
+				const label = source.title || source.url;
+				const url = source.finalUrl || source.url;
+				const path = source.contentPath ? ` — ${source.contentPath}` : "";
+				return `- ${source.id || "?"}: [${label}](${url})${path}`;
+			}),
+			"",
+		].join("\n"),
+		"utf8",
+	);
+
+	// Provenance sidecar — human-readable run metadata (non-critical)
+	try {
+		writeProvenanceSidecar(dir, {
+			query,
+			rounds,
+			sources,
+			fetchedSources,
+			citationAudit,
+			citationUrls,
+			floor,
+			manifest,
+		});
+	} catch (sidecarError) {
+		process.stderr.write(
+			`[greedysearch] Provenance sidecar write failed (non-critical): ${sidecarError.message}\n`,
+		);
+	}
+
+	return {
+		dir,
+		statusPath: join(dir, "STATUS.md"),
+		summaryPath: join(reportsDir, "SUMMARY.md"),
+		manifestPath: join(dataDir, "manifest.json"),
+		provenancePath: join(dir, "provenance.md"),
+		sourceCount: sourceFiles.length,
+		sourceFiles,
+	};
+}
+
 export async function runResearchMode({
 	query,
 	breadth = 3,
@@ -1149,14 +2217,63 @@ export async function runResearchMode({
 	locale = null,
 	short = false,
 	qualityThreshold = 8.5,
+	writeBundle = process.env.GREEDY_RESEARCH_BUNDLE !== "0",
+	researchOutDir = null,
 } = {}) {
 	const options = clampResearchOptions({ breadth, iterations, maxSources });
+
+	// ── Scale-aware fast path ────────────────────────────────────────────────
+	// When breadth and iterations are at defaults (not user-specified), classify
+	// the query complexity. Simple queries bypass the iterative loop entirely
+	// for ~70% faster results and lower API cost.
+	const userSpecifiedBreadth = typeof breadth === "number";
+	const userSpecifiedIterations = typeof iterations === "number";
+	const atDefaults = !userSpecifiedBreadth && !userSpecifiedIterations;
+
+	if (atDefaults) {
+		try {
+			const classification = await classifyResearchComplexity(query);
+			process.stderr.write(
+				`[greedysearch] Complexity: ${classification.complexity} (${classification.reasoning})\n`,
+			);
+			if (classification.complexity === "simple") {
+				process.stderr.write(
+					`[greedysearch] Simple query detected — using fast single-pass path\n`,
+				);
+				return runSimpleResearchMode({
+					query,
+					locale,
+					maxSources: Math.min(maxSources ?? 5, 5),
+					qualityThreshold,
+					writeBundle,
+					researchOutDir,
+				});
+			}
+			// For moderate/complex: use classifier suggestions as hints if user
+			// didn't specify values. This tightens the loop for moderate queries
+			// without changing the user-explicit path.
+			if (!userSpecifiedBreadth) {
+				options.breadth = classification.suggestedBreadth;
+			}
+			if (!userSpecifiedIterations) {
+				options.iterations = classification.suggestedIterations;
+			}
+		} catch (error) {
+			process.stderr.write(
+				`[greedysearch] Scale classification failed, using defaults: ${error.message}\n`,
+			);
+		}
+	}
+
 	const rounds = [];
 	let allLearnings = [];
 	let allGaps = [];
+	const questions = createQuestionLedger(query);
 	let activeActions = null;
 	let combinedSources = [];
 	let fetchedSources = [];
+	let evidenceItems = [];
+	const extractedSourceKeys = new Set();
 	const usedQueries = new Set();
 	const usedUrls = new Set();
 	const qualityHistory = [];
@@ -1170,8 +2287,20 @@ export async function runResearchMode({
 	let totalFetches = 0;
 	const engineFailures = [];
 
+	// Progress bar with ETA — pre-compute totals from plan so the bar
+	// reflects the full run, not just the current round. The actual
+	// actions per round come from Gemini's plan; we estimate 1 fetch
+	// per academic source found.
+	const progressTracker = createProgressTracker({
+		totalActions: options.iterations * options.breadth,
+		totalRounds: options.iterations,
+		totalFetches: options.iterations, // estimate: ~1 fetch per round
+		silent: process.env.GREEDY_RESEARCH_QUIET === "1",
+	});
+	progressTracker.startRound(1);
+
 	process.stderr.write(
-		`[greedysearch] Research mode: breadth ${options.breadth}, iterations ${options.iterations}, qualityThreshold ${qualityThreshold}\n`,
+		`[greedysearch] Research mode: breadth ${options.breadth}, iterations ${options.iterations}, qualityThreshold ${qualityThreshold}, engines ${RESEARCH_ENGINES.join(",")}, synthesizer gemini\n`,
 	);
 
 	for (let roundIndex = 0; roundIndex < options.iterations; roundIndex++) {
@@ -1254,6 +2383,26 @@ export async function runResearchMode({
 		});
 
 		const roundActions = noveltyFiltered.slice(0, roundBreadth);
+
+		// Force at least one fetchUrl per round when a known academic source
+		// (arXiv, semantic-scholar, DOI) is present in combinedSources. The
+		// Gemini planner occasionally emits all-search actions even when the
+		// answer is in a single arXiv PDF; direct fetching gives the synthesizer
+		// real PDF text and reliably passes citation audits.
+		const academicTargets = pickAcademicFetchTargets(combinedSources, usedUrls);
+		const hasFetch = roundActions.some((a) => a.type === "fetchUrl");
+		if (!hasFetch && academicTargets.length > 0) {
+			const injectTarget = academicTargets[0];
+			roundActions.push({
+				type: "fetchUrl",
+				url: injectTarget.url,
+				researchGoal: `Direct fetch of known academic source: ${injectTarget.label || injectTarget.url}`,
+			});
+			process.stderr.write(
+				`[greedysearch] Forced fetchUrl for academic source: ${injectTarget.url}\n`,
+			);
+		}
+
 		const actionRuns = [];
 		for (let i = 0; i < roundActions.length; i++) {
 			const action = roundActions[i];
@@ -1263,6 +2412,10 @@ export async function runResearchMode({
 			process.stderr.write(
 				`[greedysearch] Action ${i + 1}/${roundActions.length} [${action.type}]: ${(action.query || action.url).slice(0, 80)}\n`,
 			);
+			progressTracker.startAction(
+				action.type,
+				(action.query || action.url || "").slice(0, 60),
+			);
 			const run = await executeResearchAction(action, {
 				locale,
 				short,
@@ -1270,10 +2423,14 @@ export async function runResearchMode({
 				usedUrls,
 				maxChars: 8000,
 			});
+			progressTracker.endAction();
 			actionRuns.push(run);
 			totalActionsRun++;
 			if (action.type === "search") totalSearches++;
-			if (action.type === "fetchUrl") totalFetches++;
+			if (action.type === "fetchUrl") {
+				totalFetches++;
+				progressTracker.endFetch(run.ok);
+			}
 			if (!run.ok) {
 				engineFailures.push({
 					round: roundNumber,
@@ -1292,6 +2449,7 @@ export async function runResearchMode({
 		const fetchActionRuns = actionRuns.filter(
 			(r) => r.action.type === "fetchUrl",
 		);
+		updateQuestionLedger(questions, { roundNumber, actions: actionRuns });
 
 		combinedSources = dedupeSources([
 			combinedSources,
@@ -1329,6 +2487,33 @@ export async function runResearchMode({
 				fetchedSources,
 			);
 		}
+		fetchedSources = annotateFetchedSourcesWithIds(
+			fetchedSources,
+			combinedSources,
+		);
+
+		process.stderr.write(`PROGRESS:research:round-${roundNumber}:evidence\n`);
+		const evidenceRun = await extractEvidenceFromSources({
+			query,
+			questions,
+			fetchedSources,
+			extractedSourceKeys,
+		});
+		if (evidenceRun.error) {
+			process.stderr.write(
+				`[greedysearch] Evidence extraction failed: ${evidenceRun.error}\n`,
+			);
+		}
+		evidenceItems = [...evidenceItems, ...evidenceRun.evidence];
+		for (const evidence of evidenceRun.evidence) {
+			updateQuestionLedger(questions, {
+				roundNumber,
+				learningPayload: {
+					answeredQuestions: evidence.answers || [],
+					newQuestions: evidence.newQuestions || [],
+				},
+			});
+		}
 
 		// Build round query summary for learning extraction
 		const roundQueries = actionRuns.map((run) => ({
@@ -1351,6 +2536,8 @@ export async function runResearchMode({
 						engines: summarizeEngineAnswers(run.result),
 					})),
 					fetchedSources,
+					questions,
+					evidenceItems,
 				),
 				{ timeoutMs: 120000 },
 			);
@@ -1377,8 +2564,14 @@ export async function runResearchMode({
 					.filter(Boolean)
 					.slice(0, 6)
 			: [];
-		allLearnings = [...new Set([...allLearnings, ...learnings])];
-		allGaps = [...new Set([...allGaps, ...gaps])];
+		allLearnings = uniqueStrings([...allLearnings, ...learnings]);
+		allGaps = uniqueStrings([...allGaps, ...gaps]);
+		updateQuestionLedger(questions, {
+			roundNumber,
+			actions: [],
+			learningPayload,
+			gaps,
+		});
 		rounds.push({
 			round: roundNumber,
 			actions: actionRuns.map((run) => ({
@@ -1391,11 +2584,17 @@ export async function runResearchMode({
 			})),
 			learnings,
 			gaps,
+			evidence: evidenceRun.evidence,
+			evidenceError: evidenceRun.error,
 			learningError,
 		});
 
 		// Quality evaluation
 		process.stderr.write(`PROGRESS:research:round-${roundNumber}:evaluating\n`);
+		progressTracker.endRound();
+		if (roundNumber < options.iterations) {
+			progressTracker.startRound(roundNumber + 1);
+		}
 		const evaluation = await evaluateResearchQuality(
 			query,
 			rounds,
@@ -1404,19 +2603,38 @@ export async function runResearchMode({
 			qualityHistory,
 		);
 		qualityHistory.push(evaluation.score);
+		allGaps = uniqueStrings([...allGaps, ...(evaluation.knowledgeGaps || [])]);
+		updateQuestionLedger(questions, {
+			roundNumber,
+			gaps: evaluation.knowledgeGaps || [],
+		});
+		const preliminaryFloor = computeResearchFloor({
+			sources: combinedSources,
+			fetchedSources,
+			gaps: allGaps,
+			questions,
+			rounds,
+			qualityScore: evaluation.score,
+			qualityThreshold,
+			maxSources: options.maxSources,
+			requireCitations: false,
+			requireQuestions: false,
+		});
 		process.stderr.write(
-			`[greedysearch] Quality score round ${roundNumber}: ${evaluation.score.toFixed(1)} (shouldContinue: ${evaluation.shouldContinue})\n`,
+			`[greedysearch] Quality score round ${roundNumber}: ${evaluation.score.toFixed(1)} (shouldContinue: ${evaluation.shouldContinue}, floor: ${preliminaryFloor.floorMet})\n`,
 		);
 
-		// Early termination
+		// Early termination is outcome-first: Gemini quality alone is not enough.
+		// Stop early only when the score is high AND deterministic source/floor checks pass.
 		if (
 			evaluation.score >= qualityThreshold &&
+			preliminaryFloor.floorMet &&
 			(!evaluation.shouldContinue ||
 				evaluation.terminationReason === "quality_threshold")
 		) {
 			terminationReason = evaluation.terminationReason || "quality_threshold";
 			process.stderr.write(
-				`[greedysearch] Quality threshold ${qualityThreshold} reached (score: ${evaluation.score.toFixed(1)}). Terminating early.\n`,
+				`[greedysearch] Research floor reached (score: ${evaluation.score.toFixed(1)}). Terminating early.\n`,
 			);
 			break;
 		}
@@ -1490,16 +2708,26 @@ export async function runResearchMode({
 	};
 	try {
 		const rawReport = await runGeminiPrompt(
-			buildFinalReportPrompt(query, rounds, combinedSources),
+			buildFinalReportPrompt(
+				query,
+				rounds,
+				combinedSources,
+				questions,
+				evidenceItems,
+			),
 			{ timeoutMs: 180000 },
 		);
 		const parsed = parseGeminiJson(rawReport, {});
+		const hasClaims = Array.isArray(parsed?.claims) && parsed.claims.length > 0;
 		synthesis = {
 			...synthesis,
 			...parsed,
 			rawAnswer: rawReport.answer || "",
 			geminiSources: rawReport.sources || [],
-			synthesized: true,
+			// Only mark as synthesized if Gemini actually returned structured
+			// claims. An empty/minimal response should not block the evidence
+			// fallback from running.
+			synthesized: hasClaims,
 		};
 	} catch (error) {
 		process.stderr.write(
@@ -1508,15 +2736,128 @@ export async function runResearchMode({
 		synthesis.error = error.message;
 	}
 
-	const fetchedFiles = await writeResearchSourcesToFiles(fetchedSources);
+	// Fallback: when no structured learnings were produced but per-source
+	// evidence was extracted successfully, ask Gemini to synthesize a final
+	// report directly from the evidence. This rescues runs whose per-round
+	// learning prompt failed (e.g. transient Gemini input field rejection)
+	// but whose evidence extraction step still captured real data.
+	const hasStructuredSynthesis =
+		synthesis.synthesized === true &&
+		Array.isArray(synthesis.claims) &&
+		synthesis.claims.length > 0;
+	if (!hasStructuredSynthesis && evidenceItems.length > 0) {
+		process.stderr.write(
+			"[greedysearch] Falling back to evidence-based synthesis (no per-round learnings).\n",
+		);
+		try {
+			const evidencePrompt = buildSynthesisFromEvidencePrompt(
+				query,
+				combinedSources,
+				questions,
+				evidenceItems,
+			);
+			const rawEvidenceReport = await runGeminiPrompt(evidencePrompt, {
+				timeoutMs: 180000,
+			});
+			const parsedEvidence = parseGeminiJson(rawEvidenceReport, {});
+			synthesis = {
+				...synthesis,
+				...parsedEvidence,
+				rawAnswer: rawEvidenceReport.answer || synthesis.answer || "",
+				geminiSources:
+					rawEvidenceReport.sources || synthesis.geminiSources || [],
+				synthesized: true,
+				synthesisMode: "evidence_fallback",
+			};
+		} catch (error) {
+			process.stderr.write(
+				`[greedysearch] Evidence-based synthesis failed: ${error.message}\n`,
+			);
+			synthesis.evidenceFallbackError = error.message;
+		}
+	}
+
 	const finishedAt = new Date().toISOString();
 	const durationMs = Date.now() - startMs;
+	const qualityScore = qualityHistory.at(-1) || 0;
+	fetchedSources = annotateFetchedSourcesWithIds(
+		fetchedSources,
+		combinedSources,
+	);
 
-	// Citation audit
+	// Citation audit + final question reconciliation + deterministic completion floor
 	process.stderr.write("PROGRESS:research:audit-citations\n");
 	const citationAudit = auditCitations(synthesis.answer || "", combinedSources);
 
+	// Citation URL reachability check
+	const citationUrls = await runCitationUrlCheck(combinedSources);
+
+	reconcileQuestionsFromSynthesis(questions, synthesis, citationAudit);
+	const floor = computeResearchFloor({
+		sources: combinedSources,
+		fetchedSources,
+		synthesis,
+		citationAudit,
+		gaps: allGaps,
+		questions,
+		rounds,
+		qualityScore,
+		qualityThreshold,
+		maxSources: options.maxSources,
+	});
+	if (floor.floorMet && terminationReason === "max_rounds") {
+		terminationReason = "done_floor_met";
+	} else if (!floor.floorMet && terminationReason === "quality_threshold") {
+		terminationReason = "max_rounds_floor_unmet";
+	}
+
+	const manifest = {
+		startedAt,
+		finishedAt,
+		durationMs,
+		engines: RESEARCH_ENGINES,
+		synthesizer: "gemini",
+		rounds: rounds.length,
+		actionsRun: totalActionsRun,
+		searches: totalSearches,
+		fetches: totalFetches,
+		sourcesFetched: fetchedSources.filter((s) => s?.contentChars > 100).length,
+		engineFailures,
+		terminationReason,
+		floorMet: floor.floorMet,
+	};
+	let bundle = null;
+	let fetchedFiles;
+	if (writeBundle) {
+		process.stderr.write("PROGRESS:research:bundle\n");
+		try {
+			bundle = await writeResearchBundle({
+				query,
+				rounds,
+				sources: combinedSources,
+				fetchedSources,
+				evidenceItems,
+				synthesis,
+				citationAudit,
+				citationUrls,
+				floor,
+				manifest,
+				allGaps,
+				questions,
+				outDir: researchOutDir,
+			});
+			fetchedFiles = bundle.sourceFiles;
+			delete bundle.sourceFiles;
+		} catch (error) {
+			bundle = { error: error.message || String(error) };
+			fetchedFiles = await writeResearchSourcesToFiles(fetchedSources);
+		}
+	} else {
+		fetchedFiles = await writeResearchSourcesToFiles(fetchedSources);
+	}
+
 	process.stderr.write("PROGRESS:research:done\n");
+	progressTracker.finish();
 
 	return {
 		query,
@@ -1527,23 +2868,19 @@ export async function runResearchMode({
 			maxSources: options.maxSources,
 			rounds,
 			learnings: allLearnings,
+			gaps: allGaps,
+			evidence: evidenceItems,
+			questions,
+			questionProgress: questionProgress(questions),
 			qualityHistory,
 			terminationReason,
 			qualityThreshold,
-			manifest: {
-				startedAt,
-				finishedAt,
-				durationMs,
-				rounds: rounds.length,
-				actionsRun: totalActionsRun,
-				searches: totalSearches,
-				fetches: totalFetches,
-				sourcesFetched: fetchedSources.filter((s) => s?.contentChars > 100)
-					.length,
-				engineFailures,
-			},
+			floor,
+			bundle,
+			manifest,
 		},
 		_citationAudit: citationAudit,
+		_citationUrls: citationUrls,
 		_sources: combinedSources,
 		_fetchedSources: fetchedFiles,
 		_synthesis: synthesis,
@@ -1559,23 +2896,43 @@ export async function runResearchMode({
 						)
 					: 0,
 			agreementLevel: synthesis.agreement?.level || "mixed",
+			floorMet: floor.floorMet,
 		},
 	};
 }
 
 function dedupeFetchedSources(sources) {
-	const seen = new Map();
+	const byUrl = new Map();
 	for (const source of sources) {
 		const key =
 			source?.id || normalizeUrl(source?.finalUrl || source?.url || "");
 		if (!key) continue;
-		const existing = seen.get(key);
+		const existing = byUrl.get(key);
 		if (
 			!existing ||
 			(source.contentChars || 0) > (existing.contentChars || 0)
 		) {
-			seen.set(key, source);
+			byUrl.set(key, source);
+		}
+	}
+
+	const out = [];
+	for (const source of byUrl.values()) {
+		const content = String(source.content || source.snippet || "");
+		const duplicateIndex = out.findIndex((existing) => {
+			const other = String(existing.content || existing.snippet || "");
+			if (content.length < 400 || other.length < 400) return false;
+			return (
+				jaccardSimilarity(content.slice(0, 4000), other.slice(0, 4000)) >= 0.9
+			);
+		});
+		if (duplicateIndex === -1) {
+			out.push(source);
+			continue;
+		}
+		if ((source.contentChars || 0) > (out[duplicateIndex].contentChars || 0)) {
+			out[duplicateIndex] = source;
 		}
 	}
-	return Array.from(seen.values());
+	return out;
 }