@lincoln504/pi-research 1.6.0 → 1.6.1

package/agent-skill/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.6.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.6.1", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli.mjs

@@ -2216,6 +2216,29 @@ function lastCitedLinksHeader(text) {
   }
   return { lineStart, textStart };
 }
+function stripReportPreamble(text) {
+  const trimmed = text.trimStart();
+  const breakAt = trimmed.indexOf("\n\n");
+  if (breakAt < 0) return { body: text, preamble: "" };
+  const head = trimmed.slice(0, breakAt).trim();
+  const rest = trimmed.slice(breakAt + 2).trimStart();
+  if (head.includes("\n")) return { body: text, preamble: "" };
+  if (!rest) return { body: text, preamble: "" };
+  if (!REPORT_NARRATION_OPENER.test(head)) return { body: text, preamble: "" };
+  if (!REPORT_NARRATION_SUBJECT.test(head)) return { body: text, preamble: "" };
+  return { body: rest, preamble: head };
+}
+function synthesisProseBody(text) {
+  const { lineStart } = lastCitedLinksHeader(text);
+  return (lineStart < 0 ? text : text.slice(0, lineStart)).trim();
+}
+function isAnalysisFreeSynthesis(text, minProseChars) {
+  const prose = synthesisProseBody(text);
+  const stripped = prose.replace(/^[ \t]*(?:#{1,6}[ \t]*|>[ \t]*|\*\*)/gm, "").trim();
+  if (minProseChars > 0 && stripped.length < minProseChars) return true;
+  if (!/[.!?。！？।॥۔؟።]/.test(stripped)) return true;
+  return false;
+}
 function parseCitations(report) {
   const headerIdx = lastCitedLinksHeaderIndex(report);
   if (headerIdx < 0) return [];
@@ -2268,11 +2291,14 @@ function parseCitations(report) {
   }
   return citations;
 }
+var REPORT_NARRATION_OPENER, REPORT_NARRATION_SUBJECT;
 var init_text_utils = __esm({
   "src/utils/text-utils.ts"() {
     "use strict";
     init_logger();
     init_url_utils();
+    REPORT_NARRATION_OPENER = /^(?:I|I'll|I'm|Let me|Now I|Next I|First,? I)\b/i;
+    REPORT_NARRATION_SUBJECT = /\b(?:report|synthesi[sz]\w*|findings|material|sources|scraped|gathered|research\w*|summar\w+)\b/i;
   }
 });
 
@@ -3217,7 +3243,7 @@ function getMaxScrapeBatches(config, cachingActive = false) {
 function resolveExcludedTools(callerExclusions, configDisabled = []) {
   return [.../* @__PURE__ */ new Set([...DEFAULT_EXCLUDED_TOOLS, ...callerExclusions ?? [], ...configDisabled])];
 }
-var MAX_GATHERING_CALLS, MAX_GREP_CALLS, MAX_SCRAPE_URLS, MAX_TEAM_SIZE_LEVEL_1, MAX_TEAM_SIZE_LEVEL_2, MAX_TEAM_SIZE_LEVEL_3, MAX_ROUNDS_LEVEL_1, MAX_ROUNDS_LEVEL_2, MAX_ROUNDS_LEVEL_3, MAX_EXTRA_ROUNDS_WITH_STEERING, OSV_TIMEOUT_MS, WEBGPU_PROBE_TIMEOUT_MS, MAX_QUERY_LENGTH, MAX_FILENAME_QUERY_LENGTH, MIN_QUERY_LENGTH, MAX_EXPORT_RETRIES, DEFAULT_MAX_RETRIES, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_MODEL_CONTEXT_WINDOW, BATCH_2_DEFAULT_CONCURRENCY, MAX_SCRAPE_CONTENT_CHARS_PER_DOC, RESEARCHER_LAUNCH_DELAY_MS, MAX_QUERIES_PER_RESEARCHER_LEVEL_1, MAX_QUERIES_PER_RESEARCHER_LEVEL_2, MAX_QUERIES_PER_RESEARCHER_LEVEL_3, DEFAULT_EXCLUDED_TOOLS, RESEARCH_TOOL_NAMES;
+var MAX_GATHERING_CALLS, MAX_GREP_CALLS, MAX_SCRAPE_URLS, MAX_TEAM_SIZE_LEVEL_1, MAX_TEAM_SIZE_LEVEL_2, MAX_TEAM_SIZE_LEVEL_3, MAX_ROUNDS_LEVEL_1, MAX_ROUNDS_LEVEL_2, MAX_ROUNDS_LEVEL_3, MAX_EXTRA_ROUNDS_WITH_STEERING, OSV_TIMEOUT_MS, WEBGPU_PROBE_TIMEOUT_MS, MAX_QUERY_LENGTH, MAX_FILENAME_QUERY_LENGTH, MIN_QUERY_LENGTH, MAX_EXPORT_RETRIES, DEFAULT_MAX_RETRIES, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_MODEL_CONTEXT_WINDOW, BATCH_2_DEFAULT_CONCURRENCY, MAX_SCRAPE_CONTENT_CHARS_PER_DOC, RESEARCHER_LAUNCH_DELAY_MS, MAX_QUERIES_PER_RESEARCHER_LEVEL_1, MAX_QUERIES_PER_RESEARCHER_LEVEL_2, MAX_QUERIES_PER_RESEARCHER_LEVEL_3, DEFAULT_EXCLUDED_TOOLS, MIN_SYNTHESIS_PROSE_CHARS, QUICK_THIN_REPORT_NOTICE, SYNTHESIS_FALLBACK_NOTICE, RESEARCH_TOOL_NAMES;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -3249,6 +3275,9 @@ var init_constants = __esm({
     MAX_QUERIES_PER_RESEARCHER_LEVEL_2 = 15;
     MAX_QUERIES_PER_RESEARCHER_LEVEL_3 = 20;
     DEFAULT_EXCLUDED_TOOLS = ["grep"];
+    MIN_SYNTHESIS_PROSE_CHARS = 800;
+    QUICK_THIN_REPORT_NOTICE = "_Note: this run did not produce a substantive write-up. The sources below were retrieved and are cited accurately, but the summary above should not be treated as a complete answer \u2014 consider re-running, or running at a deeper level._";
+    SYNTHESIS_FALLBACK_NOTICE = "_Note: the synthesis step did not produce a usable summary for this run, so the individual researcher reports are included below in full. The sources cited at the end of this document are unaffected._";
     RESEARCH_TOOL_NAMES = [
       "search",
       "scrape",
@@ -23866,6 +23895,19 @@ ${userMessage}`);
         const synthesisService = await getService(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
         synthesisService.storeReport(this.options.researchId, "quick", result);
         result = synthesisService.getReport(this.options.researchId, "quick") ?? result;
+        const { body: withoutPreamble, preamble } = stripReportPreamble(result);
+        if (preamble) {
+          logger.debug(`[QuickOrchestrator] Dropped a ${preamble.length}-char narration preamble from the report: ${preamble.slice(0, 120)}`);
+          metrics.increment("research_report_preamble_stripped_total", 1, { mode: "quick" });
+          result = withoutPreamble;
+        }
+        if (isAnalysisFreeSynthesis(result, 0)) {
+          logger.warn(`[QuickOrchestrator] Report contains no complete sentence (${synthesisProseBody(result).length} char(s) of prose) \u2014 flagging it in the report`);
+          metrics.increment("research_synthesis_analysis_free_total", 1, { mode: "quick" });
+          result = `${result.trim()}
+
+${QUICK_THIN_REPORT_NOTICE}`;
+        }
         result = synthesisService.ensureCitedLinks(this.options.researchId, result);
         const citationSource = result;
         const finalSteeringMessages = getActiveSteeringMessages(this.options.sessionId);
@@ -23976,6 +24018,7 @@ ${result}`);
 init_logger();
 init_metrics();
 init_constants();
+init_text_utils();
 init_service_interfaces();
 init_service_registry();
 init_config();
@@ -24291,6 +24334,13 @@ var DeepResearchOrchestrator = class {
         observer?.onEvaluationDecision?.("synthesize", finalReport, this.currentRound);
       }
       let result = finalReport.content || "";
+      try {
+        const parsed = JSON.parse(result);
+        if (parsed && typeof parsed === "object" && typeof parsed["content"] === "string") {
+          result = parsed["content"];
+        }
+      } catch {
+      }
       if (!result.trim()) {
         if (hasReports) {
           logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisCheckService.getReportCount(researchId)} reports`);
@@ -24298,13 +24348,15 @@ var DeepResearchOrchestrator = class {
         } else {
           throw new Error("Research produced no report \u2014 no source material was collected.");
         }
-      }
-      try {
-        const parsed = JSON.parse(result);
-        if (parsed && typeof parsed === "object" && typeof parsed["content"] === "string") {
-          result = parsed["content"];
-        }
-      } catch {
+      } else if (hasReports && isAnalysisFreeSynthesis(result, MIN_SYNTHESIS_PROSE_CHARS)) {
+        const proseChars = synthesisProseBody(result).length;
+        logger.warn(`[DeepOrchestrator] LLM synthesis for ${researchId} carried no analysis (${proseChars} char(s) of prose, min ${MIN_SYNTHESIS_PROSE_CHARS}) \u2014 appending ${synthesisCheckService.getReportCount(researchId)} researcher report(s) below it`);
+        metrics.increment("research_synthesis_analysis_free_total", 1, { mode: "deep" });
+        result = [
+          result.trim(),
+          SYNTHESIS_FALLBACK_NOTICE,
+          synthesisCheckService.buildFallbackSynthesis(researchId, this.currentRound)
+        ].join("\n\n");
       }
       const synthesisService = await getService(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
       result = synthesisService.ensureCitedLinks(researchId, result);
@@ -25172,7 +25224,7 @@ var ResearchSynthesisService = class _ResearchSynthesisService {
     if (reportCount === 0) {
       synthesis += "No researcher reports were generated before the process stopped.";
     } else {
-      synthesis += `This is an automated synthesis of ${reportCount} individual researcher report(s) gathered before the process was interrupted.
+      synthesis += `This is an automated compilation of ${reportCount} individual researcher report(s). The synthesis step did not produce a usable summary for this run, so the findings are presented as collected.
 
 `;
       synthesis += Array.from(reports.entries()).map(([id, report]) => `Researcher ${id}

package/dist/prompts/researcher.md

@@ -62,6 +62,8 @@ Write your report immediately after scraping is complete, or as soon as a tool r
 ## Report Format
 
 {{digest_section}}
+Emit the report and nothing else. No preamble, and no narration of what you are about to do — not "I have gathered extensive material…", not "Let me now synthesize my findings…". Begin at the report's own first line.
+
 Use [N] inline citations throughout. Write in plain prose — no markdown headings, no bullet points, no bold or italic text. Use clear paragraphs separated by blank lines. The full CITED LINKS list goes at the very end.
 
 [Topic Title]

package/dist/thread-worker.mjs

@@ -2334,12 +2334,19 @@ async function readPdfDownload(download, url, page, pendingAddrChecks, getPoison
   }
   const filePath = await download.path();
   if (!filePath) throw new Error("Fetch blocked: download produced no readable file");
-  const { size } = await fsp.stat(filePath);
-  if (size > MAX_PDF_SIZE) {
-    const sizeMB = Math.round(size / 1024 / 1024);
-    throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
+  const handle = await fsp.open(filePath, "r");
+  let buffer;
+  try {
+    const { size } = await handle.stat();
+    if (size > MAX_PDF_SIZE) {
+      const sizeMB = Math.round(size / 1024 / 1024);
+      throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
+    }
+    buffer = await handle.readFile();
+  } finally {
+    await handle.close().catch(() => {
+    });
   }
-  const buffer = await fsp.readFile(filePath);
   await Promise.allSettled(pendingAddrChecks);
   const poisoned = getPoisonedError();
   if (poisoned) throw poisoned;

package/docs/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.1] - 2026-08-23
+
+A report that contained no analysis was being delivered as a completed run, because
+the engine's own repair step padded it out. Fixing that exposed a second way into the
+same failure, and a review of the machinery around it turned up a third defect.
+
+### Fixed
+
+- **A synthesis with no analysis in it reached users looking like a finished report.** The completion guard was `if (!result.trim())` — a lone title line passes it, and `ensureCitedLinks` then appends the rebuilt source list underneath. Two runs in the retained logs did exactly that: 131 and 147 characters of prose delivered as 6.8KB and 9.9KB documents with a heading, a full citation list, and not one sentence between them, both reported as complete. The engine's own repair machinery was what disguised the failure. A synthesis is now checked for analysis by two independent signals — prose volume measured BEFORE the citation block, and whether any sentence ends at all — and the response is **additive**: the model's own text is kept, the researchers' reports are appended below it, and a notice states what happened. That is the part that matters. Because a false positive can only ever add material, never discard it, the threshold can sit well clear of real reports (800 characters, against a smallest observed legitimate report of 1056) rather than hugging the two failures out of fear of destroying a good run. Quick mode gets the structural signal only: it has no researcher reports to fall back on, so the sole available response is to flag the report — and telling a reader their correct one-sentence answer is untrustworthy is worse than missing a thin one. Its notice says the run produced no substantive write-up and that the cited sources are still accurate (`src/orchestration/deep-research-orchestrator.ts`, `src/orchestration/quick-research-orchestrator.ts`, `src/utils/text-utils.ts`, `src/constants.ts`).
+- **The same failure had a second route in, through the raw JSON envelope.** When upstream JSON parsing fails, the synthesis arrives as the whole envelope string rather than the extracted markdown, and an unwrap ran afterwards to recover it. Both completion checks therefore measured the envelope — long, well punctuated, and healthy-looking whatever it wrapped — and the unwrap then replaced it with the title or the empty string it was hiding, with nothing left to catch either. An envelope wrapping empty content produced a citation list with no document above it. The unwrap now runs first, so every check judges the report itself (`src/orchestration/deep-research-orchestrator.ts`).
+- **The structural signal assumed Latin punctuation.** It looked for `.!?` plus the CJK full stops, so a correct report written with a danda, an Arabic full stop or an Ethiopic full stop ended no sentence as far as the check was concerned. In quick mode, where that signal runs alone, every such report would have been flagged as thin (`src/utils/text-utils.ts`).
+- **A time-of-check/time-of-use gap in the attachment-served PDF path.** The 100MB cap was measured with `fsp.stat(filePath)` and the bytes then read with `fsp.readFile(filePath)` — two separate lookups of a path the browser process is still writing to, so the file that was measured need not be the file that was read (CodeQL `js/file-system-race`, alert #266). The size is now taken from an open handle and the bytes read back through that same handle, which cannot be swapped underneath, and the descriptor is released on both the accept and the over-cap reject (`src/infrastructure/browser/thread-worker-messaging.ts`).
+
+### Changed
+
+- **A quick report no longer opens by narrating itself.** Live runs delivered documents whose first line was "I have gathered extensive material… Let me now synthesize my findings into a comprehensive report." and "I have gathered sufficient material from multiple authoritative sources. I will now synthesize the full report." Quick mode has no synthesis step behind it to absorb that, so it landed as the reader's first sentence. The researcher prompt now forbids it — and, because that instruction was measurably not obeyed (it still appeared in 2 of 3 live runs after the prompt change), quick mode also removes the line. Removing text is destructive, so every condition on it is a required narrowing rather than a score: the segment must be a single line, separated from the report by a blank line, first-person AND about the act of reporting, and must leave a report behind. A report that opens as the format requires — with a topic title — matches none of them. The strip runs BEFORE the analysis check above, so a title-only report cannot pass that check on the strength of the narration's full stop, and each removal is counted in `research_report_preamble_stripped_total` (`src/prompts/researcher.md`, `src/utils/text-utils.ts`, `src/orchestration/quick-research-orchestrator.ts`).
+
+### Removed
+
+- **The GitHub Release job added in 1.6.0 is gone; tags remain the only release marker.** Cutting a Release per tag was not wanted — the tag plus `docs/CHANGELOG.md` is the intended record — so the job was removed and the one Release it created (v1.6.0) was deleted. The tag itself is untouched, and nothing about publishing changes: the release workflow is still CI-gate → tarball test → npm publish (`.github/workflows/release.yml`).
+
+### Verified
+
+- Full gates green: 2917 unit tests across 230 files, type-check over source and tests, lint, dependency-cruiser, and the integration suite (77 passed, 26 skipped for live network).
+- Live runs across all four front-ends: CLI quick and depth-1 (15.5KB and 16.5KB reports), the agent skill launcher through its installed link (11.8KB, opening straight at the report), the pi extension, and the SDK (12.1KB, clean shutdown). Every report was replayed through both guards afterwards: the one real preamble was removed, and neither analysis check fired on any of them.
+
 ## [1.6.0] - 2026-08-22
 
 Driven by log forensics rather than by the test suite: every entry below was found
@@ -32,7 +58,6 @@ and recovered conditions reported as terminal failures.
 
 - **`bgutils-js` upgraded 3.2.0 → 4.0.3**, the YouTube PoToken stack's most upstream-brittle dependency and the one pin with no written rationale. v4 is a hard break: the barrel entry is gone (the package now exposes only `/botguard`, `/webpo` and `/utils` subpaths, so the previous bare import resolves to nothing), `BG.Challenge.create` became a free `getChallenge()` whose config drops `globalObj`/`identifier` and renames `fetch` to `fetchFunction`, and `BotGuardClient`'s `globalObj` became `globalObject`. All three renames fail silently rather than loudly — a wrong `globalObject` leaves the VM with no global to attach to and the minter factory returns a non-function — so each is now pinned by a test that asserts the field names v4 actually reads, and the whole flow was re-validated live: a real PoToken minted against Google's attestation endpoint and a real transcript fetched. Staying on v3 meant sitting on an unmaintained line for the one subsystem that breaks whenever YouTube changes BotGuard, with the failure mode being a silent empty transcript body (`src/youtube/potoken.ts`).
 - **`jsdom` deliberately stays at 29.1.1.** jsdom 30 narrows its supported Node range to `^22.22.2 || ^24.15.0 || >=26.0.0`, which excludes both part of this package's own `>=22.19.0` floor and Node 25 entirely; 29's `^20.19.0 || ^22.13.0 || >=24.0.0` covers the whole supported surface. Attempted, measured against the engine ranges, reverted — the pin now has the same recorded rationale as the others (`package.json`).
-- **Tags now produce GitHub Releases.** 44 tags existed and zero Releases, so each version's changelog entry was reachable only by reading `docs/CHANGELOG.md` in the tree. A new job extracts that version's section from the tag's own copy of the changelog and publishes it. It runs after `publish` and needs it, so a failed npm publish cannot announce a version nobody can install; it holds `contents: write` and nothing else — in particular no `id-token` — and installs nothing, so no dependency lifecycle script runs while that token is live. A version that reached npm with no changelog section fails the job rather than publishing an empty Release (`.github/workflows/release.yml`).
 
 ### Added
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/src/constants.ts

@@ -201,6 +201,36 @@ export const MAX_QUERIES_PER_RESEARCHER_LEVEL_3 = 20;
  */
 export const DEFAULT_EXCLUDED_TOOLS: readonly string[] = ['grep'];
 
+/**
+ * Volume signal for {@link isAnalysisFreeSynthesis}: prose below this, measured BEFORE
+ * the CITED LINKS section, is treated as a synthesis containing no analysis.
+ *
+ * Calibrated against 41 real reports from the run logs rather than guessed. The two
+ * broken ones — each a lone title line, delivered as a "complete" 6.8KB and 9.9KB
+ * document because the engine's own citation rebuild padded them out — measured 131 and
+ * 147 characters. The shortest LEGITIMATE report measured 1056.
+ *
+ * Set at 800 rather than hugging the failures, because the response to tripping it is
+ * ADDITIVE: the model's own text is kept and the researcher reports are appended below
+ * it. A false positive therefore costs some duplication, never a lost report, so the
+ * boundary is placed to catch marginal cases rather than to avoid them. It is also only
+ * one of two independent signals — a synthesis with no sentence-ending punctuation is
+ * caught at any length, so a long title would not slip through on volume alone.
+ */
+export const MIN_SYNTHESIS_PROSE_CHARS = 800;
+
+/** Flags a quick-mode report that contains no analysis, where there is no fallback to add. */
+export const QUICK_THIN_REPORT_NOTICE =
+  '_Note: this run did not produce a substantive write-up. The sources below were ' +
+  'retrieved and are cited accurately, but the summary above should not be treated as ' +
+  'a complete answer — consider re-running, or running at a deeper level._';
+
+/** Explains an additive fallback in the delivered report, so the reader is never misled. */
+export const SYNTHESIS_FALLBACK_NOTICE =
+  '_Note: the synthesis step did not produce a usable summary for this run, so the ' +
+  'individual researcher reports are included below in full. The sources cited at the ' +
+  'end of this document are unaffected._';
+
 /**
  * The complete set of excludable research tool names — the vocabulary
  * `--exclude-tools` / `excludeTools` / PI_RESEARCH_DISABLED_TOOLS accept.

package/src/infrastructure/browser/thread-worker-messaging.ts

@@ -524,14 +524,24 @@ async function readPdfDownload(
 
   // Same 100MB policy cap the PDF branch enforces, checked from the file size so the
   // bytes are never read into the worker at all when the file is over the limit.
-  const { size } = await fsp.stat(filePath);
-  if (size > MAX_PDF_SIZE) {
-    const sizeMB = Math.round(size / 1024 / 1024);
-    throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
+  //
+  // The size is measured on an OPEN HANDLE and the bytes are read back through that
+  // same handle, so the check and the read cannot land on two different files: a
+  // stat-by-path followed by a read-by-path is a time-of-check/time-of-use gap, and
+  // the download directory is a path the browser process is still writing to.
+  const handle = await fsp.open(filePath, 'r');
+  let buffer: Buffer;
+  try {
+    const { size } = await handle.stat();
+    if (size > MAX_PDF_SIZE) {
+      const sizeMB = Math.round(size / 1024 / 1024);
+      throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
+    }
+    buffer = await handle.readFile();
+  } finally {
+    await handle.close().catch(() => {});
   }
 
-  const buffer = await fsp.readFile(filePath);
-
   await Promise.allSettled(pendingAddrChecks);
   const poisoned = getPoisonedError();
   if (poisoned) throw poisoned;

package/src/infrastructure/browser/thread-worker.mjs

@@ -2334,12 +2334,19 @@ async function readPdfDownload(download, url, page, pendingAddrChecks, getPoison
   }
   const filePath = await download.path();
   if (!filePath) throw new Error("Fetch blocked: download produced no readable file");
-  const { size } = await fsp.stat(filePath);
-  if (size > MAX_PDF_SIZE) {
-    const sizeMB = Math.round(size / 1024 / 1024);
-    throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
+  const handle = await fsp.open(filePath, "r");
+  let buffer;
+  try {
+    const { size } = await handle.stat();
+    if (size > MAX_PDF_SIZE) {
+      const sizeMB = Math.round(size / 1024 / 1024);
+      throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
+    }
+    buffer = await handle.readFile();
+  } finally {
+    await handle.close().catch(() => {
+    });
   }
-  const buffer = await fsp.readFile(filePath);
   await Promise.allSettled(pendingAddrChecks);
   const poisoned = getPoisonedError();
   if (poisoned) throw poisoned;

package/src/orchestration/deep-research-orchestrator.ts

@@ -9,7 +9,8 @@ import { type Model } from '@earendil-works/pi-ai';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
 import { getSteeringMessages, consumeQueuedMessages, getActiveSteeringMessages, getFailedResearchers, getResearcherFailureReasons } from './session-state.ts';
-import { MAX_EXTRA_ROUNDS_WITH_STEERING, resolveExcludedTools } from '../constants.ts';
+import { MAX_EXTRA_ROUNDS_WITH_STEERING, MIN_SYNTHESIS_PROSE_CHARS, SYNTHESIS_FALLBACK_NOTICE, resolveExcludedTools } from '../constants.ts';
+import { synthesisProseBody, isAnalysisFreeSynthesis } from '../utils/text-utils.ts';
 import {
   getMaxRounds,
 } from '../core/planning-utils.ts';
@@ -594,6 +595,19 @@ export class DeepResearchOrchestrator {
 
       let result = finalReport.content || '';
 
+      // Unwrap FIRST, before anything judges the content. If the LLM returned the full
+      // JSON envelope as its response text and JSON parsing failed upstream,
+      // finalReport.content is the raw JSON string rather than the extracted markdown —
+      // and every check below would then be measuring the envelope instead of the report.
+      // An envelope wrapping an empty or title-only content read as a long, well-punctuated
+      // document, so neither guard fired and the unwrapped nothing went straight out.
+      try {
+        const parsed: unknown = JSON.parse(result);
+        if (parsed && typeof parsed === 'object' && typeof (parsed as Record<string, unknown>)['content'] === 'string') {
+          result = (parsed as Record<string, unknown>)['content'] as string;
+        }
+      } catch { /* result is not JSON — use as-is */ }
+
       if (!result.trim()) {
           if (hasReports) {
               // Content is empty but reports exist — build a fallback synthesis.
@@ -603,18 +617,30 @@ export class DeepResearchOrchestrator {
               // No reports, no recorded failures, and nothing to ship either.
               throw new Error('Research produced no report — no source material was collected.');
           }
+      } else if (hasReports && isAnalysisFreeSynthesis(result, MIN_SYNTHESIS_PROSE_CHARS)) {
+          // The synthesis LLM returned something, but nothing that constitutes analysis —
+          // twice in the run logs it was a lone title line. `!result.trim()` passes on
+          // that, and ensureCitedLinks then appends the rebuilt source list underneath, so
+          // a 131-character failure reached the user as a 6.8KB document with a heading,
+          // citations, and not one sentence between them, reported as a successful run.
+          //
+          // The response is deliberately ADDITIVE rather than a replacement. Whatever the
+          // model did write is kept, the researchers' own reports are appended below it,
+          // and a notice states plainly what happened. That matters more than the
+          // detector's precision: because a false positive can only ever ADD material,
+          // never discard it, the threshold can sit far away from real reports instead of
+          // hugging them out of fear of destroying a legitimate one. A missed detection
+          // costs a thin report; a false detection costs a few paragraphs of duplication.
+          const proseChars = synthesisProseBody(result).length;
+          logger.warn(`[DeepOrchestrator] LLM synthesis for ${researchId} carried no analysis (${proseChars} char(s) of prose, min ${MIN_SYNTHESIS_PROSE_CHARS}) — appending ${synthesisCheckService.getReportCount(researchId)} researcher report(s) below it`);
+          metrics.increment('research_synthesis_analysis_free_total', 1, { mode: 'deep' });
+          result = [
+              result.trim(),
+              SYNTHESIS_FALLBACK_NOTICE,
+              synthesisCheckService.buildFallbackSynthesis(researchId, this.currentRound),
+          ].join('\n\n');
       }
 
-      // Guard: if the LLM returned the full JSON envelope as its response text and JSON
-      // parsing failed upstream, finalReport.content may be the raw JSON string rather
-      // than the extracted markdown. Unwrap it here so docs never show the raw JSON.
-      try {
-        const parsed: unknown = JSON.parse(result);
-        if (parsed && typeof parsed === 'object' && typeof (parsed as Record<string, unknown>)['content'] === 'string') {
-          result = (parsed as Record<string, unknown>)['content'] as string;
-        }
-      } catch { /* result is not JSON — use as-is */ }
-
       // Final post-processing: Ensure CITED LINKS section is accurate and consistent
       const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
       result = synthesisService.ensureCitedLinks(researchId, result);

package/src/orchestration/quick-research-orchestrator.ts

@@ -17,8 +17,8 @@ import { recordLlmUsage } from '../utils/llm-usage.ts';
 import { logger } from '../logger.ts';
 import { getConfig, type Config } from '../config.ts';
 import { createResearcherSession } from './researcher.ts';
-import { ensureAssistantResponse, parseCitations } from '../utils/text-utils.ts';
-import { getMaxScrapeBatches, resolveExcludedTools } from '../constants.ts';
+import { ensureAssistantResponse, parseCitations, isAnalysisFreeSynthesis, synthesisProseBody, stripReportPreamble } from '../utils/text-utils.ts';
+import { getMaxScrapeBatches, resolveExcludedTools, QUICK_THIN_REPORT_NOTICE } from '../constants.ts';
 import { resolveResearchModel, isPromptCachingActiveForModel } from '../core/llm/research-model-resolver.ts';
 import type { ResearchObserver } from '../core/interfaces/observer-interfaces.ts';
 import { HeadlessObserver, makeSafeObserver, type HeadlessObserverOptions } from './headless-observer.ts';
@@ -354,6 +354,44 @@ export class QuickResearchOrchestrator {
           // digest out of the delivered document.
           result = synthesisService.getReport(this.options.researchId, 'quick') ?? result;
 
+          // Drop a leading line that announces the report instead of being part of it
+          // ("I have gathered sufficient material… I will now synthesize the full
+          // report."). The prompt forbids it and the instruction is not reliably obeyed;
+          // quick mode has nothing behind it to absorb the line, so it lands as the
+          // reader's first sentence. Removed BEFORE the analysis check below, so that
+          // check measures the report rather than the narration about it.
+          const { body: withoutPreamble, preamble } = stripReportPreamble(result);
+          if (preamble) {
+            logger.debug(`[QuickOrchestrator] Dropped a ${preamble.length}-char narration preamble from the report: ${preamble.slice(0, 120)}`);
+            metrics.increment('research_report_preamble_stripped_total', 1, { mode: 'quick' });
+            result = withoutPreamble;
+          }
+
+          // Same disguise as the deep path, and here it is the DELIVERABLE: a report with
+          // no analysis in it — a bare heading, a fragment — is about to have the rebuilt
+          // source list appended below, which pads it to kilobytes and makes a failed run
+          // read as a complete one. Quick mode has no second layer of researcher reports to
+          // fall back on, so the honest response is to say so in the report itself rather
+          // than hand back a heading over a link dump and call it a success.
+          //
+          // The VOLUME signal is deliberately disabled here (0). The 800-character floor was
+          // calibrated on deep reports; quick mode answers a single question and a correct
+          // reply can legitimately be one sentence, and there is no measured distribution of
+          // quick-report lengths to justify any floor. Since the only available response is
+          // a warning, a false positive would tell a user their correct answer is untrustworthy
+          // — strictly worse than missing a thin one. The structural signal is length-independent
+          // and carries no such risk: "Paris is the capital of France." ends a sentence and
+          // passes, a bare title does not and is flagged.
+          //
+          // Added to the body BEFORE ensureCitedLinks so the links land beneath it — the
+          // same ordering constraint the weak-grounding notice observes, because
+          // parseCitations absorbs any text trailing the last entry into its description.
+          if (isAnalysisFreeSynthesis(result, 0)) {
+            logger.warn(`[QuickOrchestrator] Report contains no complete sentence (${synthesisProseBody(result).length} char(s) of prose) — flagging it in the report`);
+            metrics.increment('research_synthesis_analysis_free_total', 1, { mode: 'quick' });
+            result = `${result.trim()}\n\n${QUICK_THIN_REPORT_NOTICE}`;
+          }
+
           // Ensure CITED LINKS section is accurate and consistent
           result = synthesisService.ensureCitedLinks(this.options.researchId, result);
           // Snapshot BEFORE steering guidance is appended: parseCitations absorbs

package/src/orchestration/research-synthesis-service.ts

@@ -277,7 +277,12 @@ export class ResearchSynthesisService implements IService {
     if (reportCount === 0) {
       synthesis += 'No researcher reports were generated before the process stopped.';
     } else {
-      synthesis += `This is an automated synthesis of ${reportCount} individual researcher report(s) gathered before the process was interrupted.\n\n`;
+      // Neutral about WHY the synthesis step produced nothing usable, because there are
+      // now two callers: a run interrupted mid-flight, and one whose synthesis LLM returned
+      // a report with no analysis in it. Asserting an interruption would be inaccurate for
+      // the second, and telling a user the run was interrupted when it was not is exactly
+      // the kind of misleading output this fallback exists to avoid.
+      synthesis += `This is an automated compilation of ${reportCount} individual researcher report(s). The synthesis step did not produce a usable summary for this run, so the findings are presented as collected.\n\n`;
       synthesis += Array.from(reports.entries())
         .map(([id, report]) => `Researcher ${id}\n\n${report}`)
         .join('\n\n');

package/src/prompts/researcher.md

@@ -62,6 +62,8 @@ Write your report immediately after scraping is complete, or as soon as a tool r
 ## Report Format
 
 {{digest_section}}
+Emit the report and nothing else. No preamble, and no narration of what you are about to do — not "I have gathered extensive material…", not "Let me now synthesize my findings…". Begin at the report's own first line.
+
 Use [N] inline citations throughout. Write in plain prose — no markdown headings, no bullet points, no bold or italic text. Use clear paragraphs separated by blank lines. The full CITED LINKS list goes at the very end.
 
 [Topic Title]

package/src/utils/text-utils.ts

@@ -280,6 +280,105 @@ export function lastCitedLinksHeader(text: string): { lineStart: number; textSta
   return { lineStart, textStart };
 }
 
+/**
+ * A first-person opener that announces the report instead of being part of it:
+ * "I have gathered extensive material… Let me now synthesize my findings into a
+ * comprehensive report."
+ *
+ * Deliberately narrow. It has to match a line that is BOTH first-person AND about the
+ * act of reporting, because the only available response is to delete the line, and the
+ * cost of deleting a real one is losing content nothing else can recover.
+ */
+const REPORT_NARRATION_OPENER = /^(?:I|I'll|I'm|Let me|Now I|Next I|First,? I)\b/i;
+const REPORT_NARRATION_SUBJECT =
+  /\b(?:report|synthesi[sz]\w*|findings|material|sources|scraped|gathered|research\w*|summar\w+)\b/i;
+
+/**
+ * Remove a leading line that narrates the report rather than being part of it.
+ *
+ * The researcher prompt forbids this, and the instruction is not reliably obeyed: across
+ * live quick runs the delivered document repeatedly opened with "I have gathered
+ * sufficient material… I will now synthesize the full report." Quick mode has no
+ * synthesis step behind it to absorb that, so it reaches the reader as the report's
+ * first line.
+ *
+ * Every condition here narrows a DESTRUCTIVE action, so each one is required rather than
+ * scored: the segment must be a single line, must be separated from the report by a
+ * blank line, must read as first-person narration ABOUT reporting, and must leave
+ * something behind. A report that opens correctly — with a topic title, as the format
+ * requires — matches none of them.
+ *
+ * @returns the body with the preamble removed, and the preamble itself (empty when
+ *          nothing was stripped) so callers can log and count what they dropped.
+ */
+export function stripReportPreamble(text: string): { body: string; preamble: string } {
+  const trimmed = text.trimStart();
+  const breakAt = trimmed.indexOf('\n\n');
+  if (breakAt < 0) return { body: text, preamble: '' };
+
+  const head = trimmed.slice(0, breakAt).trim();
+  const rest = trimmed.slice(breakAt + 2).trimStart();
+  if (head.includes('\n')) return { body: text, preamble: '' };
+  // Something has to be left. There is deliberately no LENGTH floor beyond that: a
+  // short remainder is the answer ("Paris is the capital of France."), and keeping the
+  // narration to pad it out would both deliver the wrong text and let that narration's
+  // full stop satisfy the analysis check that runs on the result.
+  if (!rest) return { body: text, preamble: '' };
+  if (!REPORT_NARRATION_OPENER.test(head)) return { body: text, preamble: '' };
+  if (!REPORT_NARRATION_SUBJECT.test(head)) return { body: text, preamble: '' };
+
+  return { body: rest, preamble: head };
+}
+
+/**
+ * The prose body of a synthesis: everything before its CITED LINKS section, trimmed.
+ * Returns the whole text when there is no such section.
+ *
+ * Exists to measure how much the model ACTUALLY wrote. Length alone cannot do that,
+ * because the engine rebuilds and appends the citation list itself — a report whose
+ * body is one title line still comes out kilobytes long once that block lands, which
+ * is precisely how a synthesis containing no analysis reached users looking complete.
+ */
+export function synthesisProseBody(text: string): string {
+  const { lineStart } = lastCitedLinksHeader(text);
+  return (lineStart < 0 ? text : text.slice(0, lineStart)).trim();
+}
+
+/**
+ * Whether a synthesis carries no actual analysis — a heading with nothing under it,
+ * a stray sentence fragment, or an empty string.
+ *
+ * Two INDEPENDENT signals, either of which is enough, so the check does not rest on a
+ * single tuned number:
+ *
+ *  - Volume. Less prose than a real report could possibly contain. Pass 0 to DISABLE
+ *    this signal, which callers must do wherever no length data justifies a floor:
+ *    a wrongly-flagged report is worse than a missed one when the only available
+ *    response is to warn the reader about output that is actually fine.
+ *  - Structure. No sentence ever ends. Every observed failure was a bare title line,
+ *    which has no terminator at all; any genuine report has many. This one needs no
+ *    threshold and would catch a title of any length.
+ *
+ * Measured on the prose only — the text before CITED LINKS — because the engine
+ * rebuilds and appends the source list itself, which pads a one-line failure out to
+ * kilobytes and is exactly how such a report reached users looking complete.
+ */
+export function isAnalysisFreeSynthesis(text: string, minProseChars: number): boolean {
+  const prose = synthesisProseBody(text);
+  // Drop markdown heading markers and blockquote/bold decoration before judging, so a
+  // model that writes "## Title" is measured the same as one that writes "Title".
+  const stripped = prose.replace(/^[ \t]*(?:#{1,6}[ \t]*|>[ \t]*|\*\*)/gm, '').trim();
+  if (minProseChars > 0 && stripped.length < minProseChars) return true;
+  // A report with no sentence-ending punctuation anywhere is a heading, a fragment or a
+  // list of bare labels — never analysis. The terminator set must not assume Latin
+  // punctuation: a report written in a script that ends sentences with a danda, an
+  // Arabic full stop or a CJK full stop is a correct report, and this signal is the only
+  // one quick mode runs, where a false positive tells the reader a good answer is
+  // untrustworthy.
+  if (!/[.!?。！？।॥۔؟።]/.test(stripped)) return true;
+  return false;
+}
+
 /**
  * Parses the CITED LINKS section from a researcher report, extracting URLs, sources, and their descriptions.
  * Handles both single-line 'URL - description' and multi-line 'Source:'/'Description:' formats.