pi-workflow-engine 0.13.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/workflows/diagnose.ts

@@ -3,17 +3,15 @@ import { Type } from "typebox";
 import {
   type AdvisoryVerified,
   type AdvisoryLens,
-  synthesizeAdvisoryReport,
-  finishAdvisoryReport,
-  emptyAdvisoryReport,
+  concludeLensReview,
   formatEvidence,
   formatLocation,
-  publishVerifiedKeptProgress,
+  formatRankedFinding,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
   name: "diagnose",
@@ -42,19 +40,7 @@ const PER_LENS = 4;
 export default async function run(api: WorkflowApi): Promise<unknown> {
   const { agent, phase, log, progress, args } = api;
   const challengeConfig = parseChallengeArgs(args);
-  const symptom = challengeConfig.args.trim();
-  let fileCount = 0;
-  let rawCandidateCount = 0;
-  let droppedCandidateCount = 0;
-  let refutedCandidateCount = 0;
-  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
-    files: fileCount,
-    candidates: rawCandidateCount,
-    verified,
-    kept,
-    dropped: droppedCandidateCount,
-    refuted: refutedCandidateCount,
-  });
+  const symptom = challengeConfig.args;
 
   phase("Scope");
   const scope = await agent(
@@ -68,16 +54,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
-  if (!scope) {
-    return finishAdvisoryReport(emptyAdvisoryReport(
-      "Diagnosis could not establish a scope.",
-      ["Provide the failing command, error message, or regression description and rerun diagnose."],
-      makeStats(0, 0),
-    ), []);
-  }
-
-  fileCount = scope.files.length;
-  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "counter", key: "files", label: "files", value: scope.files.length });
   progress({ type: "summary", key: "symptom", value: scope.symptom });
   progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
   log(`${scope.files.length} files scoped for diagnosis`);
@@ -107,45 +84,26 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Do not run mutation, install, commit, network, or destructive commands. Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence. " +
       "Use NOT_SUBSTANTIATED when evidence is missing; REFUTED requires disproof. Structured output only.",
   });
-  rawCandidateCount += pipelineResult.rawCandidates;
-  droppedCandidateCount += pipelineResult.dropped;
-  refutedCandidateCount += pipelineResult.refuted;
-  const { coverage } = pipelineResult;
-  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
-  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
-  const refuted = verified.filter((finding) => finding.verdict === "REFUTED");
-  const stats = makeStats(verified.length, surviving.length);
-  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
-
-  if (surviving.length === 0) {
-    return finishAdvisoryReport(emptyAdvisoryReport(
-      "No root-cause hypothesis survived verification.",
-      ["Capture the exact failing command and error output.", "Rerun diagnose with a narrower symptom or more evidence."],
-      stats,
-    ), coverage, verified);
-  }
-
-  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
-  const block = ranked
-    .map(
-      (finding, index) =>
-        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
-        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\nValidation/fix plan: ${finding.recommendation ?? "(none supplied)"}`,
-    )
-    .join("\n\n");
-  const refutedBlock = refuted
-    .slice(0, 8)
-    .map((finding) => `- ${finding.summary} — REFUTED because ${formatEvidence(finding.evidence)}`)
-    .join("\n");
-
-  const resolved = await synthesizeAdvisoryReport(api,
-    `## Synthesis: final diagnosis report\n\n${ranked.length} hypotheses survived independent verification.\n\n${block}\n\n` +
-      `## Refuted hypotheses for context\n${refutedBlock || "(none recorded)"}\n\n` +
-      "Select confirmed, plausible or explicitly unresolved root causes by ID. " +
-      "Recommendation must be a validation/fix plan, not a patch. nextSteps must be the minimum commands or code inspections needed to confirm the top diagnosis. Structured output only.",
-    ranked, coverage,
-  );
-  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
+  return concludeLensReview(api, pipelineResult, verified, {
+    files: scope.files.length,
+    rank,
+    formatFinding: (finding, index) => formatRankedFinding(finding, index, "Validation/fix plan"),
+    empty: {
+      summary: "No root-cause hypothesis survived verification.",
+      nextSteps: ["Capture the exact failing command and error output.", "Rerun diagnose with a narrower symptom or more evidence."],
+    },
+    synthesisPrompt: (block, ranked, refuted) => {
+      const refutedBlock = refuted
+        .slice(0, 8)
+        .map((finding) => `- ${finding.summary} — REFUTED because ${formatEvidence(finding.evidence)}`)
+        .join("\n");
+      return `## Synthesis: final diagnosis report\n\n${ranked.length} hypotheses survived independent verification.\n\n${block}\n\n` +
+        `## Refuted hypotheses for context\n${refutedBlock || "(none recorded)"}\n\n` +
+        "Select confirmed, plausible or explicitly unresolved root causes by ID. " +
+        "Recommendation must be a validation/fix plan, not a patch. nextSteps must be the minimum commands or code inspections needed to confirm the top diagnosis. Structured output only.";
+    },
+  });
 }
 
 function rank(finding: AdvisoryVerified): number {

package/.pi/extensions/pi-workflow-engine/workflows/perf-review.ts

@@ -3,17 +3,16 @@ import { Type } from "typebox";
 import {
   type AdvisoryVerified,
   type AdvisoryLens,
-  synthesizeAdvisoryReport,
+  concludeLensReview,
   finishAdvisoryReport,
   emptyAdvisoryReport,
-  formatEvidence,
+  EMPTY_LENS_REVIEW_STATS,
   formatLocation,
-  publishVerifiedKeptProgress,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
   name: "perf-review",
@@ -43,19 +42,7 @@ const PER_LENS = 4;
 export default async function run(api: WorkflowApi): Promise<unknown> {
   const { agent, phase, log, progress, args } = api;
   const challengeConfig = parseChallengeArgs(args);
-  const target = challengeConfig.args.trim() || "repository performance";
-  let fileCount = 0;
-  let rawCandidateCount = 0;
-  let droppedCandidateCount = 0;
-  let refutedCandidateCount = 0;
-  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
-    files: fileCount,
-    candidates: rawCandidateCount,
-    verified,
-    kept,
-    dropped: droppedCandidateCount,
-    refuted: refutedCandidateCount,
-  });
+  const target = challengeConfig.args || "repository performance";
 
   phase("Scope");
   const scope = await agent(
@@ -67,16 +54,15 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
-  if (!scope || scope.files.length === 0) {
+  if (scope.files.length === 0) {
     return finishAdvisoryReport(emptyAdvisoryReport(
       "No performance-relevant files were identified.",
       ["Provide a slow command, workload, file path, or user-visible latency concern to review."],
-      makeStats(0, 0),
+      EMPTY_LENS_REVIEW_STATS,
     ), []);
   }
 
-  fileCount = scope.files.length;
-  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "counter", key: "files", label: "files", value: scope.files.length });
   progress({ type: "summary", key: "target", value: scope.target });
   progress({ type: "summary", key: "files", value: scope.files.join(", ") });
   log(`${scope.files.length} files scoped for performance review`);
@@ -85,7 +71,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     `## Target\n${scope.target}\n\n## Files\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
     `## Measurement commands\n${scope.commands.map((command) => `- ${command}`).join("\n") || "(none identified)"}\n\n` +
     `## Summary\n${scope.summary}\n\n## Known measurements\n${scope.knownMeasurements ?? "(none known)"}\n` +
-    (args.trim() ? `\n## User instructions (verbatim)\n${args.trim()}\n` : "");
+    (challengeConfig.args ? `\n## User instructions (verbatim)\n${challengeConfig.args}\n` : "");
 
   const pipelineResult = await runLensVerificationPipeline({
     api,
@@ -106,40 +92,20 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence from code, scripts, config, or measurement output. " +
       "Default toward PLAUSIBLE or REFUTED when no measurement exists; do not overstate a bottleneck. Structured output only.",
   });
-  rawCandidateCount += pipelineResult.rawCandidates;
-  droppedCandidateCount += pipelineResult.dropped;
-  refutedCandidateCount += pipelineResult.refuted;
-  const { coverage } = pipelineResult;
-  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
-  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
-  const stats = makeStats(verified.length, surviving.length);
-  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
-
-  if (surviving.length === 0) {
-    return finishAdvisoryReport(emptyAdvisoryReport(
-      "No performance finding survived verification.",
-      ["Add or run a focused measurement for the target workload before optimizing.", "Rerun perf-review with benchmark output or a narrower slow path."],
-      stats,
-    ), coverage, verified);
-  }
-
-  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
-  const block = ranked
-    .map(
-      (finding, index) =>
-        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
-        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\nRecommendation: ${finding.recommendation ?? "(none supplied)"}`,
-    )
-    .join("\n\n");
-
-  const resolved = await synthesizeAdvisoryReport(api,
-    `## Synthesis: final perf-review report\n\n${ranked.length} candidates survived independent verification.\n\n${block}\n\n` +
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
+  return concludeLensReview(api, pipelineResult, verified, {
+    files: scope.files.length,
+    rank,
+    empty: {
+      summary: "No performance finding survived verification.",
+      nextSteps: ["Add or run a focused measurement for the target workload before optimizing.", "Rerun perf-review with benchmark output or a narrower slow path."],
+    },
+    synthesisPrompt: (block, ranked) =>
+      `## Synthesis: final perf-review report\n\n${ranked.length} candidates survived independent verification.\n\n${block}\n\n` +
       "Select findings by ID. " +
       "Severity is expected performance impact for the target workload. Prefer measurement recommendations before optimization recommendations when evidence is weak. " +
       "Recommendations must be safe advisory next actions, not patches. Include risky optimizations to avoid in recommendations or nextSteps when relevant. Structured output only.",
-    ranked, coverage,
-  );
-  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
+  });
 }
 
 function rank(finding: AdvisoryVerified): number {

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -3,17 +3,17 @@ import { Type } from "typebox";
 import {
   type AdvisoryVerified,
   type AdvisoryLens,
-  synthesizeAdvisoryReport,
+  concludeLensReview,
   finishAdvisoryReport,
   emptyAdvisoryReport,
-  formatEvidence,
+  EMPTY_LENS_REVIEW_STATS,
   formatLocation,
-  publishVerifiedKeptProgress,
+  formatRankedFinding,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
   name: "refactor-scout",
@@ -42,19 +42,7 @@ const PER_LENS = 5;
 export default async function run(api: WorkflowApi): Promise<unknown> {
   const { agent, phase, log, progress, args } = api;
   const challengeConfig = parseChallengeArgs(args);
-  const target = challengeConfig.args.trim() || ".";
-  let fileCount = 0;
-  let rawCandidateCount = 0;
-  let droppedCandidateCount = 0;
-  let refutedCandidateCount = 0;
-  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
-    files: fileCount,
-    candidates: rawCandidateCount,
-    verified,
-    kept,
-    dropped: droppedCandidateCount,
-    refuted: refutedCandidateCount,
-  });
+  const target = challengeConfig.args || ".";
 
   phase("Scope");
   const scope = await agent(
@@ -66,23 +54,22 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
-  if (!scope || scope.files.length === 0) {
+  if (scope.files.length === 0) {
     return finishAdvisoryReport(emptyAdvisoryReport(
       "No files were identified for refactor scouting.",
       ["Provide a target path, module, or subsystem to scout for refactor opportunities."],
-      makeStats(0, 0),
+      EMPTY_LENS_REVIEW_STATS,
     ), []);
   }
 
-  fileCount = scope.files.length;
-  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "counter", key: "files", label: "files", value: scope.files.length });
   progress({ type: "summary", key: "files", value: scope.files.join(", ") });
   log(`${scope.files.length} files scoped for refactor scouting`);
 
   const scopeBlock =
     `## Target\n${scope.target}\n\n## Files in scope\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
     `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
-    (args.trim() ? `\n## User instructions (verbatim)\n${args.trim()}\n` : "");
+    (challengeConfig.args ? `\n## User instructions (verbatim)\n${challengeConfig.args}\n` : "");
 
   const pipelineResult = await runLensVerificationPipeline({
     api,
@@ -103,37 +90,22 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Default toward REFUTED if the opportunity is generic, too broad, not evidenced by code, or lacks a safe first step. " +
       "Evidence must quote or cite code. Structured output only.",
   });
-  rawCandidateCount += pipelineResult.rawCandidates;
-  droppedCandidateCount += pipelineResult.dropped;
-  refutedCandidateCount += pipelineResult.refuted;
-  const { coverage } = pipelineResult;
-  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
-  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
-  const stats = makeStats(verified.length, surviving.length);
-  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
-
-  if (surviving.length === 0) {
-    return finishAdvisoryReport(emptyAdvisoryReport("No refactor opportunities survived verification.", ["Leave the scoped code unchanged unless a human reviewer has additional context."], stats), coverage, verified);
-  }
-
-  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
-  const block = ranked
-    .map(
-      (finding, index) =>
-        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
-        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\nSafe first step: ${finding.recommendation ?? "(none supplied)"}`,
-    )
-    .join("\n\n");
-
-  const resolved = await synthesizeAdvisoryReport(api,
-    `## Synthesis: final refactor-scout report\n\n${ranked.length} opportunities survived independent verification.\n\n${block}\n\n` +
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
+  return concludeLensReview(api, pipelineResult, verified, {
+    files: scope.files.length,
+    rank,
+    formatFinding: (finding, index) => formatRankedFinding(finding, index, "Safe first step"),
+    empty: {
+      summary: "No refactor opportunities survived verification.",
+      nextSteps: ["Leave the scoped code unchanged unless a human reviewer has additional context."],
+    },
+    synthesisPrompt: (block, ranked) =>
+      `## Synthesis: final refactor-scout report\n\n${ranked.length} opportunities survived independent verification.\n\n${block}\n\n` +
       "Merge findings with the same root cause and rank highest leverage / lowest risk first. " +
       "Select findings by ID. " +
       "Severity is maintenance or future-correctness impact. " +
       "Recommendations must be safe first refactor steps, not rewrites. Include concrete nextSteps for the host developer. Structured output only.",
-    ranked, coverage,
-  );
-  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
+  });
 }
 
 function rank(finding: AdvisoryVerified): number {

package/.pi/extensions/pi-workflow-engine/workflows/research.ts

@@ -1,4 +1,3 @@
-import { compactResults } from "../src/concurrency.ts";
 import {
   MAX_RESEARCH_LANES,
   ResearchLaneResultSchema,
@@ -7,18 +6,17 @@ import {
   ResearchVerificationSchema,
   type ResearchClaimCandidate,
   type ResearchReport,
-  type ResearchVerification,
 } from "../src/research-contract.ts";
 import {
   buildClaimCandidates,
   fallbackResearchReport,
   normalizeResearchLanes,
-  sanitizeLaneResults,
   sanitizeResearchReport,
   sanitizeVerification,
   unavailableResearchReport,
   unavailableVerification,
 } from "../src/research-evidence.ts";
+import { isFatalWorkflowError } from "../src/cancellation.ts";
 import { WorkflowToolHintUnavailableError } from "../src/tool-capabilities.ts";
 import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
@@ -32,7 +30,7 @@ const EXTERNAL_TOOLS: string[] = [];
 const EXTERNAL_TOOL_HINTS = ["external-search"] as const;
 
 export default async function run(api: WorkflowApi): Promise<ResearchReport> {
-  const { agent, parallel, phase, log, progress, args } = api;
+  const { agent, parallel, phase, log, progress, args, signal } = api;
   const question = args.trim();
   if (!question) return unavailableResearchReport("empty-question");
 
@@ -61,54 +59,54 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
     throw error;
   }
 
-  if (!plan) return unavailableResearchReport("no-evidence");
   const lanes = normalizeResearchLanes(plan);
   if (lanes.length === 0) return unavailableResearchReport("no-evidence");
   progress({ type: "counter", key: "research.lanes", label: "research lanes", value: lanes.length });
   progress({ type: "summary", key: "research.question", value: question });
 
   phase("Gather");
-  const gathered = compactResults(
-    await parallel(
-      lanes.map((lane) => async () => {
-        const result = await agent(
-          `Research one bounded lane using only installed external web-search, browsing, or URL-extraction tools.\n\n` +
-            `Question: ${question}\n` +
-            `Scope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n` +
-            `Lane id: ${lane.id}\nLane: ${lane.title}\nObjective: ${lane.objective}\n` +
-            `Queries:\n${lane.queries.map((query) => `- ${query}`).join("\n")}\n\n` +
-            "Open the supporting pages instead of citing a search-results page. Prefer primary and authoritative sources; use independent sources when useful. " +
-            "Return concrete claims with importance, whether each page supports or conflicts with the claim, a short passage or precise paraphrase, and the exact page title and URL. " +
-            "State evidence gaps. Never invent a URL or claim that the opened page does not support. Structured output only.",
-          {
-            phase: "Gather",
-            label: `gather:${lane.id}`,
-            tools: EXTERNAL_TOOLS,
-            toolHints: EXTERNAL_TOOL_HINTS,
-            requireToolHints: true,
-            profile: "small",
-            resume: "off",
-            schema: ResearchLaneResultSchema,
-          },
-        );
-        if (!result) return null;
-        progress({ type: "counter_delta", key: "research.evidence", label: "evidence items", delta: result.evidence.length });
-        progress({
-          type: "lane_item",
-          lane: "Research lanes",
-          title: lane.title,
-          subtitle: `${result.evidence.length} evidence item(s)`,
-          status: result.evidence.length > 0 ? "success" : "warning",
-          details: result.gaps.join("; ") || lane.objective,
-        });
-        return result;
-      }),
-    ),
+  const gatherResults = await parallel(
+    lanes.map((lane) => async () => {
+      const result = await agent(
+        `Research one bounded lane using only installed external web-search, browsing, or URL-extraction tools.\n\n` +
+          `Question: ${question}\n` +
+          `Scope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n` +
+          `Lane: ${lane.title}\nObjective: ${lane.objective}\n` +
+          `Queries:\n${lane.queries.map((query) => `- ${query}`).join("\n")}\n\n` +
+          "Open the supporting pages instead of citing a search-results page. Prefer primary and authoritative sources; use independent sources when useful. " +
+          "Return concrete claims with importance, whether each page supports or conflicts with the claim, a short passage or precise paraphrase, and the exact page title and URL. " +
+          "State evidence gaps. Never invent a URL or claim that the opened page does not support. Structured output only.",
+        {
+          phase: "Gather",
+          label: `gather:${lane.id}`,
+          tools: EXTERNAL_TOOLS,
+          toolHints: EXTERNAL_TOOL_HINTS,
+          requireToolHints: true,
+          // The prompt embeds lane text planned by a web-enabled agent; never infer skills (and the read tool) from it.
+          skills: [],
+          profile: "small",
+          resume: "off",
+          schema: ResearchLaneResultSchema,
+        },
+      );
+      progress({ type: "counter_delta", key: "research.evidence", label: "evidence items", delta: result.evidence.length });
+      progress({
+        type: "lane_item",
+        lane: "Research lanes",
+        title: lane.title,
+        subtitle: `${result.evidence.length} evidence item(s)`,
+        status: result.evidence.length > 0 ? "success" : "warning",
+        details: result.gaps.join("; ") || lane.objective,
+      });
+      return result;
+    }),
+    { settled: true },
   );
+  const gathered = gatherResults.flatMap((result) => (result.ok ? [result.value] : []));
+  const failedLanes = lanes.filter((_, index) => !gatherResults[index]!.ok);
 
-  const laneResults = sanitizeLaneResults(gathered);
-  const candidates = buildClaimCandidates(laneResults);
-  if (candidates.length === 0) return unavailableResearchReport("no-evidence");
+  const candidates = buildClaimCandidates(gathered);
+  if (candidates.length === 0) return unavailableResearchReport(failedLanes.length > 0 ? "lanes-failed" : "no-evidence");
   progress({ type: "counter", key: "research.claims", label: "claims to verify", value: candidates.length });
   log(`${candidates.length} bounded claim(s) selected for independent verification`);
 
@@ -121,11 +119,13 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
         tools: EXTERNAL_TOOLS,
         toolHints: EXTERNAL_TOOL_HINTS,
         requireToolHints: true,
+        // The prompt embeds web-derived evidence; never infer skills (and the read tool) from it.
+        skills: [],
         profile: "medium",
         resume: "off",
         schema: ResearchVerificationSchema,
       });
-      return result ? sanitizeVerification(result, candidate) : null;
+      return sanitizeVerification(result, candidate);
     }),
   );
   const verifications = verificationResults.map((result, index) => result ?? unavailableVerification(candidates[index]!));
@@ -135,28 +135,36 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
   const synthesisInputs = verifications.filter((verification) => verification.verdict !== "REJECTED");
 
   phase("Synthesize");
-  const synthesis = await agent(
-    `Answer the research question using only the independently verified handoff below.\n\n` +
-      `Question: ${question}\nScope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n\n` +
-      `Verified claims JSON:\n${JSON.stringify(synthesisInputs)}\n\n` +
-      "Keep SUPPORTED claims, CONFLICTED evidence, UNCERTAIN claims, and model INFERENCE in their separate fields. Exclude REJECTED claims. " +
-      "Copy each verified claim string exactly so its citations remain bound to that claim during validation. " +
-      "Every supported or conflicting claim must cite exact title/URL objects from its verification; do not add URLs, cite search-results pages, or turn inference into fact. " +
-      "Answer concisely, disclose limited coverage, and provide useful next steps. Structured output only.",
-    {
-      phase: "Synthesize",
-      label: "synthesize",
-      tools: [],
-      profile: "medium",
-      resume: "off",
-      schema: ResearchReportSchema,
-    },
-  );
+  let synthesis: ResearchReport;
+  try {
+    synthesis = await agent(
+      `Answer the research question using only the independently verified handoff below.\n\n` +
+        `Question: ${question}\nScope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n\n` +
+        `Verified claims JSON:\n${JSON.stringify(synthesisInputs)}\n\n` +
+        "Keep SUPPORTED claims, CONFLICTED evidence, UNCERTAIN claims, and model INFERENCE in their separate fields. Exclude REJECTED claims. " +
+        "Copy each verified claim string exactly so its citations remain bound to that claim during validation. " +
+        "Every supported or conflicting claim must cite exact title/URL objects from its verification; do not add URLs, cite search-results pages, or turn inference into fact. " +
+        "Answer concisely, disclose limited coverage, and provide useful next steps. Structured output only.",
+      {
+        phase: "Synthesize",
+        label: "synthesize",
+        tools: [],
+        // The prompt embeds web-derived claims; never infer skills (and the read tool) from them.
+        skills: [],
+        profile: "medium",
+        resume: "off",
+        schema: ResearchReportSchema,
+      },
+    );
+  } catch (error) {
+    if (isFatalWorkflowError(error, signal)) throw error;
+    synthesis = fallbackResearchReport(synthesisInputs);
+  }
 
-  return sanitizeResearchReport(
-    synthesis ?? fallbackResearchReport(synthesisInputs, "The model did not return a structured synthesis."),
-    synthesisInputs,
-  );
+  const report = sanitizeResearchReport(synthesis, synthesisInputs);
+  if (failedLanes.length === 0) return report;
+  const laneGap = `${failedLanes.length} of ${lanes.length} research lane(s) failed (${failedLanes.map((lane) => lane.title).join(", ")}); coverage is incomplete.`;
+  return { ...report, limitations: [...report.limitations, laneGap] };
 }
 
 function verificationPrompt(question: string, candidate: ResearchClaimCandidate): string {