@lincoln504/pi-research 1.0.6 → 1.0.9

package/dist/prompts/research-tool-usage.md

@@ -85,6 +85,7 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 
 **Multiple Topics:**
 - If you need to research multiple unrelated topics of **truly distinct scope**, you may emit multiple `research` calls **simultaneously in a single turn**. Each call gets its own isolated research run with its own coordinator and researchers.
+- **Maximum 4 simultaneous calls** — Do NOT make more than 4 `research` calls in a single turn, even if you have more unrelated topics. Exceeding 4 simultaneous research runs can overload the system and degrade performance. If you have more than 4 truly distinct topics, they can likely be consolidated into fewer calls (group related subtopics, use broader queries, or batch across multiple turns).
 - Example: `research("bananas")` and `research("quantum computing")` in the same turn — these have zero overlap.
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.

package/dist/thread-worker.mjs

@@ -2219,6 +2219,8 @@ var ConfigSchema = Type.Object({
   RESEARCHER_MAX_RETRIES: Type.Number({ minimum: 0, maximum: 5, default: 2 }),
   /** Base delay between retries in milliseconds (default: 2000, range: 100-10000) */
   RESEARCHER_MAX_RETRY_DELAY_MS: Type.Number({ minimum: 100, maximum: 1e4, default: 2e3 }),
+  /** Unique researcher failures that abort the entire run (default: 2, range: 1-10) */
+  MAX_FAILED_RESEARCHERS: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Target depth for recursive research (default: 1, range: 1-3) */
   DEFAULT_RESEARCH_DEPTH: Type.Number({ minimum: 1, maximum: 3, default: 1 }),
   /** Number of batches to allow for a single scrape tool call (default: 2, 0=unlimited) */
@@ -2276,9 +2278,13 @@ var ConfigSchema = Type.Object({
    *  never killed before it has used its full nav budget plus time waiting in the queue.
    *  (default: 10000) */
   BROWSER_TASK_TIMEOUT_MS: Type.Number({ minimum: 2e3, maximum: 12e4, default: 1e4 }),
-  /** Timeout for coordinator/evaluator/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-600s).
-   *  Not exposed in TUI — controlled via PI_RESEARCH_LLM_TIMEOUT_MS env var. */
-  LLM_TIMEOUT_MS: Type.Number({ minimum: 6e4, maximum: 6e5, default: 3e5 }),
+  /** Timeout for coordinator/evaluator/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-30min).
+   *  Not exposed in TUI — controlled via PI_RESEARCH_LLM_TIMEOUT_MS env var.
+   *  Ceiling raised to 30min (matching RESEARCHER_TIMEOUT_MS): a slow model on a
+   *  large-context synthesis/plan call can legitimately run >10min, and the old
+   *  600000 ceiling silently clamped an explicit PI_RESEARCH_LLM_TIMEOUT_MS
+   *  (e.g. 900000), causing those calls to time out mid-generation. */
+  LLM_TIMEOUT_MS: Type.Number({ minimum: 6e4, maximum: 18e5, default: 3e5 }),
   /** Chain-of-thought "thinking" level for the engine's own LLM calls (coordinator,
    *  evaluator, synthesis, JSON-repair, knowledge extraction) AND the researcher
    *  sub-agents. Default 'off': these calls emit structured JSON / cited reports, not

package/docs/ARCHITECTURE.md

@@ -84,10 +84,23 @@ Two conventions apply:
   report. A mid-round evaluation that cannot be parsed continues the existing agenda
   rather than finalizing early, so a parse failure never truncates a run.
 
-### Research tools
+### Tool inventory
 
-Each researcher has a fixed tool set and a shared budget of 12 gathering calls per phase
-(`MAX_GATHERING_CALLS`).
+This is the canonical list of every tool the system exposes, on both surfaces.
+
+**Host-facing tools** — registered with the pi session (`src/index.ts`) for the calling
+agent to invoke:
+
+| Tool | Purpose |
+|------|---------|
+| `research` | Run a full multi-source research session and return the cited Markdown report |
+| `research_knowledge_search` | Instant local search of the knowledge store — checked before live research; always registered, reports why when the store is disabled |
+| `health` | Verify system status (browser pool, knowledge store, GPU lock); optional liveness probe |
+
+**Researcher-agent tools** — the fixed set each researcher sub-agent works with
+(`src/tools/index.ts`). `search`, `security_search`, `stackexchange`, and
+`youtube_transcript` share a budget of 12 gathering calls per phase
+(`MAX_GATHERING_CALLS`); `scrape` and local `grep` have their own budgets:
 
 | Tool | Quick | Deep | Backend |
 |------|-------|------|---------|
@@ -102,7 +115,9 @@ Each researcher has a fixed tool set and a shared budget of 12 gathering calls p
 In deep research `search` is excluded — the coordinator runs the search burst and hands
 out URLs directly. In quick research `grep` is excluded — the single session is not
 expected to traverse a local codebase. Researchers cannot write files, run shell
-commands, or reach the network outside these tools.
+commands, or reach the network outside these tools. Individual researcher tools can be
+disabled per run with `PI_RESEARCH_DISABLED_TOOLS`
+(see [CONFIGURATION.md](CONFIGURATION.md)).
 
 ### Browser infrastructure
 

package/docs/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+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.0.9] - 2026-07-28
+
+### Fixed
+- **pi ≥ 0.81.0 researcher crash** — every researcher session died with `pendingNativeProviderRegistrations is not iterable` under pi 0.81.0+ ("no source material was collected"). The hand-maintained `ExtensionRuntime` mock in the resource loader was frozen at a pre-0.81 contract; it is replaced with pi's own `createExtensionRuntime()`, which always satisfies the running host's contract and cannot drift again.
+- **pi 0.80.8+ ModelRuntime migration** — `buildModelRegistry` migrated off the removed `AuthStorage`/`ModelRegistry.create()` APIs to `ModelRuntime.create()` + the synchronous `ModelRegistry` facade. The `@earendil-works/*` dependency floor and the in-host version self-check are both raised to 0.80.8 to match.
+- **Explicit-API-key auth now reaches researcher LLM calls** — researcher sessions are created with the `modelRuntime` backing our own registry (pi 0.80.8 removed the old `modelRegistry` session option). Without this, standalone `PI_RESEARCH_API_KEY` users with no `~/.pi/agent/auth.json` passed pre-flight and then failed auth on every researcher call.
+- **Explicit-API-key pre-flight hang** — seeding a runtime API key triggered a model-catalog refresh whose default options open live network connections with no timeout; in network-restricted environments the CLI pre-flight hung indefinitely. The refresh is now pinned offline (`allowNetwork: false`).
+- **No filesystem side effects on read-only commands** — the migrated runtime's default file-backed credential store created `~/.pi/agent/auth.json` at construction, so every CLI invocation (including `status`) silently created a pi config dir on machines without pi and hard-failed where `$HOME` is read-only. An in-memory credential store is used when no `auth.json` exists; env-var provider keys are unaffected.
+- **Search-timeout cascade under concurrent load** — the per-query hard cap in browser search started at enqueue with only the nav budget, so a query stuck in a saturated worker queue burned its whole budget waiting and aborted with zero work ("Query timed out … likely blocked or slow startup"). The cap now includes the queue-wait margin, matching the scheduler's own ceiling.
+- **`PI_RESEARCH_LLM_TIMEOUT_MS` ceiling raised 10 → 30 min** — an explicit higher value was silently clamped to 600000, timing out large-context synthesis calls mid-generation.
+- **CHANGELOG dates corrected** — release dates in this file wrongly said 2024; corrected to the actual git release dates (2026).
+
+### Security
+- **protobufjs override 7.6.4 → 7.6.5** — clears GHSA-j3f2-48v5-ccww (DoS) and its whole moderate advisory chain through `@google/genai`/pi-ai.
+- **adm-zip forced to 0.6.0 via override** — clears GHSA-xcpc-8h2w-3j85 (crafted-ZIP 4 GB allocation) in the camoufox-js subtree; extraction APIs camoufox uses verified compatible.
+- **Audit gate hardened with a reviewed exception list** — CI and the release publish gate now run `scripts/audit-gate.cjs`: any moderate+ advisory in the shipped tree fails the build unless explicitly allowlisted in `config/tooling/audit-exceptions.json` with an upstream-blocked justification, a clears-when condition, and a review date. Current exceptions: `brace-expansion` (frozen inside pi-coding-agent's npm-shrinkwrap; fix released upstream) and `sharp` (unused image pipeline of the embeddings-only transformers dependency).
+
+### Changed
+- **Dependencies**: pi ecosystem lockfile refreshed to 0.82.1 (matching the current pi host); `pdf-oxide-wasm` 0.3.77; `undici` ^8.9; devDependencies refreshed (eslint 10.8, typescript-eslint 8.65, vitest 4.1.10, dependency-cruiser 17.4.3). Deliberate pins unchanged (typebox 1.1.38, playwright-core 1.60.0, camoufox-js 0.10.x, lancedb 0.29, apache-arrow 21.1.0, transformers 4.2, impit 0.13).
+- **Docs**: `PI_RESEARCH_LLM_TIMEOUT_MS` range updated in CONFIGURATION.md.
+
+## [1.0.8] - 2026-07-17
+
+### Added
+- **CHANGELOG** — Added comprehensive CHANGELOG.md documenting all versions from 0.1.13 through 1.0.7
+- **System prompt constraint** — Added "Maximum 4 simultaneous calls" constraint to research-tool-usage prompt to prevent system overload
+
+### Changed
+- **Topic consolidation guidance** — Emphasized that topics can likely be consolidated to fit the 4-call maximum, with strategies for grouping related subtopics
+- **Package structure** — CHANGELOG.md now included in published package (docs/CHANGELOG.md)
+
+## [1.0.7] - 2026-07-14
+
+### Fixed
+- **Browser-pool leader-election race** - Fixed a critical bug where a single client's transient socket error could force-clear shared leader state, causing a live, healthy leader to self-destruct via the leadership-miss watchdog. The fix reserves the "unreachable, force clear" path for cases where liveness probes actually confirm the registered leader PID or port is gone.
+- **Researcher retry-exemption** - Fixed the "no initial search results or historical links" failure path that bypassed the retry loop entirely. This now routes through the same `RESEARCHER_MAX_RETRIES`/`RESEARCHER_MAX_RETRY_DELAY_MS` retry loop as other failures.
+- **Exit-code misclassification** - Fixed false-positive classification of "Research stopped" errors as config errors (exit 78) via substring matching on the boilerplate "API key" advice text. Error classification now properly distinguishes infrastructure failures from credential problems.
+- **Unsurfaced quality signals** - Added per-run error tracking and per-researcher grounding signals to the log output for better debugging of report quality variance.
+- **SIGINT/SIGTERM cancellation wiring** - Improved cancellation handling for graceful shutdown on interrupt signals.
+- **Multi-researcher citation-provenance folding** - Fixed citation provenance tracking when multiple researchers contribute to a report.
+- **Untitled YouTube video citation line** - Fixed citation formatting for YouTube videos without titles.
+
+### Security
+- Several hardening improvements from the adversarial-review audit:
+  - Migration abort safety gates
+  - Hollow-run detection gates
+  - Streaming caps for large responses
+  - Socket drain on Content-Length pre-screen throws
+  - Observer isolation improvements
+
+## [1.0.6] - 2026-07-04
+
+### Fixed
+- **Observer isolation** - Fixed `makeSafeObserver` proxying the observer directly, which could cause state leakage.
+
+### Documentation
+- Corrected depth-0 availability documentation
+- Fixed migration.ts attribution in architecture docs
+
+## [1.0.5] - 2026-07-04
+
+### Fixed
+- **Content-Length pre-screen throws** - Added proper body draining to prevent resource leaks
+- **TTL refresh for transcribed links** - Fixed TTL handling for YouTube transcripts
+
+### Fixed
+- **YouTube transcript provenance** - Fixed transcript provenance tracking in final report citations
+
+## [1.0.4] - 2026-07-04
+
+### Fixed
+- **Credential detection** - Detect pi keys by pi's own semantics, not file presence; registry no longer gated on auth.json
+- **Configuration clarity** - Updated docs to reflect that pi has configuration files, not a named 'auth' feature
+
+## [1.0.3] - 2026-07-04
+
+### Fixed
+- **Model resolution** - Require a configured model on the standalone CLI/skill; align SDK session model with RESEARCH_MODEL
+- **Configuration requirement** - Added proper error messages when model is not configured
+
+### Documentation
+- Updated installation and configuration documentation
+
+## [1.0.2] - 2026-07-04
+
+### Fixed
+- **Timeout robustness** - Improved timeout handling for long-running operations
+- De-emphasized the markdown-conversion fallback in favor of native HTML-to-markdown conversion
+
+## [1.0.1] - 2026-07-04
+
+### Fixed
+- Initial stable release after rebuild against current pi APIs
+- Stealth-browser stack integration
+
+## [0.1.13] - 2026-04-15
+
+### Added
+- Initial research functionality
+- Knowledge store integration
+- Multi-agent orchestration
+
+---
+
+## Deferred Findings (from v1.0.7 audit)
+
+The following issues were identified during the v1.0.7 audit but intentionally deferred to future releases:
+
+1. **KnowledgeStore.close() timeout behavior** - The close() method proceeds even when the pending-write wait times out. A correct fix requires threading cancellation tokens through write paths or documenting the 10s timeout as intended behavior.
+
+2. **Cross-session teardown via shared singletons** - Session shutdown handlers run process-wide cleanup for reload/new/fork events. The correct behavior depends on pi's session model semantics and needs further investigation.
+
+3. **Lower-severity hardening items** - Various low-confidence or low-impact findings noted for future investigation:
+   - SIGINT-adjacent cancellation race
+   - Knowledge-store migration vs. concurrent access
+   - Global activity gate reused for per-session decisions
+   - Zombie queued browser tasks after timeout
+   - Non-atomic `clearBrowserServer`
+   - Inconsistent `knowledge --json` payload shapes
+   - Backward-clock-step tolerance across multiple rate limiters
+
+See `DEFERRED-FINDINGS-2026-07-14.md` for full details.

package/docs/CONFIGURATION.md

@@ -73,6 +73,7 @@ Research
 | `PI_RESEARCH_MAX_CONCURRENT_SCRAPES` | `3` | 1–20 | Concurrent URLs fetched per scrape batch. |
 | `PI_RESEARCH_MAX_RETRIES` | `2` | 0–5 | Retries per researcher request. |
 | `PI_RESEARCH_RETRY_DELAY_MS` | `2000` | 100–10000 | Base delay between retries. |
+| `PI_RESEARCH_MAX_FAILED_RESEARCHERS` | `2` | 1–10 | Unique researcher failures that abort the whole run. Raise to let slower, still-in-flight researchers finish before giving up. |
 | `PI_RESEARCH_WORKER_THREADS` | `4` | 1–10 | Browser worker processes. Higher = more throughput, more CPU/RAM. |
 | `PI_RESEARCH_WORKER_CONCURRENCY` | `2` | 1–10 | Tasks per worker process. |
 | `PI_RESEARCH_MODEL` | _(pi: session model; CLI/skill: required)_ | — | The model research runs on. **Required for the standalone CLI / agent skill** — they use only this configured model (never the model selected inside the pi extension) and refuse to start without one (the CLI's per-run `--model` flag also satisfies this). On the SDK it selects the session model when no `model` option is given. In the pi extension it overrides researcher sub-agents and knowledge synthesis, while the coordinator and evaluator keep using the session model. Accepts `provider/id` or a bare model id. |
@@ -96,7 +97,7 @@ Timeouts
 
 | Variable | Default | Range | Description |
 |----------|---------|-------|-------------|
-| `PI_RESEARCH_LLM_TIMEOUT_MS` | `300000` | 60000–600000 | Coordinator / evaluator / repair / knowledge LLM call timeout. |
+| `PI_RESEARCH_LLM_TIMEOUT_MS` | `300000` | 60000–1800000 | Coordinator / evaluator / repair / knowledge LLM call timeout. |
 | `PI_RESEARCH_SCRAPE_TIMEOUT_MS` | `15000` | 5000–120000 | Per-page scrape (page-load) timeout. |
 | `PI_RESEARCH_SEARCH_TIMEOUT_MS` | `45000` | 5000–120000 | Browser search page timeout. |
 | `PI_RESEARCH_BROWSER_TASK_TIMEOUT_MS` | `10000` | 2000–120000 | Queue-wait / overhead margin added to each browser op's own timeout (a search task ceiling is `SEARCH_TIMEOUT_MS` + this; a scrape is `SCRAPE_TIMEOUT_MS` + this). |

package/docs/SDK.md

@@ -76,7 +76,10 @@ await shutdownResearchSDK();
 `runResearchDetailed`, `searchKnowledge`, `scrapeUrl`, `getResearchHealth`,
 `getLastRunStats`, and `getSessionMetrics`, plus `exportKnowledge` (write the
 knowledge store to a web-consumable JSON file) and the post-run telemetry accessors
-`getLastRunMetrics`, `getLastRunSummary`, and `getLastErrorReport`. Both
+`getLastRunMetrics`, `getLastRunSummary`, `getLastErrorReport`, and
+`getLastResearcherOutcome` (planned/launched/succeeded/failed researcher counts plus
+per-researcher failure reasons for the most recent run — lets a caller tell a thin
+report caused by a sparse topic apart from one where most researchers failed). Both
 `@lincoln504/pi-research` and `@lincoln504/pi-research/sdk` export these symbols.
 
 > Concurrency: a single initialized SDK instance runs one research call at a time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,
@@ -37,7 +37,8 @@
     "scripts/prepare.cjs",
     "LICENSE",
     "docs/THIRD-PARTY-NOTICES.md",
-    "README.md"
+    "README.md",
+    "docs/CHANGELOG.md"
   ],
   "repository": {
     "type": "git",
@@ -109,9 +110,9 @@
     "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": ">=0.80.2 <1",
-    "@earendil-works/pi-coding-agent": ">=0.80.2 <1",
-    "@earendil-works/pi-tui": ">=0.80.2 <1",
+    "@earendil-works/pi-ai": ">=0.80.8 <1",
+    "@earendil-works/pi-coding-agent": ">=0.80.8 <1",
+    "@earendil-works/pi-tui": ">=0.80.8 <1",
     "@huggingface/transformers": "4.2.0",
     "@kreuzberg/html-to-markdown-node": "^3.5.5",
     "@lancedb/lancedb": "0.29.0",
@@ -122,11 +123,11 @@
     "impit": "0.13.0",
     "jsdom": "^29.1.1",
     "node-html-markdown": "^2.0.0",
-    "pdf-oxide-wasm": "^0.3.70",
+    "pdf-oxide-wasm": "^0.3.75",
     "playwright-core": "1.60.0",
     "poolifier": "^5.3.2",
     "typebox": "1.1.38",
-    "undici": "^8.6.0",
+    "undici": "^8.9.0",
     "youtubei.js": "^17.2.0"
   },
   "optionalDependencies": {
@@ -139,20 +140,21 @@
     "onnxruntime-web": "1.24.3",
     "node-domexception": "npm:@nolyfill/domexception@^1.0.28",
     "ua-parser-js": "^1.0.41",
-    "protobufjs": "7.6.4",
-    "vite": "^8.0.16"
+    "protobufjs": "7.6.5",
+    "vite": "^8.0.16",
+    "adm-zip": "^0.6.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/jsdom": "^28.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.60.0",
-    "@typescript-eslint/parser": "^8.60.0",
-    "@vitest/coverage-v8": "^4.1.7",
-    "dependency-cruiser": "^17.4.2",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "dependency-cruiser": "^17.4.3",
     "depngn": "^0.6.0",
-    "eslint": "^10.4.0",
-    "npm-check-updates": "^22.2.1",
+    "eslint": "^10.8.0",
+    "npm-check-updates": "^22.2.9",
     "typescript": ">=6.0.3 <6.1.0",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.10"
   }
 }

package/skills/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.0.6", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.0.9", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/src/cli.ts

@@ -31,9 +31,12 @@ import {
   runDeepResearch,
   searchKnowledge,
   shutdownResearchSDK,
+  getLastErrorReport,
+  getLastResearcherOutcome,
   type KnowledgeSearchResult,
 } from './sdk.ts';
 import type { HeadlessObserverOptions } from './orchestration/headless-observer.ts';
+import { RESEARCH_STOPPED_ERROR_CODE } from './orchestration/session-state.ts';
 import { validateAndSanitizeQuery } from './utils/input-validation.ts';
 import { validateInitialLink, MAX_INITIAL_LINKS } from './utils/url-utils.ts';
 import { exportResearchReport, appendExportMessage } from './utils/research-export.ts';
@@ -237,9 +240,9 @@ function fileExists(p: string): boolean {
  * OPENAI_API_KEY. File presence alone is neither necessary (keys can live in
  * models.json / env with no auth.json) nor sufficient (auth.json can be `{}`).
  */
-function piKeysAvailable(piAuthPresent: boolean, provider?: string): boolean {
+async function piKeysAvailable(piAuthPresent: boolean, provider?: string): Promise<boolean> {
   try {
-    const available = safeGetAvailable(buildModelRegistry(undefined, undefined));
+    const available = safeGetAvailable(await buildModelRegistry(undefined, undefined));
     if (!provider) return available.length > 0;
     // Provider known (from the configured provider/model-id): keys must exist
     // for THAT provider — a key for some other provider would pass pre-flight
@@ -279,7 +282,7 @@ export interface CredentialDetection {
  * blocks a valid `--model` run). An explicit PI_RESEARCH_PROVIDER still wins:
  * it names the provider the configured key belongs to.
  */
-function detectCredentials(explicitModel?: string): CredentialDetection {
+async function detectCredentials(explicitModel?: string): Promise<CredentialDetection> {
   const paths = resolvedConfigPaths();
   const piAuthPresent = fileExists(paths.piAuth);
   const piModelsPresent = fileExists(paths.piModels);
@@ -296,7 +299,7 @@ function detectCredentials(explicitModel?: string): CredentialDetection {
     providerEnv ?? (model && model.includes('/') ? model.slice(0, model.indexOf('/')) : undefined);
   // Provider-aware when the configured model names one: a key for a DIFFERENT
   // provider must not greenlight this run.
-  const piKeysUsable = piKeysAvailable(piAuthPresent, provider);
+  const piKeysUsable = await piKeysAvailable(piAuthPresent, provider);
 
   // --- Explicit API-key path -------------------------------------------------
   if (apiKey) {
@@ -437,7 +440,7 @@ interface ResearchArgs {
 async function cmdResearch(args: ResearchArgs): Promise<number> {
   // Pre-flight with the per-run --model flag folded in: it satisfies the
   // model-required check and steers the provider-aware key detection.
-  const det = detectCredentials(args.model);
+  const det = await detectCredentials(args.model);
   if (det.problem) {
     if (args.json) toStdout(pretty({ ok: false, error: det.problem, exitCode: EXIT.CONFIG }));
     else toStderr(`\nError: ${det.problem}\n\n${configBlock(det)}\n`);
@@ -468,6 +471,11 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
   const observer: HeadlessObserverOptions = makeProgressObserver();
 
   let exit: number = EXIT.OK;
+  // Let Ctrl-C/SIGTERM (main()'s onSignal) cancel THIS run's orchestrator instead of
+  // only tearing down shared SDK services out from under it — see
+  // activeResearchAbortController's declaration for why.
+  const abortController = new AbortController();
+  activeResearchAbortController = abortController;
   try {
     await initResearchSDK({
       model: runModel,
@@ -485,7 +493,7 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
       observer,
       ...(args.excludeTools ? { excludeTools: args.excludeTools } : {}),
       ...(args.initialLinks ? { initialLinks: args.initialLinks } : {}),
-    });
+    }, abortController.signal);
 
     // Optionally persist the report to a file (opt-in via
     // PI_RESEARCH_REPORT_EXPORT_ENABLED). The SDK is a pure library and does not
@@ -503,13 +511,29 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
     }
 
     if (args.json) {
-      toStdout(pretty({ ok: true, depth, report, ...(reportPath ? { reportPath } : {}) }));
+      // Surface the internal quality/health signals that were previously log-only
+      // (ISSUES-ANALYSIS-2026-07-09.md, Symptom 4): a caller reading only stdout/JSON
+      // had no way to distinguish "thin report, little material out there" from "thin
+      // report because most researchers died mid-run" without opening the log file.
+      const outcome = getLastResearcherOutcome();
+      const errorReport = getLastErrorReport();
+      toStdout(pretty({
+        ok: true,
+        depth,
+        report,
+        ...(reportPath ? { reportPath } : {}),
+        ...(outcome ? { researchers: { planned: outcome.planned, launched: outcome.launched, succeeded: outcome.succeeded, failed: outcome.failed } } : {}),
+        ...(errorReport && errorReport.totalErrors > 0 ? {
+          trackedErrors: { total: errorReport.totalErrors, uniquePatterns: errorReport.uniquePatterns },
+        } : {}),
+      }));
     } else {
       toStdout(report.endsWith('\n') ? report : report + '\n');
     }
   } catch (err) {
-    exit = reportError(err, 'research', args.json);
+    exit = await reportError(err, 'research', args.json);
   } finally {
+    if (activeResearchAbortController === abortController) activeResearchAbortController = null;
     await safeShutdown();
   }
   return exit;
@@ -521,7 +545,7 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
  * research.
  */
 async function cmdKnowledge(queries: string[], json?: boolean): Promise<number> {
-  const det = detectCredentials();
+  const det = await detectCredentials();
   if (det.problem) {
     if (json) { toStdout(pretty({ ok: false, error: det.problem, exitCode: EXIT.CONFIG })); return EXIT.CONFIG; }
     toStderr(`\nError: ${det.problem}\n\n${configBlock(det)}\n`);
@@ -571,7 +595,7 @@ async function cmdKnowledge(queries: string[], json?: boolean): Promise<number>
  * run, without initializing the SDK. Machine-readable with --json.
  */
 async function cmdStatus(json?: boolean): Promise<number> {
-  const det = detectCredentials();
+  const det = await detectCredentials();
   const paths = resolvedConfigPaths();
   const cfg = getConfig(process.cwd(), 'cli');
   const summary = {
@@ -791,12 +815,23 @@ function describeUninstall(r: { status: string; path: string; message?: string }
 // ---------------------------------------------------------------------------
 
 /** Distinguish setup errors from runtime errors and print a clean, located message. */
-function reportError(err: unknown, what: string, json?: boolean): number {
+export async function reportError(err: unknown, what: string, json?: boolean): Promise<number> {
   const msg = err instanceof Error ? err.message : String(err);
   const lower = msg.toLowerCase();
 
+  // A tagged research-stop error (session-state.ts's createResearchStopError) is an
+  // orchestration/infrastructure failure (worker-pool contention, ungrounded
+  // researchers, etc.), never a credentials problem — classify it as SOFTWARE
+  // unconditionally and skip the substring heuristic below entirely. Without this,
+  // the boilerplate advice line every research-stop message carries ("Verify the
+  // model is available and the API key / context settings are valid.") contains the
+  // literal substring "api key," so the heuristic alone would misclassify EVERY
+  // research-stop — regardless of real cause — as a config error (exit 78).
+  const isTaggedResearchStop = (err as { code?: unknown } | undefined)?.code === RESEARCH_STOPPED_ERROR_CODE;
+
   // Auth / model / config-shaped errors → CONFIG exit + config block.
   const isConfigError =
+    !isTaggedResearchStop && (
     lower.includes('no llm model available') ||
     lower.includes('not found in pi') ||
     lower.includes('no api key') ||
@@ -804,7 +839,7 @@ function reportError(err: unknown, what: string, json?: boolean): number {
     lower.includes('invalid model string') ||
     lower.includes('authentication') ||
     lower.includes('unauthorized') ||
-    lower.includes('api key');
+    lower.includes('api key'));
 
   // Rate limits win over config-shaped matches: a provider 429 often mentions
   // "api key" in its body (e.g. "rate limit exceeded for this api key"), and
@@ -830,7 +865,7 @@ function reportError(err: unknown, what: string, json?: boolean): number {
     return exitCode;
   }
   if (isConfigError) {
-    toStderr(`\nError: pi-research ${what} failed: ${msg}\n\n${configBlock(detectCredentials())}\n`);
+    toStderr(`\nError: pi-research ${what} failed: ${msg}\n\n${configBlock(await detectCredentials())}\n`);
     return exitCode;
   }
   toStderr(`\nError: pi-research ${what} failed: ${msg}\n`);
@@ -1175,6 +1210,15 @@ const flushAndExit = (code: number): void => {
   });
 };
 
+// Signal to the in-flight `research` run's AbortController, if any is active.
+// Without this, Ctrl-C only tore down shared SDK services (browser pool, LLM
+// clients, LanceDB) via safeShutdown() while runDeepResearch() was still using
+// them — the orchestrator never saw a cancellation and had no chance to return
+// its already-wired partial/fallback synthesis for a clean stop. Set at the
+// start of cmdResearch, cleared in its finally so a stale reference never
+// outlives that one run.
+let activeResearchAbortController: AbortController | null = null;
+
 async function main(argv: string[]): Promise<number> {
   // Register signal handlers so SIGINT/SIGTERM always trigger SDK shutdown
   // before the process exits. safeShutdown() is idempotent — safe to call
@@ -1184,6 +1228,11 @@ async function main(argv: string[]): Promise<number> {
     if (_signalCleanupDone) return;
     _signalCleanupDone = true;
     toStderr(`\n[pi-research] ${sig} — cleaning up…\n`);
+    // Abort the in-flight research run FIRST (synchronously ahead of the shutdown
+    // teardown below) so the orchestrator's existing signal-aware cancellation path
+    // gets a chance to return a partial/fallback synthesis instead of racing a live
+    // browser-pool/LLM teardown out from under it.
+    activeResearchAbortController?.abort();
     // Fire-and-forget: we can't await here, but safeShutdown swallows errors
     // and the finally blocks in each command handler also call it. Drain via
     // flushAndExit (not a bare process.exit) so buffered stdout isn't truncated.

package/src/config.ts

@@ -28,6 +28,8 @@ export const ConfigSchema = Type.Object({
   RESEARCHER_MAX_RETRIES: Type.Number({ minimum: 0, maximum: 5, default: 2 }),
   /** Base delay between retries in milliseconds (default: 2000, range: 100-10000) */
   RESEARCHER_MAX_RETRY_DELAY_MS: Type.Number({ minimum: 100, maximum: 10000, default: 2000 }),
+  /** Unique researcher failures that abort the entire run (default: 2, range: 1-10) */
+  MAX_FAILED_RESEARCHERS: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Target depth for recursive research (default: 1, range: 1-3) */
   DEFAULT_RESEARCH_DEPTH: Type.Number({ minimum: 1, maximum: 3, default: 1 }),
   /** Number of batches to allow for a single scrape tool call (default: 2, 0=unlimited) */
@@ -85,9 +87,13 @@ export const ConfigSchema = Type.Object({
    *  never killed before it has used its full nav budget plus time waiting in the queue.
    *  (default: 10000) */
   BROWSER_TASK_TIMEOUT_MS: Type.Number({ minimum: 2000, maximum: 120000, default: 10000 }),
-  /** Timeout for coordinator/evaluator/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-600s).
-   *  Not exposed in TUI — controlled via PI_RESEARCH_LLM_TIMEOUT_MS env var. */
-  LLM_TIMEOUT_MS: Type.Number({ minimum: 60000, maximum: 600000, default: 300000 }),
+  /** Timeout for coordinator/evaluator/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-30min).
+   *  Not exposed in TUI — controlled via PI_RESEARCH_LLM_TIMEOUT_MS env var.
+   *  Ceiling raised to 30min (matching RESEARCHER_TIMEOUT_MS): a slow model on a
+   *  large-context synthesis/plan call can legitimately run >10min, and the old
+   *  600000 ceiling silently clamped an explicit PI_RESEARCH_LLM_TIMEOUT_MS
+   *  (e.g. 900000), causing those calls to time out mid-generation. */
+  LLM_TIMEOUT_MS: Type.Number({ minimum: 60000, maximum: 1800000, default: 300000 }),
   /** Chain-of-thought "thinking" level for the engine's own LLM calls (coordinator,
    *  evaluator, synthesis, JSON-repair, knowledge extraction) AND the researcher
    *  sub-agents. Default 'off': these calls emit structured JSON / cited reports, not
@@ -690,6 +696,7 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     PI_RESEARCH_MAX_RESEARCHERS: String(config.MAX_CONCURRENT_RESEARCHERS),
     PI_RESEARCH_MAX_RETRIES: String(config.RESEARCHER_MAX_RETRIES),
     PI_RESEARCH_RETRY_DELAY_MS: String(config.RESEARCHER_MAX_RETRY_DELAY_MS),
+    PI_RESEARCH_MAX_FAILED_RESEARCHERS: String(config.MAX_FAILED_RESEARCHERS ?? DEFAULTS.MAX_FAILED_RESEARCHERS),
     PI_RESEARCH_HEALTH_CHECK_TIMEOUT_MS: String(config.HEALTH_CHECK_TIMEOUT_MS ?? DEFAULTS.HEALTH_CHECK_TIMEOUT_MS),
     PI_RESEARCH_SEARCH_TIMEOUT_MS: String(config.SEARCH_TIMEOUT_MS),
     PI_RESEARCH_TUI_REFRESH_DEBOUNCE_MS: String(config.TUI_REFRESH_DEBOUNCE_MS),
@@ -912,6 +919,7 @@ export function createConfig(env: Record<string, string | undefined>, processEnv
     MAX_CONCURRENT_RESEARCHERS: parseEnvNumber(e, 'PI_RESEARCH_MAX_RESEARCHERS', DEFAULTS.MAX_CONCURRENT_RESEARCHERS, 1, 5, true),
     RESEARCHER_MAX_RETRIES: parseEnvNumber(e, 'PI_RESEARCH_MAX_RETRIES', DEFAULTS.RESEARCHER_MAX_RETRIES, 0, 5, true),
     RESEARCHER_MAX_RETRY_DELAY_MS: parseEnvNumber(e, 'PI_RESEARCH_RETRY_DELAY_MS', DEFAULTS.RESEARCHER_MAX_RETRY_DELAY_MS, 100, 10000),
+    MAX_FAILED_RESEARCHERS: parseEnvNumber(e, 'PI_RESEARCH_MAX_FAILED_RESEARCHERS', DEFAULTS.MAX_FAILED_RESEARCHERS, 1, 10, true),
     DEFAULT_RESEARCH_DEPTH: parseEnvNumber(e, 'PI_RESEARCH_DEFAULT_RESEARCH_DEPTH', DEFAULTS.DEFAULT_RESEARCH_DEPTH, 1, 3, true),
     MAX_SCRAPE_BATCHES: parseEnvNumber(e, 'PI_RESEARCH_MAX_SCRAPE_BATCHES', DEFAULTS.MAX_SCRAPE_BATCHES, 0, 99, true),
     MAX_GATHERING_CALLS: parseEnvNumber(e, 'PI_RESEARCH_MAX_GATHERING_CALLS', DEFAULTS.MAX_GATHERING_CALLS, 1, 100, true),
@@ -941,7 +949,7 @@ export function createConfig(env: Record<string, string | undefined>, processEnv
     SEARCH_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_SEARCH_TIMEOUT_MS', DEFAULTS.SEARCH_TIMEOUT_MS, 5000, 120000),
     TUI_REFRESH_DEBOUNCE_MS: parseEnvNumber(e, 'PI_RESEARCH_TUI_REFRESH_DEBOUNCE_MS', DEFAULTS.TUI_REFRESH_DEBOUNCE_MS, 0, 1000),
     BROWSER_TASK_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_BROWSER_TASK_TIMEOUT_MS', DEFAULTS.BROWSER_TASK_TIMEOUT_MS, 2000, 120000),
-    LLM_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_LLM_TIMEOUT_MS', DEFAULTS.LLM_TIMEOUT_MS, 60000, 600000),
+    LLM_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_LLM_TIMEOUT_MS', DEFAULTS.LLM_TIMEOUT_MS, 60000, 1800000),
     LLM_THINKING_LEVEL: parseEnvEnum(e, 'PI_RESEARCH_LLM_THINKING_LEVEL', ['off', 'minimal', 'low', 'medium', 'high'] as const, DEFAULTS.LLM_THINKING_LEVEL),
     PLANNING_MAX_TOKENS: parseEnvNumber(e, 'PI_RESEARCH_PLANNING_MAX_TOKENS', DEFAULTS.PLANNING_MAX_TOKENS, 1024, 131072),
     SYNTHESIS_MAX_TOKENS: parseEnvNumber(e, 'PI_RESEARCH_SYNTHESIS_MAX_TOKENS', DEFAULTS.SYNTHESIS_MAX_TOKENS, 1024, 131072),