@lincoln504/pi-research 1.6.0 → 1.6.2

package/README.md

@@ -44,11 +44,13 @@ npm install -g @lincoln504/pi-research
 pi-research skill install
 ```
 
-In pi it works out of the box on the session's model and pi's configuration. Standalone use ([agent skill](docs/AGENT-SKILL.md) or [SDK](docs/SDK.md)) needs a model configured. See [Configuration](docs/CONFIGURATION.md). The first install pulls the stealth browser engine, which takes a few minutes.
+On npm 12 or newer, add `--allow-scripts` to either install above. npm 12 stopped running dependency install scripts by default, and the stealth browser's native dependencies are built by one — without it searches fail with a missing-module error rather than a warning at install time.
+
+In pi it works out of the box on the session's model and pi's configuration. Standalone use ([agent skill](docs/AGENT-SKILL.md) or [SDK](docs/SDK.md)) needs a model configured. See [Configuration](docs/CONFIGURATION.md). The first install downloads the stealth browser engine, which takes a few minutes.
 
 ### How it works
 
-A research run loops through agent teams: a coordinator plans and opens with a search, researcher agents scrape and read in parallel, and a research lead decides whether to go another round — then writes the report from every report collected. The result is one cited Markdown report with findings optionally saved to the knowledge store.
+A research run loops through agent teams: a coordinator plans and starts with a search, researcher agents scrape and read in parallel, and a research lead decides whether to go another round — then writes the report from every report collected. The result is one cited Markdown report with findings optionally saved to the knowledge store.
 
 Three depth levels (normal, deep, ultra) set the team size and number of rounds. A natural-language request is enough — the tool picks the right one:
 
@@ -64,10 +66,10 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 ### Why pi-research
 
 - **No quota and no monthly fee.** Most AI search providers cap free searches and then charge, with results served from their index on their servers. pi-research searches and scrapes locally through DuckDuckGo in a stealth browser.
-- **The index stays local.** Every finding can be saved to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
+- **The index is local.** Every finding can be saved to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
 - **Cited reports rather than raw dumps.** Each run returns one sourced Markdown report instead of raw web content pasted into the conversation. Context efficient and easy to verify.
 - **Read-only by design.** The research agent cannot run shell commands or write, edit, or delete anything — the right shape for an agent whose whole job is reading untrusted web pages. Prompt injection picked up mid-run has nothing to act on.
-- **Search a little or a lot.** Depth levels span a quick pass to a large-scale investigation.
+- **Search a little or a lot.** Depth levels range from a quick pass to a large-scale investigation.
 
 ### Requirements / limitations
 
@@ -75,7 +77,7 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 - An LLM with a 100k+ context window (an API key or a local model)
 - Internet access on a residential IP, since search, scraping, and YouTube transcripts get bot-blocked from datacenter/VPS/cloud IPs
 - pi. The pi extension uses the host's copy while the standalone CLI and agent skill install it as a dependency.
-- Cloudflare and similar systems block scraping on some sites. A run flags unreachable pages and compensates with a wide pool of search results to cite.
+- Cloudflare Turnstile and similar systems block scraping on some sites. A run compensates with a wide pool of search results to scrape.
 
 ### Channels
 

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.2", "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",
@@ -10254,9 +10283,17 @@ function detectHarnesses(opts) {
       }
     } catch {
     }
-    return { ...h, present, absSkillsDir, absSkillPath, installed };
+    const broken = (installed === "owned-symlink" || installed === "owned-copy") && !isUsableSkillDir(absSkillPath);
+    return { ...h, present, absSkillsDir, absSkillPath, installed, broken };
   });
 }
+function isUsableSkillDir(p) {
+  try {
+    return fs16.existsSync(path18.join(p, "SKILL.md")) && fs16.existsSync(path18.join(p, "scripts", "run.mjs"));
+  } catch {
+    return false;
+  }
+}
 function isSymlinkPresent(p) {
   try {
     return fs16.lstatSync(p).isSymbolicLink();
@@ -10426,8 +10463,8 @@ function reconcileSkillInstalls(opts = {}) {
   const keep = [];
   for (const e of manifest.entries) {
     if (e.type !== "symlink") {
-      const stale2 = currentVersion !== null && e.version !== currentVersion;
-      if (stale2 && source !== null && fs16.existsSync(e.path) && isOwnedCopy(e.path)) {
+      const stale = currentVersion !== null && e.version !== currentVersion;
+      if (stale && source !== null && fs16.existsSync(e.path) && isOwnedCopy(e.path)) {
         const dir2 = path18.dirname(e.path);
         const base2 = path18.basename(e.path);
         try {
@@ -10504,14 +10541,8 @@ function reconcileSkillInstalls(opts = {}) {
       keep.push(e);
       continue;
     }
-    const targetLive = fs16.existsSync(e.path);
-    let dest = null;
-    try {
-      dest = path18.resolve(path18.dirname(e.path), fs16.readlinkSync(e.path));
-    } catch {
-    }
-    const stale = source !== null && dest !== null && dest !== path18.resolve(source);
-    if (!targetLive || stale) {
+    const targetLive = fs16.existsSync(e.path) && isUsableSkillDir(e.path);
+    if (!targetLive) {
       if (source !== null) {
         try {
           fs16.unlinkSync(e.path);
@@ -12289,6 +12320,7 @@ import * as crypto4 from "node:crypto";
 import { join as join8 } from "node:path";
 import { existsSync as existsSync6, mkdirSync as mkdirSync3 } from "node:fs";
 import { platform, homedir as homedir3 } from "node:os";
+import { createRequire as createRequire3 } from "node:module";
 function getWindowsCamoufoxDir() {
   return join8(homedir3(), "AppData", "Local", "camoufox", "camoufox", "Cache");
 }
@@ -12397,6 +12429,20 @@ function resolveHeadlessMode() {
   if (process.env["PI_RESEARCH_USE_XVFB"] === "true") return "virtual";
   return true;
 }
+function probeBrowserNativeDeps(load = defaultNativeDepLoad) {
+  try {
+    load();
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message.split("\n")[0].trim() : String(err) };
+  }
+}
+function defaultNativeDepLoad() {
+  const require2 = createRequire3(import.meta.url);
+  const Database = require2("better-sqlite3");
+  const db = new Database(":memory:");
+  db.close();
+}
 function isBrowserAvailable() {
   if (isFullMockMode()) return false;
   try {
@@ -12489,6 +12535,11 @@ function isPoolShutdownError(error) {
   // same transient swap the "being reset" string covers, not a hard fault.
   err.message.includes("Cannot execute a task on not started pool"));
 }
+var NATIVE_BINDING_FAILURE = /Could not locate the bindings file|ERR_DLOPEN_FAILED|NODE_MODULE_VERSION|was compiled against a different Node\.js version|invalid ELF header|Cannot find module '[^']*\.node'/;
+function isNativeBindingError(error) {
+  const msg2 = error instanceof Error ? error.message : String(error);
+  return NATIVE_BINDING_FAILURE.test(msg2);
+}
 var BENIGN_NAVIGATION_FAILURE = /page\.goto: (?:Timeout \d+ *ms exceeded|net::|NS_ERROR_|SEC_ERROR_|MOZILLA_PKIX_ERROR_)/;
 function isBenignScrapeFailure(error) {
   const msg2 = error instanceof Error ? error.message : String(error);
@@ -15720,7 +15771,7 @@ import { FixedClusterPool, WorkerChoiceStrategies } from "poolifier";
 // src/infrastructure/browser/ensure-browser.ts
 init_logger();
 import { spawn as spawn2 } from "node:child_process";
-import { createRequire as createRequire3 } from "node:module";
+import { createRequire as createRequire4 } from "node:module";
 import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync7, readdirSync as readdirSync3, statSync as statSync3, fstatSync, openSync as openSync4, closeSync as closeSync4, rmSync } from "node:fs";
 import { join as join11, dirname as dirname8 } from "node:path";
@@ -15747,7 +15798,7 @@ function isBrowserBinaryPresent() {
 }
 function resolveCamoufoxBin() {
   try {
-    const require2 = createRequire3(import.meta.url);
+    const require2 = createRequire4(import.meta.url);
     const pkgJson = require2.resolve("camoufox-js/package.json");
     const bin = join11(dirname8(pkgJson), "..", ".bin", process.platform === "win32" ? "camoufox-js.cmd" : "camoufox-js");
     if (existsSync7(bin)) return bin;
@@ -17503,6 +17554,12 @@ async function performSearch(queries, config, signal, onProgress, container = ge
     } else if (timeoutCount + errorCount === filteredQueries.length) {
       reason = `${timeoutCount} queries timed out and ${errorCount} queries failed`;
     }
+    if (isNativeBindingError(sampleWorkerError)) {
+      metrics.increment("browser_search_total_failures_total", 1, { cause: "native_binding" });
+      throw new Error(
+        `Search completely failed: ${reason}, all with a missing native module. This is an incomplete install, not a network problem: the browser engine's native dependencies were never built. npm 12 does not run dependency install scripts by default \u2014 reinstall allowing them (npm install @lincoln504/pi-research --allow-scripts, or npm approve-scripts --allow-scripts-pending), then retry.` + (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : "")
+      );
+    }
     throw new Error(
       `Search completely failed: ${reason}. Browser workers may be unavailable, DuckDuckGo is unreachable, or the system is under extreme load.` + (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : "")
     );
@@ -23866,6 +23923,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 +24046,7 @@ ${result}`);
 init_logger();
 init_metrics();
 init_constants();
+init_text_utils();
 init_service_interfaces();
 init_service_registry();
 init_config();
@@ -24291,6 +24362,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 +24376,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 +25252,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}
@@ -26655,11 +26735,12 @@ async function cmdStatus(json) {
   const paths = resolvedConfigPaths();
   const cfg = getConfig(process.cwd(), "cli");
   const browserInstalled = isBrowserAvailable();
+  const nativeDeps = probeBrowserNativeDeps();
   const summary = {
     package: "@lincoln504/pi-research",
     version: PKG_VERSION,
     cli: `node ${process.argv[1]}`,
-    ready: !det.problem,
+    ready: !det.problem && nativeDeps.ok,
     credentials: {
       source: det.source,
       apiKeyConfigured: det.apiKeyConfigured,
@@ -26670,6 +26751,9 @@ async function cmdStatus(json) {
     },
     browser: {
       installed: browserInstalled,
+      nativeDepsOk: nativeDeps.ok,
+      nativeDepsError: nativeDeps.ok ? null : nativeDeps.error,
+      nativeDepsFix: nativeDeps.ok ? null : "Reinstall allowing dependency install scripts: npm install -g @lincoln504/pi-research --allow-scripts (npm 12 turns them off by default).",
       // Same remedy the health check prints, so both surfaces name one command.
       fix: browserInstalled ? null : "npx camoufox-js fetch",
       note: browserInstalled ? null : "Stealth browser not installed \u2014 scraping falls back to plain fetch, which some sites block. npm 11.19+ blocks install scripts by default, which skips this package's postinstall."
@@ -26687,7 +26771,16 @@ async function cmdStatus(json) {
   toStdout(`ready: ${summary.ready ? "yes" : "no"}
 
 `);
-  toStdout(configBlock(det, summary.ready ? void 0 : "\u2014 fix the problem above, then re-run.") + "\n");
+  toStdout(configBlock(det, det.problem ? "\u2014 fix the problem above, then re-run." : void 0) + "\n");
+  if (!summary.browser.nativeDepsOk) {
+    toStdout(`
+browser engine: BROKEN \u2014 native dependencies were never built, so no search can run.
+`);
+    toStdout(`  ${summary.browser.nativeDepsFix}
+`);
+    toStdout(`  Underlying error: ${summary.browser.nativeDepsError}
+`);
+  }
   if (!summary.browser.installed) {
     toStdout(`
 stealth browser: NOT INSTALLED \u2014 run: ${summary.browser.fix}
@@ -26760,7 +26853,7 @@ async function cmdSkill(s) {
       toStdout(pretty({
         command: "skill",
         action: "status",
-        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, path: d.absSkillPath }))
+        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, broken: d.broken, path: d.absSkillPath }))
       }));
       return EXIT.OK;
     }
@@ -26768,7 +26861,8 @@ async function cmdSkill(s) {
 
 `);
     for (const d of agents) {
-      const state = !d.present ? "agent not detected" : d.installed === "none" ? "not installed" : d.installed === "foreign" ? "a different skill occupies this slot \u2014 left untouched" : `installed (${d.installed === "owned-copy" ? "copy" : "symlink"})`;
+      const kind = d.installed === "owned-copy" ? "copy" : "symlink";
+      const state = !d.present ? "agent not detected" : d.installed === "none" ? "not installed" : d.installed === "foreign" ? "a different skill occupies this slot \u2014 left untouched" : d.broken ? `BROKEN ${kind} \u2014 target is missing or incomplete; re-run \`${BINARY_NAME} skill install\`` : `installed (${kind})`;
       const loc = d.installed === "owned-symlink" || d.installed === "owned-copy" ? `  \u2192 ${d.absSkillPath}` : "";
       toStdout(`  ${d.label.padEnd(18)} ${state}${loc}
 `);

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,54 @@ 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.2] - 2026-08-24
+
+An agent-skill run reported that every search had failed and concluded it had hit an
+unfixable environment problem. It was half right: the install really was broken, but
+nothing in the tool would say so, and one of the two causes was the tool's own doing.
+
+### Fixed
+
+- **A second install captured the skill links of the first.** `reconcileSkillInstalls()` runs on every engine-touching CLI invocation and resolves its source from whichever copy is being invoked. It re-pointed any owned link whose destination differed — including a perfectly healthy one — so an ordinary second install captured the user's global Claude/Codex/OpenClaw skill links merely by being run once. That is a documented setup, not an exotic one: `docs/SDK.md` instructs users to `npm install @lincoln504/pi-research` INTO their project so the SDK imports resolve, and anything that then ran the project-local CLI moved the global skill into the project. Moving, cleaning or deleting the project later killed the skill with an opaque `Cannot find module …/scripts/run.mjs`. Reconcile now repairs only a link that is dangling or whose target has been gutted — the case it was written for, which is what an update that relocates the package actually produces. Choosing between two live installs is what the explicit `skill install` is for. Two existing tests asserted the old behaviour and were unfaithful in the same way: each described "package relocated by an update" while leaving the old directory on disk, so the link never dangled (`src/skill-install/skill-installer.ts`).
+- **`skill status` called a dead skill installed.** Detection tested that the link existed, never that it resolved, so a dangling symlink reported as `installed (symlink)` — leaving the harness's later "Cannot find module" as the only signal anything was wrong. A link or copy whose target is missing, or which lacks `SKILL.md` / `scripts/run.mjs`, is now reported as BROKEN with the command that repairs it (`src/skill-install/skill-installer.ts`, `src/cli.ts`).
+- **`status` reported a build that cannot search as ready.** npm 12 turns dependency install scripts off by default. `camoufox-js` needs `better-sqlite3` to launch a browser at all, and its binding is produced by exactly such a script — so the module imports fine and throws only at first use. `ready` was derived from credentials alone and said yes; `isBrowserAvailable()` only stats the camoufox binary and never sees it. Measured across every native dependency this package ships: better-sqlite3 is the ONLY one that fails that way — onnxruntime-node carries its binding inside its own tarball, and lancedb, impit and html-to-markdown resolve prebuilt platform packages, which is why the knowledge store kept answering while search was dead. `status` now opens an in-memory database to settle it, gates `ready` on the result, and prints the remedy. The old comment claiming "nothing else fails" was wrong and is corrected (`src/infrastructure/browser/config.ts`, `src/cli.ts`).
+- **A broken install was reported as a network outage.** With no binding, every browser worker dies identically and the run said browser workers may be unavailable, DuckDuckGo unreachable, or the system under extreme load. All three were false and none is actionable — a calling agent read it and gave up rather than reinstalling. A total search failure whose workers all died on a missing native module now says it is an incomplete install and names the flag that fixes it (`src/infrastructure/browser/browser-error-utils.ts`, `src/web-research/browser-search.ts`).
+
+### Changed
+
+- **README documents the npm 12 install flag** on the install commands themselves, and drops a claim that a run flags unreachable pages. Turnstile is named because it is the challenge readers actually hit, and a handful of inflated verbs are now plain ones.
+
+### Verified
+
+- 2938 unit tests over 233 files, lint, type-check over source and tests, dependency-cruiser.
+- The failure mode was reproduced and the remedy measured: a scripts-blocked install of 1.6.1 fails `better-sqlite3` at first use and passes every other native dependency. A live agent-skill run through the installed link completes clean with zero binding errors.
+
+## [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 +80,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.2",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -45,7 +45,7 @@ import { getConfig, getGlobalConfigDir, getGlobalEnvFilePath, getInterfaceEnvFil
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { buildModelRegistry, safeGetAvailable } from './core/llm/model-registry-factory.ts';
 import { RESEARCH_TOOL_NAMES } from './constants.ts';
-import { isBrowserAvailable } from './infrastructure/browser/config.ts';
+import { isBrowserAvailable, probeBrowserNativeDeps } from './infrastructure/browser/config.ts';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -796,19 +796,25 @@ async function cmdStatus(json?: boolean): Promise<number> {
   // (scripts/setup.cjs), which npm 11.19+ BLOCKS BY DEFAULT — it now warns
   // "packages have install scripts not yet covered by allowScripts" and carries
   // on, so the browser is simply absent on an otherwise successful install.
-  // Every other native artifact survives that (onnxruntime, sharp, esbuild and
-  // webgpu all ship prebuilt platform packages), which is exactly what makes
-  // this one worth reporting: nothing else fails, and without this the first
-  // symptom is a scrape falling back mid-run. A missing browser degrades
-  // capability rather than breaking the tool — the fetch path still serves most
-  // pages — so it is reported alongside `ready` rather than folded into it.
-  // isBrowserAvailable() is a resolve + existsSync; it never launches anything.
+  // A missing browser DEGRADES capability rather than breaking the tool — the fetch
+  // path still serves most pages — so it is reported alongside `ready` rather than
+  // folded into it. isBrowserAvailable() is a resolve + existsSync; it never launches
+  // anything.
+  //
+  // The browser's NATIVE DEPENDENCIES are a separate and harsher question, and were
+  // previously assumed away here with "nothing else fails". Measured: better-sqlite3,
+  // which camoufox-js needs to launch at all, is built by a dependency install script
+  // and does NOT survive a scripts-blocked install. When it is missing every browser
+  // worker dies and SEARCH IS DEAD — not degraded — while the knowledge store keeps
+  // working because onnxruntime and lancedb both ship their binaries. That is not a
+  // capability note, so it gates `ready`: a build that cannot search cannot research.
   const browserInstalled = isBrowserAvailable();
+  const nativeDeps = probeBrowserNativeDeps();
   const summary = {
     package: '@lincoln504/pi-research',
     version: PKG_VERSION,
     cli: `node ${process.argv[1]}`,
-    ready: !det.problem,
+    ready: !det.problem && nativeDeps.ok,
     credentials: {
       source: det.source,
       apiKeyConfigured: det.apiKeyConfigured,
@@ -819,6 +825,11 @@ async function cmdStatus(json?: boolean): Promise<number> {
     },
     browser: {
       installed: browserInstalled,
+      nativeDepsOk: nativeDeps.ok,
+      nativeDepsError: nativeDeps.ok ? null : nativeDeps.error,
+      nativeDepsFix: nativeDeps.ok
+        ? null
+        : 'Reinstall allowing dependency install scripts: npm install -g @lincoln504/pi-research --allow-scripts (npm 12 turns them off by default).',
       // Same remedy the health check prints, so both surfaces name one command.
       fix: browserInstalled ? null : 'npx camoufox-js fetch',
       note: browserInstalled
@@ -837,7 +848,19 @@ async function cmdStatus(json?: boolean): Promise<number> {
 
   toStdout(`pi-research ${PKG_VERSION}\n`);
   toStdout(`ready: ${summary.ready ? 'yes' : 'no'}\n\n`);
-  toStdout(configBlock(det, summary.ready ? undefined : '— fix the problem above, then re-run.') + '\n');
+  // The hint points at the CONFIG block, so it belongs to a credential problem only.
+  // `ready` can now also be false because the browser's native deps are missing, and
+  // that is reported below with its own remedy — sending the reader back to a config
+  // block that has nothing wrong with it would be its own small lie.
+  toStdout(configBlock(det, det.problem ? '— fix the problem above, then re-run.' : undefined) + '\n');
+  if (!summary.browser.nativeDepsOk) {
+    // Printed BEFORE the browser-download note: a missing binary is a degradation the
+    // fetch path covers, while a missing binding means no search runs at all. The more
+    // severe problem has to be the one the reader sees first.
+    toStdout(`\nbrowser engine: BROKEN — native dependencies were never built, so no search can run.\n`);
+    toStdout(`  ${summary.browser.nativeDepsFix}\n`);
+    toStdout(`  Underlying error: ${summary.browser.nativeDepsError}\n`);
+  }
   if (!summary.browser.installed) {
     toStdout(`\nstealth browser: NOT INSTALLED — run: ${summary.browser.fix}\n`);
     toStdout(`  ${summary.browser.note}\n`);
@@ -940,16 +963,21 @@ async function cmdSkill(s: NonNullable<ParsedArgs['skill']>): Promise<number> {
     if (s.json) {
       toStdout(pretty({
         command: 'skill', action: 'status',
-        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, path: d.absSkillPath })),
+        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, broken: d.broken, path: d.absSkillPath })),
       }));
       return EXIT.OK;
     }
     toStdout(`pi-research agent skill — install status\n\n`);
     for (const d of agents) {
+      // A broken install must not read as a working one. It said "installed (symlink)"
+      // for a link whose target had been deleted, so the only sign anything was wrong
+      // came later, from the harness, as "Cannot find module …/scripts/run.mjs".
+      const kind = d.installed === 'owned-copy' ? 'copy' : 'symlink';
       const state = !d.present ? 'agent not detected'
         : d.installed === 'none' ? 'not installed'
         : d.installed === 'foreign' ? 'a different skill occupies this slot — left untouched'
-        : `installed (${d.installed === 'owned-copy' ? 'copy' : 'symlink'})`;
+        : d.broken ? `BROKEN ${kind} — target is missing or incomplete; re-run \`${BINARY_NAME} skill install\``
+        : `installed (${kind})`;
       const loc = d.installed === 'owned-symlink' || d.installed === 'owned-copy' ? `  → ${d.absSkillPath}` : '';
       toStdout(`  ${d.label.padEnd(18)} ${state}${loc}\n`);
     }

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/browser-error-utils.ts

@@ -124,6 +124,27 @@ export function isPoolShutdownError(error: unknown): boolean {
     );
 }
 
+/**
+ * A native addon that is missing or unloadable, i.e. a BROKEN INSTALL rather than
+ * anything about the page, the network or the load on the machine.
+ *
+ * The case that produced this: npm 12 turns `allowScripts` OFF by default, so a
+ * plain `npm install` no longer runs dependency lifecycle scripts — including the
+ * one that fetches/builds `better-sqlite3`, which `camoufox-js` needs to launch a
+ * browser at all. Every browser worker then dies with "Could not locate the
+ * bindings file", every query fails, and the run reported that DuckDuckGo might be
+ * unreachable or the machine under extreme load. Neither was true, and the advice
+ * that follows from each is useless. An install fault has to say so.
+ */
+const NATIVE_BINDING_FAILURE =
+  /Could not locate the bindings file|ERR_DLOPEN_FAILED|NODE_MODULE_VERSION|was compiled against a different Node\.js version|invalid ELF header|Cannot find module '[^']*\.node'/;
+
+/** True when the failure is a missing/unloadable native addon — a broken install. */
+export function isNativeBindingError(error: unknown): boolean {
+  const msg = error instanceof Error ? error.message : String(error);
+  return NATIVE_BINDING_FAILURE.test(msg);
+}
+
 /** Playwright navigation failures whose cause is at the remote end — see below. */
 const BENIGN_NAVIGATION_FAILURE =
   /page\.goto: (?:Timeout \d+ *ms exceeded|net::|NS_ERROR_|SEC_ERROR_|MOZILLA_PKIX_ERROR_)/;

package/src/infrastructure/browser/config.ts

@@ -12,6 +12,7 @@ import { platform, homedir } from 'node:os';
 import type { Config } from '../../config.ts';
 import { getConfig } from '../../config.ts';
 import { getLogger } from '../../logger.ts';
+import { createRequire } from 'node:module';
 
 // ============================================================================
 // Binary Cache Management
@@ -310,6 +311,48 @@ export function resolveHeadlessMode(): boolean | 'virtual' {
  * 
  * Single point of control: all existing skipTests() checks use this function.
  */
+/**
+ * Whether the browser stack's NATIVE dependencies can actually load.
+ *
+ * `isBrowserAvailable()` answers a different question — is the camoufox binary on
+ * disk — and a browser can be fully downloaded and still unable to launch. camoufox-js
+ * requires `better-sqlite3`, whose binding is produced by a dependency INSTALL SCRIPT,
+ * and npm 12 turns those off by default. The module then imports fine and throws only
+ * when first used, so nothing notices until every browser worker dies mid-run with
+ * "Could not locate the bindings file" and the run reports a network problem it does
+ * not have.
+ *
+ * Measured, not assumed: of this package's native dependencies, only better-sqlite3
+ * fails a scripts-blocked install. onnxruntime-node ships its binding inside its own
+ * tarball, and lancedb, impit and html-to-markdown all resolve prebuilt platform
+ * packages, so the knowledge store keeps working while search is dead — exactly the
+ * split seen in the field.
+ *
+ * Opening an in-memory database is the only check that settles it: resolving the
+ * module or stat-ing a path does not, because the failure is in the binding lookup at
+ * first use. It costs a few milliseconds and is confined to diagnostics.
+ */
+export function probeBrowserNativeDeps(
+    /** Injected for tests. Production callers pass nothing. */
+    load: () => void = defaultNativeDepLoad,
+): { ok: true } | { ok: false; error: string } {
+    try {
+        load();
+        return { ok: true };
+    } catch (err) {
+        // First line only: the bindings error enumerates every path it tried, which is
+        // pages of noise in a status block. The rest is in the log if it is wanted.
+        return { ok: false, error: err instanceof Error ? err.message.split('\n')[0]!.trim() : String(err) };
+    }
+}
+
+function defaultNativeDepLoad(): void {
+    const require = createRequire(import.meta.url);
+    const Database = require('better-sqlite3') as new (p: string) => { close(): void };
+    const db = new Database(':memory:');
+    db.close();
+}
+
 export function isBrowserAvailable(): boolean {
     if (isFullMockMode()) return false;
     try {

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/skill-install/skill-installer.ts

@@ -325,6 +325,14 @@ export interface DetectedHarness extends HarnessDef {
   absSkillPath: string;
   /** Current install state of THIS skill at that path. */
   installed: 'none' | 'owned-symlink' | 'owned-copy' | 'foreign';
+  /**
+   * Ours, but not usable: the symlink dangles, or the directory it resolves to is
+   * missing SKILL.md / scripts/run.mjs. Reported because the alternative is what
+   * actually happened — `skill status` said "installed (symlink)" for a link whose
+   * target had been deleted, so the only signal the user got was the harness failing
+   * later with "Cannot find module …/scripts/run.mjs".
+   */
+  broken: boolean;
 }
 
 export function detectHarnesses(opts?: { home?: string }): DetectedHarness[] {
@@ -342,10 +350,28 @@ export function detectHarnesses(opts?: { home?: string }): DetectedHarness[] {
         else installed = 'foreign';
       }
     } catch { /* none */ }
-    return { ...h, present, absSkillsDir, absSkillPath, installed };
+    const broken = (installed === 'owned-symlink' || installed === 'owned-copy')
+      && !isUsableSkillDir(absSkillPath);
+    return { ...h, present, absSkillsDir, absSkillPath, installed, broken };
   });
 }
 
+/**
+ * The two files a skill directory is useless without: the manifest a harness reads to
+ * discover the skill, and the launcher it executes. A link or copy can exist while the
+ * thing it points at does not — the target was deleted, moved, or partially removed —
+ * and the harness then fails at invocation time with "Cannot find module …/run.mjs",
+ * which says nothing about the install being the problem. Checked rather than assumed
+ * so both `skill status` and the startup reconcile can tell a live install from a
+ * hollow one.
+ */
+function isUsableSkillDir(p: string): boolean {
+  try {
+    return fs.existsSync(path.join(p, 'SKILL.md'))
+        && fs.existsSync(path.join(p, 'scripts', 'run.mjs'));
+  } catch { return false; }
+}
+
 function isSymlinkPresent(p: string): boolean {
   try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; }
 }
@@ -695,12 +721,23 @@ export function reconcileSkillInstalls(opts: InstallOptions = {}): ReconcileResu
     // Only ever touch links we own; a foreign link at this path stays + tracked.
     if (!isOwnedSymlink(e.path)) { keep.push(e); continue; }
 
-    const targetLive = fs.existsSync(e.path); // existsSync follows the link
-    let dest: string | null = null;
-    try { dest = path.resolve(path.dirname(e.path), fs.readlinkSync(e.path)); } catch { /* unreadable */ }
-
-    const stale = source !== null && dest !== null && dest !== path.resolve(source);
-    if (!targetLive || stale) {
+    // A target that resolves but has been gutted (partial delete, interrupted
+    // install, pruned tree) is as dead as one that is gone — and it fails later,
+    // at invocation, with an error that never mentions the install. Treat both as
+    // needing repair.
+    const targetLive = fs.existsSync(e.path) && isUsableSkillDir(e.path); // existsSync follows the link
+
+    // A link pointing at a DIFFERENT but perfectly live pi-research install is left
+    // alone. Re-pointing it was a silent hijack: reconcile runs on every
+    // engine-touching CLI invocation, from whichever copy of the package is being
+    // invoked, so any second install captured the user's skill links just by being
+    // run once. docs/SDK.md tells users to `npm install @lincoln504/pi-research` INTO
+    // their project, so the second install is a documented, ordinary setup — and when
+    // that project was later moved or cleaned, the global skill died with an opaque
+    // "Cannot find module .../run.mjs". Self-healing only needs the dangling case
+    // (`!targetLive`), which is what an update that relocates the package produces;
+    // choosing between two live installs is what the explicit `skill install` is for.
+    if (!targetLive) {
       if (source !== null) {
         // Re-point to the current package source (handles update/reinstall).
         try {

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.

package/src/web-research/browser-search.ts

@@ -6,7 +6,7 @@
 
 import { runWorkerSearch } from '../infrastructure/browser/task-execution-service.ts';
 import { getMaxWorkers, COLD_START_ALLOWANCE_MS } from '../infrastructure/browser/config.ts';
-import { isTaskTimeoutError } from '../infrastructure/browser/browser-error-utils.ts';
+import { isTaskTimeoutError, isNativeBindingError } from '../infrastructure/browser/browser-error-utils.ts';
 import { logger } from '../logger.ts';
 import { safeUnref } from '../utils/safe-unref.ts';
 import { normalizeUrl } from '../utils/url-utils.ts';
@@ -321,6 +321,24 @@ export async function performSearch(
             reason = `${timeoutCount} queries timed out and ${errorCount} queries failed`;
         }
 
+        // A missing native addon is a BROKEN INSTALL, and the generic advice below
+        // actively misleads: it sends the reader to check their network and their
+        // machine load when neither is involved and neither can be acted on. npm 12
+        // defaults `allowScripts` to off, so a plain install no longer builds
+        // camoufox-js's better-sqlite3 dependency and every browser worker dies
+        // identically. Say that instead, and say what fixes it.
+        if (isNativeBindingError(sampleWorkerError)) {
+            metrics.increment('browser_search_total_failures_total', 1, { cause: 'native_binding' });
+            throw new Error(
+                `Search completely failed: ${reason}, all with a missing native module. ` +
+                `This is an incomplete install, not a network problem: the browser engine's ` +
+                `native dependencies were never built. npm 12 does not run dependency install ` +
+                `scripts by default — reinstall allowing them (npm install @lincoln504/pi-research ` +
+                `--allow-scripts, or npm approve-scripts --allow-scripts-pending), then retry.` +
+                (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : '')
+            );
+        }
+
         throw new Error(
             `Search completely failed: ${reason}. ` +
             `Browser workers may be unavailable, DuckDuckGo is unreachable, or the system is under extreme load.` +