mcp-scraper 0.77.0 → 0.78.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to MCP Scraper are documented here. The format is based on [
 
 ## [Unreleased]
 
+## [0.78.0] - 2026-08-28
+
+### Changed
+
+- Made `maxQuestions` an explicit target count rather than a traversal-depth control, with separate discovery and material-completeness diagnostics.
+- Preserved complete People Also Ask, AI Overview, and organic-result link provenance in JSON, structured MCP output, and CSV while classifying plain links and Google redirect links explicitly.
+- Resolved opaque Google `/goto` targets through bounded concurrent manual-redirect requests with active-browser interception as a fallback, without following publisher destinations and without dropping unresolved material.
+- Aligned the bounded PAA production-provider canary with the public `maxQuestions` contract and made Bright Data the default test provider.
+
+### Fixed
+
+- Distinguished a healthy three-pass PAA frontier exhaustion from failed, disappeared, or timed-out browser interactions; interrupted jobs now renew fenced leases, resume automatically on the same job ID, and stop after a bounded recovery budget.
+- Checkpointed the initial SERP material before PAA expansion so a worker interruption retains already captured AI Overview citations, organic rankings, entities, forums, videos, and local results.
+- Required an exact visible AI Overview label before accepting an overview container, preventing ordinary sponsored blocks from being misclassified as AI answers.
+- Kept synchronous and durable PAA results consistent for question identifiers, all answer sources, SERP modules, link-resolution status, and completeness diagnostics.
+
 ## [0.77.0] - 2026-08-28
 
 ### Fixed

package/README.md

@@ -174,7 +174,7 @@ Build the branded one-click bundle:
 npm run build:mcpb
 ```
 
-The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.77.0`, SHA-256 `d59c2c55eeff7889a78d0fcddfb93d8062003e2ebd18f8dc8a03a73d262fc25a`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, API-key configuration field, and manually curated current-release message from the bundle manifest.
+The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.78.0`, SHA-256 `24ff5a133390938baa00e38a6489dd46e4f143fb26d9d2759e0983e134a946a7`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, API-key configuration field, and manually curated current-release message from the bundle manifest.
 
 The MCPB install exposes every tool — web-intelligence plus all `browser_*` tools — through the one `mcp-scraper` server.
 

package/dist/{analytics-repository-AUTJK4HK.js → analytics-repository-D5LEGQG3.js}

@@ -85,9 +85,9 @@ import {
   updateAnalyticsPixel,
   upsertAnalyticsAdSpend,
   upsertAnalyticsHostGroup
-} from "./chunk-IBQNOZ7E.js";
-import "./chunk-PJEEKOUM.js";
-import "./chunk-WEFPBAAG.js";
+} from "./chunk-74CCAY6T.js";
+import "./chunk-FUMG43EN.js";
+import "./chunk-OU4FV2RP.js";
 export {
   ANALYTICS_CONTENT_SORTS,
   AnalyticsRepositoryError,

package/dist/bin/api-server.js

@@ -17,15 +17,15 @@ loadDotEnv();
 async function main() {
   const [{ serve }, { app }, { startWorker }, { migrate }] = await Promise.all([
     import("@hono/node-server"),
-    import("../server-EKRNKKLU.js"),
-    import("../worker-DR6R7J46.js"),
-    import("../db-566MOHHD.js")
+    import("../server-6B2OG3NN.js"),
+    import("../worker-2BYACLNF.js"),
+    import("../db-TA567JLA.js")
   ]);
   const PORT = parseInt(process.env.PORT ?? "3001");
   try {
     await migrate();
     if (process.env.ANALYTICS_DATABASE_URL) {
-      const { migrateAnalytics } = await import("../analytics-repository-AUTJK4HK.js");
+      const { migrateAnalytics } = await import("../analytics-repository-D5LEGQG3.js");
       await migrateAnalytics();
     }
     startWorker();

package/dist/bin/mcp-scraper-cli.js

@@ -6,14 +6,14 @@ import {
   openWorkflowReport,
   runWorkflow,
   workflowOutputBaseDir
-} from "../chunk-KBTUPRTF.js";
+} from "../chunk-VEQPA65D.js";
 import "../chunk-RJ7JVYKU.js";
-import "../chunk-77LQV73B.js";
+import "../chunk-OWF2JJKN.js";
 import "../chunk-VXLU74YZ.js";
 import "../chunk-GGZEC22A.js";
 import {
   PACKAGE_VERSION
-} from "../chunk-7HF3T7P2.js";
+} from "../chunk-ZUCU2A6V.js";
 
 // src/cli/human-cli.ts
 import { Command } from "commander";

package/dist/bin/mcp-scraper-core.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 import {
   runMcpScraperStdio
-} from "../chunk-IP7UDXMU.js";
-import "../chunk-DTJ56S5B.js";
+} from "../chunk-FODYEDZK.js";
+import "../chunk-2P2ZVRPK.js";
 import "../chunk-PGJQDMC2.js";
 import "../chunk-DNM65UCK.js";
 import "../chunk-T3MZISOF.js";
-import "../chunk-7RQULQF3.js";
+import "../chunk-B6L73AO4.js";
 import "../chunk-6W4ADSWE.js";
 import "../chunk-OM7HVEJ3.js";
-import "../chunk-CXY5WV45.js";
-import "../chunk-GT6MP4SU.js";
+import "../chunk-NGLZ6UJR.js";
+import "../chunk-IYYRSVRQ.js";
 import "../chunk-VXLU74YZ.js";
 import "../chunk-GGZEC22A.js";
-import "../chunk-7HF3T7P2.js";
-import "../chunk-WEFPBAAG.js";
+import "../chunk-ZUCU2A6V.js";
+import "../chunk-OU4FV2RP.js";
 
 // src/mcp/thorbit-restricted-tool-surface.ts
 var THORBIT_RESTRICTED_TOOL_NAMES = [

package/dist/bin/mcp-scraper-install.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   renderInstallTerminal
-} from "../chunk-GT6MP4SU.js";
+} from "../chunk-IYYRSVRQ.js";
 import {
   PACKAGE_VERSION
-} from "../chunk-7HF3T7P2.js";
+} from "../chunk-ZUCU2A6V.js";
 
 // bin/mcp-scraper-install.ts
 var noColor = process.argv.includes("--no-color") || process.env.NO_COLOR !== void 0 || process.env.FORCE_COLOR === "0" || !process.stdout.isTTY;

package/dist/bin/mcp-stdio-server.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 import {
   runMcpScraperStdio
-} from "../chunk-IP7UDXMU.js";
-import "../chunk-DTJ56S5B.js";
+} from "../chunk-FODYEDZK.js";
+import "../chunk-2P2ZVRPK.js";
 import "../chunk-PGJQDMC2.js";
 import "../chunk-DNM65UCK.js";
 import "../chunk-T3MZISOF.js";
-import "../chunk-7RQULQF3.js";
+import "../chunk-B6L73AO4.js";
 import "../chunk-6W4ADSWE.js";
 import "../chunk-OM7HVEJ3.js";
-import "../chunk-CXY5WV45.js";
-import "../chunk-GT6MP4SU.js";
+import "../chunk-NGLZ6UJR.js";
+import "../chunk-IYYRSVRQ.js";
 import "../chunk-VXLU74YZ.js";
 import "../chunk-GGZEC22A.js";
-import "../chunk-7HF3T7P2.js";
-import "../chunk-WEFPBAAG.js";
+import "../chunk-ZUCU2A6V.js";
+import "../chunk-OU4FV2RP.js";
 
 // bin/mcp-stdio-server.ts
 runMcpScraperStdio();

package/dist/bin/paa-harvest.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   harvest
-} from "../chunk-F6MUGMRN.js";
+} from "../chunk-UFJJGXVO.js";
 import {
   browserServiceApiKey
 } from "../chunk-OM7HVEJ3.js";
-import "../chunk-CXY5WV45.js";
-import "../chunk-77LQV73B.js";
-import "../chunk-WEFPBAAG.js";
+import "../chunk-NGLZ6UJR.js";
+import "../chunk-OWF2JJKN.js";
+import "../chunk-OU4FV2RP.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/{chunk-DTJ56S5B.js → chunk-2P2ZVRPK.js}

@@ -19,7 +19,7 @@ import {
 } from "./chunk-T3MZISOF.js";
 import {
   sanitizeOutboundDiagnostics
-} from "./chunk-7RQULQF3.js";
+} from "./chunk-B6L73AO4.js";
 import {
   MC_PER_CREDIT,
   PAA_BASE_CREDITS,
@@ -34,7 +34,7 @@ import {
 import {
   recordVendorUsage,
   vendorCostUsd
-} from "./chunk-CXY5WV45.js";
+} from "./chunk-NGLZ6UJR.js";
 import {
   buildSerpEmailQuery,
   classifyEmailScope,
@@ -45,14 +45,14 @@ import {
 } from "./chunk-VXLU74YZ.js";
 import {
   PACKAGE_VERSION
-} from "./chunk-7HF3T7P2.js";
+} from "./chunk-ZUCU2A6V.js";
 import {
   PUBLIC_ERROR_CODES,
   buildPublicErrorEnvelope,
   normalizePublicErrorCode,
   publicErrorMessage,
   sanitizeVendorName
-} from "./chunk-WEFPBAAG.js";
+} from "./chunk-OU4FV2RP.js";
 
 // src/harvest-timeout.ts
 var SCRAPE_FUNCTION_MAX_MS = 8e5;
@@ -1121,6 +1121,100 @@ function errorAttemptsSection(body) {
 Attempts:
 ${lines.join("\n")}`;
 }
+function publicPaaLifecycle(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const row = value;
+  const discoveryStatus = nullableBoundedString(row.discoveryStatus, 100);
+  if (!discoveryStatus) return null;
+  const requestedQuestions = finiteNonNegative(row.requestedQuestions) ?? 0;
+  const questionsFound = finiteNonNegative(row.questionsFound) ?? 0;
+  return {
+    requestedQuestions,
+    questionsFound,
+    targetStatus: row.targetStatus === "met" ? "met" : "not_met",
+    discoveryStatus,
+    materialStatus: row.materialStatus === "complete" ? "complete" : "partial",
+    completionReason: nullableBoundedString(row.completionReason, 1e3) ?? "",
+    automaticRetries: finiteNonNegative(row.automaticRetries) ?? 0,
+    knownQuestions: finiteNonNegative(row.knownQuestions) ?? questionsFound,
+    processedQuestions: finiteNonNegative(row.processedQuestions) ?? 0,
+    failedInteractions: finiteNonNegative(row.failedInteractions) ?? 0,
+    noGrowthConfirmations: finiteNonNegative(row.noGrowthConfirmations) ?? 0
+  };
+}
+function publicPaaSource(value) {
+  if (!value || typeof value !== "object") return null;
+  const source = value;
+  const rawUrl = nullableBoundedString(source.rawUrl ?? source.url, 8e3);
+  if (!rawUrl) return null;
+  return {
+    title: nullableBoundedString(source.title, 2e3),
+    site: nullableBoundedString(source.site, 2e3),
+    url: nullableBoundedString(source.url, 8e3) ?? rawUrl,
+    rawUrl,
+    resolvedUrl: nullableBoundedString(source.resolvedUrl, 8e3),
+    linkType: nullableBoundedString(source.linkType, 100) ?? "plain",
+    resolutionStatus: nullableBoundedString(source.resolutionStatus, 100) ?? "not_needed"
+  };
+}
+function publicPaaQuestion(row) {
+  const sources = Array.isArray(row.sources) ? row.sources.flatMap((value) => {
+    const source = publicPaaSource(value);
+    return source ? [source] : [];
+  }) : [];
+  const legacyUrl = nullableBoundedString(row.source_cite ?? row.sourceCite ?? row.source_url ?? row.sourceUrl, 8e3);
+  return {
+    questionId: nullableBoundedString(row.question_id ?? row.questionId, 100) ?? "",
+    googleLinkId: nullableBoundedString(row.google_link_id ?? row.googleLinkId, 2e3),
+    googleEvidenceId: nullableBoundedString(row.google_evidence_id ?? row.googleEvidenceId, 2e3),
+    question: String(row.question ?? ""),
+    answer: nullableBoundedString(row.answer, 5e4),
+    sources,
+    sourceTitle: nullableBoundedString(row.source_title ?? row.sourceTitle, 2e3) ?? sources[0]?.title ?? null,
+    sourceSite: nullableBoundedString(row.source_site ?? row.sourceSite, 2e3) ?? sources[0]?.site ?? null,
+    sourceUrl: legacyUrl ?? sources[0]?.url ?? null
+  };
+}
+function publicOrganicResult(row) {
+  const url = String(row.url ?? "");
+  return {
+    position: Number(row.position) || 0,
+    title: String(row.title ?? ""),
+    url,
+    rawUrl: String(row.rawUrl ?? url),
+    resolvedUrl: nullableBoundedString(row.resolvedUrl, 8e3),
+    linkType: nullableBoundedString(row.linkType, 100) ?? "plain",
+    resolutionStatus: nullableBoundedString(row.resolutionStatus, 100) ?? "not_needed",
+    domain: String(row.domain ?? ""),
+    snippet: nullableBoundedString(row.snippet, 5e4)
+  };
+}
+function publicAiOverview(value) {
+  if (!value || typeof value !== "object") return null;
+  const ai = value;
+  return {
+    detected: ai.detected === true,
+    text: nullableBoundedString(ai.text, 1e5),
+    citations: Array.isArray(ai.citations) ? ai.citations.flatMap((value2) => {
+      if (!value2 || typeof value2 !== "object") return [];
+      const citation = value2;
+      const rawUrl = nullableBoundedString(citation.rawUrl ?? citation.rawHref ?? citation.href, 8e3);
+      if (!rawUrl) return [];
+      return [{
+        text: String(citation.text ?? ""),
+        href: nullableBoundedString(citation.href ?? citation.url, 8e3) ?? rawUrl,
+        rawUrl,
+        resolvedUrl: nullableBoundedString(citation.resolvedUrl, 8e3),
+        linkType: nullableBoundedString(citation.linkType, 100) ?? "plain",
+        resolutionStatus: nullableBoundedString(citation.resolutionStatus, 100) ?? "not_needed"
+      }];
+    }) : [],
+    expanded: ai.expanded === true,
+    fullyExpanded: ai.fullyExpanded === true,
+    sections: Array.isArray(ai.sections) ? ai.sections.map(String) : [],
+    shareUrl: nullableBoundedString(ai.shareUrl, 8e3)
+  };
+}
 function formatHarvestPaa(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return formattedErrorResult(parsed.error);
@@ -1139,7 +1233,7 @@ function formatHarvestPaa(raw, input) {
 |---|----------|--------|--------|
 ${paaRows}` : "## People Also Ask\n*Google did not return a People Also Ask block for this query/location. SERP data was extracted successfully when available.*";
   const serpRows = organic.map(
-    (r) => `| ${r.position} | ${cell(r.title)} | [${cell(r.domain)}](${r.url}) | ${cell(truncate(r.snippet, 100))} |`
+    (r) => `| ${r.position} | ${cell(r.title)} | [${cell(r.resolutionStatus === "unresolved" ? "Google redirect (unresolved)" : r.domain)}](${r.url}) | ${cell(truncate(r.snippet, 100))} |`
   ).join("\n");
   const serpTable = organic.length ? `
 ## Organic Results (${organic.length})
@@ -1175,20 +1269,10 @@ ${paaTable}${serpTable}${entityIdsSection(entityIds)}${aiSection}${statsLine}${d
       degradedResult: diagnostics?.degradedResult ?? null,
       degradationReasons: diagnostics?.degradationReasons ?? [],
       retryRecommended: diagnostics?.retryRecommended ?? null,
-      questions: flat.map((r) => ({
-        question: String(r.question ?? ""),
-        answer: r.answer ?? null,
-        sourceTitle: r.source_title ?? null,
-        sourceSite: r.source_site ?? null
-      })),
-      organicResults: organic.map((r) => ({
-        position: Number(r.position) || 0,
-        title: String(r.title ?? ""),
-        url: String(r.url ?? ""),
-        domain: String(r.domain ?? ""),
-        snippet: r.snippet ?? null
-      })),
-      aiOverview: aiOvw ? { detected: aiOvw.detected === true, text: aiOvw.text ?? null, shareUrl: aiOvw.shareUrl ?? null } : null,
+      paaLifecycle: publicPaaLifecycle(diagnostics?.paaLifecycle),
+      questions: flat.map((r) => publicPaaQuestion(r)),
+      organicResults: organic.map((r) => publicOrganicResult(r)),
+      aiOverview: publicAiOverview(aiOvw),
       entityIds: entityIds ? { entities: entityIds.entities ?? [], kgIds: entityIds.kgIds ?? [], cids: entityIds.cids ?? [], gcids: entityIds.gcids ?? [] } : null,
       durationMs: durationMs ?? null
     }
@@ -1230,16 +1314,24 @@ function durablePaaProgress(result, options) {
   const completeness = structuredRecord(diagnostics.completeness ?? result.completeness);
   const captured = finiteNonNegative(completeness.questionCount ?? completeness.capturedQuestions) ?? rows.length;
   const answered = finiteNonNegative(completeness.answeredQuestions) ?? rows.filter((row) => nullableBoundedString(row.answer) !== null).length;
-  const sourced = finiteNonNegative(completeness.sourcedQuestions) ?? rows.filter((row) => nullableBoundedString(
+  const sourced = finiteNonNegative(completeness.sourcedQuestions) ?? rows.filter((row) => Array.isArray(row.sources) && row.sources.length > 0 || nullableBoundedString(
     row.source_cite ?? row.sourceCite ?? row.source_site ?? row.sourceSite ?? row.source_url ?? row.sourceUrl
   ) !== null).length;
+  const lifecycle = publicPaaLifecycle(diagnostics.paaLifecycle ?? structuredRecord(result.progress).lifecycle);
+  if (lifecycle) {
+    lifecycle.automaticRetries = Math.max(
+      finiteNonNegative(lifecycle.automaticRetries) ?? 0,
+      finiteNonNegative(options.paaRecoveryCount) ?? 0
+    );
+  }
   return {
     requestedQuestions: finiteNonNegative(completeness.requestedQuestions ?? options.maxQuestions),
     capturedQuestions: captured,
     answeredQuestions: answered,
     sourcedQuestions: sourced,
     missingAnswers: finiteNonNegative(completeness.paaWithoutAnswer ?? completeness.missingAnswers) ?? Math.max(0, captured - answered),
-    missingSources: finiteNonNegative(completeness.paaWithoutSource ?? completeness.missingSources) ?? Math.max(0, captured - sourced)
+    missingSources: finiteNonNegative(completeness.paaWithoutSource ?? completeness.missingSources) ?? Math.max(0, captured - sourced),
+    lifecycle
   };
 }
 function durablePaaResult(result) {
@@ -1250,14 +1342,12 @@ function durablePaaResult(result) {
     completionStatus: nullableBoundedString(diagnostics.completionStatus ?? result.completionStatus),
     resultQuality: nullableBoundedString(diagnostics.resultQuality ?? result.resultQuality),
     retryRecommended: typeof diagnostics.retryRecommended === "boolean" ? diagnostics.retryRecommended : typeof result.retryRecommended === "boolean" ? result.retryRecommended : null,
+    paaLifecycle: publicPaaLifecycle(diagnostics.paaLifecycle ?? structuredRecord(result.progress).lifecycle),
     questionCount: rows.length,
-    questions: rows.map((row) => ({
-      question: String(row.question ?? ""),
-      answer: nullableBoundedString(row.answer, 5e4),
-      sourceTitle: nullableBoundedString(row.source_title ?? row.sourceTitle, 2e3),
-      sourceSite: nullableBoundedString(row.source_site ?? row.sourceSite, 2e3),
-      sourceUrl: nullableBoundedString(row.source_cite ?? row.sourceCite ?? row.source_url ?? row.sourceUrl, 8e3)
-    }))
+    questions: rows.map(publicPaaQuestion),
+    organicResults: Array.isArray(result.organicResults) ? result.organicResults.filter((row) => row && typeof row === "object").map((row) => publicOrganicResult(row)) : [],
+    aiOverview: publicAiOverview(result.aiOverview),
+    entityIds: result.entityIds && typeof result.entityIds === "object" ? result.entityIds : null
   };
 }
 function durablePaaAttempts(value) {
@@ -1332,6 +1422,7 @@ function formatHarvestPaaStatus(raw) {
   const result = structuredRecord(parsed.data.result);
   const options = structuredRecord(parsed.data.options);
   const progress = durablePaaProgress(result, options);
+  const recovering = state === "pending" && (finiteNonNegative(options.paaRecoveryCount) ?? 0) > 0;
   const holdMc = finiteNonNegative(options.billingHoldMc);
   const billedMc = finiteNonNegative(options.billedMc);
   const billingSettled = nullableBoundedString(options.billingSettledAt) !== null;
@@ -1351,7 +1442,10 @@ function formatHarvestPaaStatus(raw) {
     }
   };
   return {
-    content: [{ type: "text", text: `PAA job ${jobId}: ${state}. ${progress.capturedQuestions ?? 0} questions are preserved.` }],
+    content: [{
+      type: "text",
+      text: recovering ? `PAA job ${jobId}: recovering automatically after an interrupted worker. ${progress.capturedQuestions ?? 0} questions are preserved; keep polling this same job.` : `PAA job ${jobId}: ${state}. ${progress.capturedQuestions ?? 0} questions are preserved.`
+    }],
     structuredContent
   };
 }
@@ -1365,7 +1459,7 @@ function formatSearchSerp(raw, input) {
   const aiOvw = d.aiOverview;
   const diagnostics = d.diagnostics;
   const serpRows = organic.map(
-    (r) => `| ${r.position} | ${cell(r.title)} | [${cell(r.domain)}](${r.url}) | ${cell(truncate(r.snippet, 100))} |`
+    (r) => `| ${r.position} | ${cell(r.title)} | [${cell(r.resolutionStatus === "unresolved" ? "Google redirect (unresolved)" : r.domain)}](${r.url}) | ${cell(truncate(r.snippet, 100))} |`
   ).join("\n");
   const serpTable = organic.length ? `## Organic Results (${organic.length})
 | # | Title | URL | Snippet |
@@ -1406,13 +1500,7 @@ ${qualityLine}${serpTable}${localSection}${entityIdsSection(entityIds)}${aiSecti
       degradedResult: diagnostics?.degradedResult ?? null,
       degradationReasons: diagnostics?.degradationReasons ?? [],
       retryRecommended: diagnostics?.retryRecommended ?? null,
-      organicResults: organic.map((r) => ({
-        position: Number(r.position) || 0,
-        title: String(r.title ?? ""),
-        url: String(r.url ?? ""),
-        domain: String(r.domain ?? ""),
-        snippet: r.snippet ?? null
-      })),
+      organicResults: organic.map((r) => publicOrganicResult(r)),
       localPack: localPack.map((b) => ({
         position: Number(b.position) || 0,
         name: String(b.name ?? ""),
@@ -1420,7 +1508,7 @@ ${qualityLine}${serpTable}${localSection}${entityIdsSection(entityIds)}${aiSecti
         reviewCount: b.reviewCount ?? null,
         websiteUrl: b.websiteUrl ?? null
       })),
-      aiOverview: aiOvw ? { detected: aiOvw.detected === true, text: aiOvw.text ?? null, shareUrl: aiOvw.shareUrl ?? null } : null,
+      aiOverview: publicAiOverview(aiOvw),
       entityIds: entityIds ? { entities: entityIds.entities ?? [], kgIds: entityIds.kgIds ?? [], cids: entityIds.cids ?? [], gcids: entityIds.gcids ?? [] } : null
     }
   };
@@ -5422,7 +5510,7 @@ seam is noted so you can chain them.
 
 ## Search & research
 - Organic Google results, rankings, and entity IDs -> **search_serp**. Set the relevant include flag (or \`includeAllSerpFeatures\`) for local pack, forums, videos, AI surfaces, or What People Are Saying.
-- Original-query People-Also-Ask questions, answers, sources, organic results, and entity IDs -> **harvest_paa** for a short compatibility call. For expected long work, especially 60 questions, call **harvest_paa_start** once and poll its job with **harvest_paa_status** until terminal. Keep the same idempotency key after a timeout, unknown response, or in-progress reply; never create a replacement key merely because the caller stopped waiting. Optional same-page SERP modules use the same include flags.
+- Original-query People-Also-Ask questions, answers, complete source/link provenance, AI Overview evidence, organic results, and entity IDs -> **harvest_paa** for a short compatibility call. maxQuestions is a target count, not depth. For expected long work, call **harvest_paa_start** once and poll its job with **harvest_paa_status** until terminal; interrupted workers recover automatically under the same job. Keep the same idempotency key after a timeout, unknown response, recovery, or in-progress reply; never create a replacement key merely because the caller stopped waiting. Treat frontier_exhausted as observed Google-frontier exhaustion and interrupted as non-terminal infrastructure/browser loss, never as the same state. Optional same-page SERP modules use the same include flags.
 - \`search_serp\` returns \`organicResults[].url\` (often including reddit.com threads) \u2014 feed those into
   \`extract_url\` or \`reddit_thread\`.
 
@@ -8388,16 +8476,52 @@ var RankTrackerBlueprintOutputSchema = {
   metrics: z6.array(z6.string()),
   implementationPrompt: z6.string()
 };
+var SerpLinkTypeOutput = z6.enum(["plain", "google_url_redirect", "google_goto_redirect"]);
+var SerpLinkResolutionStatusOutput = z6.enum(["not_needed", "resolved", "unresolved", "rejected"]);
+var SerpLinkOutput = {
+  url: z6.string(),
+  rawUrl: z6.string(),
+  resolvedUrl: NullableString,
+  linkType: SerpLinkTypeOutput,
+  resolutionStatus: SerpLinkResolutionStatusOutput
+};
+var PaaSourceOutput = z6.object({
+  ...SerpLinkOutput,
+  title: NullableString,
+  site: NullableString
+});
+var PaaQuestionOutput = z6.object({
+  questionId: z6.string(),
+  googleLinkId: NullableString,
+  googleEvidenceId: NullableString,
+  question: z6.string(),
+  answer: NullableString,
+  sources: z6.array(PaaSourceOutput),
+  sourceTitle: NullableString,
+  sourceSite: NullableString,
+  sourceUrl: NullableString
+});
 var OrganicResultOutput = z6.object({
   position: z6.number().int(),
   title: z6.string(),
-  url: z6.string(),
+  ...SerpLinkOutput,
   domain: z6.string(),
   snippet: NullableString
 });
 var AiOverviewOutput = z6.object({
   detected: z6.boolean(),
   text: NullableString,
+  citations: z6.array(z6.object({
+    text: z6.string(),
+    href: z6.string(),
+    rawUrl: z6.string(),
+    resolvedUrl: NullableString,
+    linkType: SerpLinkTypeOutput,
+    resolutionStatus: SerpLinkResolutionStatusOutput
+  })),
+  expanded: z6.boolean(),
+  fullyExpanded: z6.boolean(),
+  sections: z6.array(z6.string()),
   shareUrl: NullableString.optional()
 }).nullable();
 var EntityIdsOutput = z6.object({
@@ -8411,6 +8535,19 @@ var EntityIdsOutput = z6.object({
   cids: z6.array(z6.string()),
   gcids: z6.array(z6.string())
 }).nullable();
+var PaaLifecycleOutput = z6.object({
+  requestedQuestions: z6.number().int().min(0),
+  questionsFound: z6.number().int().min(0),
+  targetStatus: z6.enum(["met", "not_met"]),
+  discoveryStatus: z6.enum(["in_progress", "target_reached", "frontier_exhausted", "no_paa_observed", "interrupted", "recovery_exhausted"]),
+  materialStatus: z6.enum(["complete", "partial"]),
+  completionReason: z6.string(),
+  automaticRetries: z6.number().int().min(0),
+  knownQuestions: z6.number().int().min(0),
+  processedQuestions: z6.number().int().min(0),
+  failedInteractions: z6.number().int().min(0),
+  noGrowthConfirmations: z6.number().int().min(0)
+}).nullable();
 var HarvestPaaOutputSchema = {
   query: z6.string(),
   location: NullableString,
@@ -8420,12 +8557,8 @@ var HarvestPaaOutputSchema = {
   degradedResult: z6.boolean().nullable(),
   degradationReasons: z6.array(z6.string()),
   retryRecommended: z6.boolean().nullable(),
-  questions: z6.array(z6.object({
-    question: z6.string(),
-    answer: NullableString,
-    sourceTitle: NullableString,
-    sourceSite: NullableString
-  })),
+  paaLifecycle: PaaLifecycleOutput,
+  questions: z6.array(PaaQuestionOutput),
   organicResults: z6.array(OrganicResultOutput),
   aiOverview: AiOverviewOutput,
   entityIds: EntityIdsOutput,
@@ -8437,7 +8570,8 @@ var HarvestPaaDurableProgressOutput = z6.object({
   answeredQuestions: z6.number().int().min(0),
   sourcedQuestions: z6.number().int().min(0),
   missingAnswers: z6.number().int().min(0),
-  missingSources: z6.number().int().min(0)
+  missingSources: z6.number().int().min(0),
+  lifecycle: PaaLifecycleOutput
 });
 var HarvestPaaDurableAttemptOutput = z6.object({
   attemptNumber: z6.number().int().min(1),
@@ -8467,14 +8601,12 @@ var HarvestPaaDurableResultOutput = z6.object({
   completionStatus: NullableString,
   resultQuality: NullableString,
   retryRecommended: z6.boolean().nullable(),
+  paaLifecycle: PaaLifecycleOutput,
   questionCount: z6.number().int().min(0),
-  questions: z6.array(z6.object({
-    question: z6.string(),
-    answer: NullableString,
-    sourceTitle: NullableString,
-    sourceSite: NullableString,
-    sourceUrl: NullableString
-  }))
+  questions: z6.array(PaaQuestionOutput),
+  organicResults: z6.array(OrganicResultOutput),
+  aiOverview: AiOverviewOutput,
+  entityIds: EntityIdsOutput
 });
 var HarvestPaaPendingStateOutput = z6.object({
   state: z6.literal("pending"),
@@ -13755,7 +13887,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   if (savesReports) registerSavedReportResources(server);
   server.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
-    description: `Expand one Google People Also Ask SERP into questions, answers, sources, organic results, and entity IDs. This compatibility tool waits; use harvest_paa_start plus harvest_paa_status for long runs. Optional SERP modules require their include flags. Use gl and location for regional context. Costs ${PAA_BASE_CREDITS} Credits per harvest plus ${PAA_QUESTION_CREDITS} Credits per question actually returned; unused hold is refunded. After a timeout or unknown response, reuse the same idempotencyKey. Call credits_info for current pricing and balance.`,
+    description: `Expand one Google People Also Ask SERP into questions, answers, every preserved source, AI Overview evidence, ranking URLs, and entity IDs. maxQuestions is a target count, not traversal depth. Results distinguish target_reached, proven frontier_exhausted, interruption, and recovery_exhausted; a failed click or browser timeout is never reported as exhaustion. This compatibility tool waits; use harvest_paa_start plus harvest_paa_status for long runs. Optional SERP modules require their include flags. Use gl and location for regional context. Costs ${PAA_BASE_CREDITS} Credits per harvest plus ${PAA_QUESTION_CREDITS} Credits per question actually returned; unused hold is refunded. After a timeout or unknown response, reuse the same idempotencyKey. Call credits_info for current pricing and balance.`,
     inputSchema: harvestPaaInputSchema,
     outputSchema: recordOutputSchema("harvest_paa", HarvestPaaOutputSchema),
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
@@ -13768,7 +13900,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   });
   server.registerTool("harvest_paa_start", {
     title: "Start Durable Google PAA Harvest",
-    description: `Start a durable Google People Also Ask harvest and return its job receipt. Use for long work, including 60 questions. Keep one idempotencyKey after a timeout, unknown response, or in-progress reply; replaying it recovers the existing job without a duplicate charge. Poll jobId with harvest_paa_status. Costs ${PAA_BASE_CREDITS} Credits plus ${PAA_QUESTION_CREDITS} per retained question; unused hold is refunded.`,
+    description: `Start a durable Google People Also Ask harvest and return its job receipt. maxQuestions is the requested target count. The job automatically resumes an interrupted serverless worker under the same jobId, idempotency key, and billing hold while preserving checkpoints. Keep one idempotencyKey after a timeout, unknown response, or in-progress reply; replaying it recovers the existing job without a duplicate charge. Poll jobId with harvest_paa_status. Costs ${PAA_BASE_CREDITS} Credits plus ${PAA_QUESTION_CREDITS} per retained question; unused hold is refunded.`,
     inputSchema: harvestPaaStartInputSchema,
     outputSchema: recordOutputSchema("harvest_paa_start", HarvestPaaStartOutputSchema),
     annotations: { ...liveWebToolAnnotations("Start Durable Google PAA Harvest"), readOnlyHint: false, idempotentHint: true }
@@ -13778,7 +13910,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   });
   server.registerTool("harvest_paa_status", {
     title: "Check Durable Google PAA Harvest",
-    description: "Poll an owner-scoped harvest_paa_start job. Returns state, saved progress, completeness, attempts, terminal rows, and billing. Polling never starts or bills another run.",
+    description: "Poll an owner-scoped harvest_paa_start job. Returns state, saved progress, automatic-recovery count, target status, discovery status, material completeness, attempts, terminal rows, and billing. frontier_exhausted means every observed eligible PAA control was processed plus three healthy no-growth confirmations; interruption never means exhaustion. Polling never starts or bills another run.",
     inputSchema: HarvestPaaStatusInputSchema,
     outputSchema: recordOutputSchema("harvest_paa_status", HarvestPaaStatusOutputSchema),
     annotations: { ...liveWebToolAnnotations("Check Durable Google PAA Harvest"), idempotentHint: true, openWorldHint: false }

package/dist/{chunk-E6Y3VCOJ.js → chunk-3PUMNEOC.js}

@@ -5,7 +5,7 @@ import {
   recordServiceConnectionHealth,
   setServiceConnectionProviderIdentity,
   updateServiceConnectionTools
-} from "./chunk-PJEEKOUM.js";
+} from "./chunk-FUMG43EN.js";
 import {
   createConnectedDataArtifact,
   createConnectedDataBinaryArtifact
@@ -23,13 +23,13 @@ import {
 import {
   recordVendorUsage,
   runWithCostContext
-} from "./chunk-CXY5WV45.js";
+} from "./chunk-NGLZ6UJR.js";
 import {
   debitMcIdempotent,
   getDb,
   getUserByEmail,
   reconcileBalanceMc
-} from "./chunk-WEFPBAAG.js";
+} from "./chunk-OU4FV2RP.js";
 
 // src/api/gmail-service.ts
 import { createHash as createHash4, createHmac, timingSafeEqual } from "crypto";

package/dist/{chunk-KIPIBPUB.js → chunk-47ZCUBM5.js}

@@ -10,7 +10,7 @@ import {
   finishHarvestAttempt,
   publicErrorMessage,
   startHarvestAttempt
-} from "./chunk-WEFPBAAG.js";
+} from "./chunk-OU4FV2RP.js";
 
 // src/api/harvest-problems.ts
 function errorMessage(err) {

package/dist/{chunk-IBQNOZ7E.js → chunk-74CCAY6T.js}

@@ -1,7 +1,7 @@
 import {
   getSessionSecret,
   serviceConnectionAdvertisesAction
-} from "./chunk-PJEEKOUM.js";
+} from "./chunk-FUMG43EN.js";
 
 // src/api/analytics-repository.ts
 import { createHash as createHash2, createHmac as createHmac2, randomBytes as randomBytes2, randomUUID as randomUUID2 } from "crypto";