@lincoln504/pi-research 1.4.1 → 1.5.0

package/package.json

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

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

package/src/cli.ts

@@ -150,7 +150,7 @@ function pretty(obj: unknown): string {
  * lifecycle event to stderr. Keeps a long research run visible without spamming
  * stdout (the report goes to stdout, untouched).
  */
-function makeProgressObserver(): HeadlessObserverOptions {
+export function makeProgressObserver(): HeadlessObserverOptions {
   return {
     enableLogging: false,
     onProgress: (event: string, data?: any) => {
@@ -196,9 +196,24 @@ function makeProgressObserver(): HeadlessObserverOptions {
           }
           break;
         }
-        case 'complete':
+        case 'complete': {
           toStderr(`  • complete (${data?.result?.length ?? 0} chars)\n`);
+          // Degradation signal for callers that read stderr (the agent skill
+          // does): a run that completes but is weakly grounded or retrieved no
+          // sources at all looks identical to a healthy run on exit code and
+          // the "complete" line alone. Two real runs on 2026-08-20 shipped
+          // degraded reports (1 citation / 0 sources) with nothing on stderr to
+          // distinguish them. The markers are the synthesis service's own
+          // notices, appended by ensureCitedLinks.
+          const reportText = typeof data?.result === 'string' ? data.result : '';
+          if (reportText.includes('No web sources were successfully retrieved') ||
+              reportText.includes('None of the links above could be verified')) {
+            toStderr('  • WARNING: no web sources could be retrieved — the report is unverified\n');
+          } else if (reportText.includes('Grounding notice: only')) {
+            toStderr('  • WARNING: weakly grounded report (fewer than 3 verified sources) — treat unattributed claims as unverified\n');
+          }
           break;
+        }
         case 'error':
           toStderr(`  • error: ${data?.message}\n`);
           break;
@@ -738,7 +753,9 @@ export async function cmdKnowledge(queries: string[], json?: boolean): Promise<n
       config: getConfig(process.cwd(), 'cli'),
       ignoreGlobalConfig: true,
     });
-    toStderr(`[pi-research] searching knowledge store (${queries.length} query/${queries.length === 1 ? '' : 's'})…\n`);
+    // "N queries", not "N query/s" — same rationale as the search_start line above:
+    // the slash form reads as a rate and renders "1 query/" in the singular.
+    toStderr(`[pi-research] searching knowledge store (${queries.length} ${queries.length === 1 ? 'query' : 'queries'})…\n`);
     result = await searchKnowledge(queries, abortController.signal);
   } catch (err) {
     return reportError(err, 'knowledge search', json);
@@ -1660,10 +1677,34 @@ async function main(argv: string[]): Promise<number> {
   // left the SDK's handler to tear the container down underneath a live orchestrator
   // — exactly the race the CLI installs its own handlers to avoid.
   process.on('SIGHUP', () => onSignal('SIGHUP'));
+  // SIGQUIT: documented (see exitCodeForSignal's comment and the exit-code
+  // tables in docs/SDK.md and SKILL.md) as handled the same way as SIGHUP,
+  // but no listener was ever registered for it — an unhandled SIGQUIT hits
+  // Node's default disposition (immediate termination, no abort, no drain),
+  // silently breaking that documented guarantee. Has no Windows equivalent;
+  // registering the listener there is a documented no-op, so no guard needed.
+  process.on('SIGQUIT', () => onSignal('SIGQUIT'));
   if (process.platform === 'win32') {
     process.on('SIGBREAK', () => onSignal('SIGBREAK'));
   }
 
+  // Test-only seam: idle here, right after every handler above is registered,
+  // instead of parsing argv/running a command. Lets a subprocess test deliver
+  // a real OS signal and observe THIS handler run (process.exit with the
+  // derived code) rather than Node's default disposition (process killed by
+  // the signal, no code) — the exact distinction that would have caught the
+  // missing SIGQUIT registration this seam was added for. Never set in
+  // production; see the SIGQUIT subprocess test in test/unit/cli.test.ts.
+  if (process.env['PI_RESEARCH_TEST_HANG_FOR_SIGNAL'] === '1') {
+    process.stdout.write('PI_RESEARCH_TEST_READY\n');
+    // A bare unresolved Promise does not keep the event loop alive by
+    // itself (only real libuv handles do — an installed signal listener
+    // isn't one either), so without a ref'd timer the process would exit 0
+    // on its own the instant this synchronous section finishes, before any
+    // signal could ever arrive.
+    await new Promise<never>(() => setInterval(() => {}, 1000));
+  }
+
   let parsed: ParsedArgs;
   try {
     parsed = parseArgs(argv);

package/src/config.ts

@@ -82,10 +82,16 @@ export const ConfigSchema = Type.Object({
   SEARCH_TIMEOUT_MS: Type.Number({ minimum: 5000, maximum: 120000, default: 45000 }),
   /** TUI refresh debounce in milliseconds (default: 100ms) */
   TUI_REFRESH_DEBOUNCE_MS: Type.Number({ minimum: 0, maximum: 1000, default: 100 }),
-  /** Queue-wait / overhead margin (ms) added on top of each browser operation's own nav
-   *  timeout to form its scheduler task-timeout ceiling: a search task times out after
-   *  SEARCH_TIMEOUT_MS + this, a scrape after SCRAPE_TIMEOUT_MS + this. Sized so a task is
-   *  never killed before it has used its full nav budget plus time waiting in the queue.
+  /** Overhead margin (ms) added on top of each browser operation's own nav timeout to
+   *  form its scheduler task-timeout ceiling: a search task times out after
+   *  SEARCH_TIMEOUT_MS + this, a scrape after SCRAPE_TIMEOUT_MS + this — covering
+   *  per-task work beyond raw navigation (page setup, result parsing). Queue wait is
+   *  NOT part of this margin: the deadline is armed on dispatch, not on enqueue, so
+   *  time spent waiting for a free worker never counts against it (see
+   *  browser-task-scheduler.ts). Cold browser-launch/context-creation time is also
+   *  separate from this margin — COLD_START_ALLOWANCE_MS
+   *  (infrastructure/browser/config.ts) covers that unconditionally on top of it,
+   *  since it isn't something a user should need to tune.
    *  (default: 10000) */
   BROWSER_TASK_TIMEOUT_MS: Type.Number({ minimum: 2000, maximum: 120000, default: 10000 }),
   /** Timeout for coordinator/research-lead/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-30min).
@@ -745,16 +751,23 @@ function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, stri
     try {
       logger.warn(`[config] WARNING: .pi-research.env files are deprecated. Settings will be auto-migrated to the centralized registry. Remove ${legacyPath} after migration.`);
       legacyEnv = parseDotEnv(fs.readFileSync(legacyPath, 'utf-8'));
-      Object.assign(merged, legacyEnv);
-      
-      // Auto-migrate legacy settings to the central registry — but only LOCAL_SCOPE_KEYS. The
-      // registry is project-scoped storage by design (saveConfig writes only these keys to it);
-      // persisting user-scoped legacy keys would freeze them per-workspace and silently override
-      // the user's global config.env forever. Non-local legacy keys still apply to THIS resolution
-      // via the Object.assign(merged, legacyEnv) above — they just aren't persisted.
+      // Only LOCAL_SCOPE_KEYS from this run's resolution too — same boundary
+      // step 4 below already enforces for the registry this file migrates
+      // into ("the registry is project-scoped storage... never user-scoped
+      // keys"). This file lives in the CWD, which for this tool is routinely
+      // an arbitrary, potentially untrusted repository a coding agent was
+      // just pointed at — applying every key unconditionally let a dropped-in
+      // .pi-research.env silently control user-scoped settings (RESEARCH_MODEL,
+      // EMBEDDING_DEVICE, DISABLED_TOOLS, export destinations, ...) for that
+      // run with no confirmation, for any setting the user hadn't already set
+      // via a real environment variable (which still wins over all of this).
+      // Non-local keys are ignored here exactly as they already are for the
+      // registry — this predecessor mechanism should not be MORE permissive
+      // than the successor it's migrating into.
       const legacyLocal = Object.fromEntries(
         Object.entries(legacyEnv).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
+      Object.assign(merged, legacyLocal);
       const existingLocal = Object.fromEntries(
         Object.entries(findRegistryEntry(registry, normalizedCwd) ?? {}).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
@@ -793,8 +806,14 @@ function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, stri
       }
     }
   } else if (Object.keys(merged).length === 0 && !fs.existsSync(legacyPath) && !fs.existsSync(globalPath)) {
-    // 5. Warning for missing config
-    logger.warn(`[config] No configuration found for workspace: ${cwd}. Using code defaults. Run /research-config to configure.`);
+    // 5. Warning for missing config — once per workspace per process. getConfig
+    // is called on many hot paths (every tool invocation, health checks), and
+    // repeating this advisory each time made it the single most common line in
+    // the shared log (362 entries in one observed day), burying real warnings.
+    if (!warnedMissingConfigWorkspaces.has(normalizedCwd)) {
+      warnedMissingConfigWorkspaces.add(normalizedCwd);
+      logger.warn(`[config] No configuration found for workspace: ${cwd}. Using code defaults. Run /research-config to configure.`);
+    }
   }
 
   warnLegacyEnvVarsOnce(merged);
@@ -819,6 +838,10 @@ const LEGACY_ENV_VARS: Record<string, string> = {
 
 let warnedLegacyEnvVars = false;
 
+// Workspaces already warned about having no configuration (see loadEnvFiles) —
+// per-process dedup so the advisory appears once, not on every getConfig call.
+const warnedMissingConfigWorkspaces = new Set<string>();
+
 /** Warn once per process about set-but-dead 0.1.x env vars (upgrade aid; never throws). */
 function warnLegacyEnvVarsOnce(merged: Record<string, string>): void {
   if (warnedLegacyEnvVars) return;

package/src/constants.ts

@@ -46,11 +46,26 @@ export function getMaxGatheringCalls(config?: Config): number {
 /**
  * Get the maximum scrape batches from config.
  * This function should be used instead of MAX_SCRAPE_CALLS to support dynamic configuration.
+ *
+ * @param cachingActive - Pass `true` when prompt caching is active for this
+ * run's resolved model (see isPromptCachingActiveForModel in
+ * core/llm/research-model-resolver.ts). With caching active, the EFFECTIVE
+ * maximum is the configured value plus one: a cached run's system-prompt/
+ * tool-definition prefix is cheap to re-send, so the same token budget
+ * covers one more scrape batch per researcher. Every consumer of the batch
+ * count (tracker enforcement, prompt text, progress units) must go through
+ * this function with the same cachingActive value so they all agree on the
+ * effective number. The "unlimited" sentinel (0 or >99) is unchanged —
+ * adding one to unlimited is meaningless.
  */
-export function getMaxScrapeBatches(config?: Config): number {
+export function getMaxScrapeBatches(config?: Config, cachingActive = false): number {
   try {
     const batches = (config || getConfig()).MAX_SCRAPE_BATCHES;
-    return batches === 0 || batches > 99 ? 999999 : batches;
+    if (batches === 0 || batches > 99) return 999999;
+    // Cap at 99: a configured 99 (the documented max) plus one would land in the
+    // >99 "unlimited" band that every renderer checks — the prompt would say
+    // "unlimited batches" while enforcement actually blocked at 100.
+    return cachingActive ? Math.min(batches + 1, 99) : batches;
   } catch {
     return 2; // Fallback to default
   }
@@ -63,9 +78,13 @@ export const MAX_SCRAPE_URLS = 6;
  * Get the units per researcher for the progress bar.
  * Units = 1 (for start/search) + number of scrape batches.
  * When batches are unlimited (MAX_SCRAPE_BATCHES=0), caps at 4 for a sane progress estimate.
+ *
+ * Relative to the EFFECTIVE batch count: pass the run's cachingActive (from
+ * isPromptCachingActiveForModel over the resolved model) so progress units
+ * agree with the limit the tracker actually enforces.
  */
-export function getUnitsPerResearcher(config?: Config): number {
-  const batches = getMaxScrapeBatches(config);
+export function getUnitsPerResearcher(config?: Config, cachingActive = false): number {
+  const batches = getMaxScrapeBatches(config, cachingActive);
   return 1 + Math.min(batches, 4);
 }
 

package/src/core/llm/research-model-resolver.ts

@@ -89,3 +89,41 @@ export function resolveResearchModel(options: {
 
   throw new Error(buildNoModelAvailableMessage());
 }
+
+/**
+ * Best-effort, CONSERVATIVE signal for "will pi-ai apply prompt caching for
+ * this resolved model." pi-ai owns all cache-mechanism logic internally (this
+ * codebase never constructs cache_control blocks itself) and exposes no
+ * public API to ask in advance for most providers, so this can only answer
+ * for the two client-visible cases:
+ *
+ * - `api === 'anthropic-messages'`: caching is native and on by default (no
+ *   capability gate at all — see pi-ai's anthropic-messages provider).
+ * - `api === 'openai-completions'` with `compat.cacheControlFormat ===
+ *   'anthropic'`: an explicit opt-in to Anthropic-style cache_control
+ *   emulation (e.g. an OpenRouter/gateway route to an Anthropic model
+ *   configured with this override).
+ *
+ * Every other case returns false even though caching may actually be
+ * active: pi's generated model catalog sets `cacheControlFormat` on zero
+ * models, so plain `openai-completions` traffic (this project's custom
+ * providers — glm-coding, cerebras, zai, OpenRouter, ...) has its cache
+ * compat auto-detected by pi-ai's own private, unexported heuristic INSIDE
+ * the live request — not knowable client-side, before or after model
+ * resolution. Providers with fully implicit/automatic caching
+ * (openai-responses family, google-generative-ai, google-vertex,
+ * mistral-conversations, bedrock-converse-stream) have no "will it be
+ * active" signal at all — it depends on provider-side runtime behavior
+ * (minimum prompt length, server cache state). Treat this as "caching is
+ * DEFINITELY active" — a false negative is expected and fine for providers
+ * outside these two cases, but a false positive would be a real bug.
+ */
+export function isPromptCachingActiveForModel(model: Model<any> | undefined): boolean {
+  if (!model) return false;
+  if (model.api === 'anthropic-messages') return true;
+  if (model.api === 'openai-completions') {
+    const compat = model.compat as { cacheControlFormat?: string } | undefined;
+    return compat?.cacheControlFormat === 'anthropic';
+  }
+  return false;
+}

package/src/core/planning-service.ts

@@ -220,8 +220,19 @@ function isDegradableLlmError(error: unknown, signal?: AbortSignal): boolean {
 export function salvageReportText(raw: string): string {
   const trimmed = raw.trim();
   if (trimmed.length <= 50) return '';
+  // Envelope sniff. Models routinely wrap the JSON envelope in a markdown code
+  // fence (```json … ```); a fenced envelope starts with backticks, not '{', so a
+  // bare startsWith('{') check shipped one verbatim as a user-facing report
+  // (observed in production 2026-08-20: a ```json-fenced {"action":"synthesize",…}
+  // blob, internal protocol fields included, published as the final report).
+  // Strip one leading fence line and a trailing fence before the shape check.
+  let sniff = trimmed;
+  const fence = sniff.match(/^```[a-zA-Z0-9_-]*[ \t]*\r?\n/);
+  if (fence) {
+    sniff = sniff.slice(fence[0].length).replace(/\r?\n```\s*$/, '').trim();
+  }
   // Looks like a (broken) JSON envelope rather than a report — suppress it.
-  if (trimmed.startsWith('{') && /"(?:action|content|researchers)"\s*:/.test(trimmed)) {
+  if (sniff.startsWith('{') && /"(?:action|content|researchers)"\s*:/.test(sniff)) {
     return '';
   }
   return raw;
@@ -717,14 +728,38 @@ export class PlanningService implements IPlanningService {
       };
 
       const responseText = isRouter
-        ? await this.callLead({
-            ...callOptions,
-            systemPrompt: populate(''),
-            userMessage: buildRouterMessage(...this.buildRouterEvidence(options, round), runContext),
-            maxTokens: ROUTER_MAX_TOKENS,
-            component: 'router',
-            label: 'router-updatePlanForRound',
-          })
+        ? await (() => {
+            const routerMessage = buildRouterMessage(...this.buildRouterEvidence(options, round), runContext);
+            // The router carries no reduce mechanism the way synthesizeCorpus does — a
+            // routing decision made from PARTITIONED evidence isn't naturally mergeable
+            // the way synthesis prose is, and this call's output is a structured JSON
+            // delegate plan, not free text. Its input is bounded by team size in the
+            // common case (digests for earlier rounds are already capped — see
+            // MAX_DIGEST_CHARS), but nothing caps an individual researcher's fresh report
+            // body, so a round with a few unusually long reports can still overflow the
+            // window with no reduce path to fall back on. Warn rather than fail silently;
+            // the provider's own rejection is still the actual backstop, same as the
+            // synthesizer's over-budget-after-every-pass case above.
+            const window = model.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
+            const estimatedTokens = routerMessage.length / CHARS_PER_TOKEN + ROUTER_MAX_TOKENS + SYNTHESIS_OVERHEAD_TOKENS;
+            if (estimatedTokens > window) {
+              logger.warn(
+                `[PlanningService] Router request for ${model.id} is an estimated ` +
+                `${Math.round(estimatedTokens)} tokens against a ${window}-token context window ` +
+                `(evidence ${routerMessage.length} chars, output ceiling ${ROUTER_MAX_TOKENS} tokens). ` +
+                `Unlike the synthesizer, the router has no reduce path for an over-budget round — ` +
+                `sending it anyway, the provider may reject this request.`,
+              );
+            }
+            return this.callLead({
+              ...callOptions,
+              systemPrompt: populate(''),
+              userMessage: routerMessage,
+              maxTokens: ROUTER_MAX_TOKENS,
+              component: 'router',
+              label: 'router-updatePlanForRound',
+            });
+          })()
         : await this.synthesizeCorpus({ ...callOptions, reports, runContext, populate });
 
       // Extract and validate JSON
@@ -1115,6 +1150,29 @@ export class PlanningService implements IPlanningService {
       );
     }
 
+    // budgetChars alone can UNDER-report overflow risk once it hits MIN_SYNTHESIS_CORPUS_CHARS:
+    // below that point it is a fixed floor, not a value derived from the window, so a reduced
+    // corpus that fits comfortably under the floor can still combine with a large global source
+    // list and/or run context (neither bounded, both already subtracted from budgetChars but not
+    // from THIS check) to overflow the real window — the same failure class the budget exists to
+    // prevent, just triggered by those two inputs growing instead of the corpus. Check the actual
+    // total request against the actual window directly, independent of any floor.
+    const window = args.model.contextWindow ?? DEFAULT_MODEL_CONTEXT_WINDOW;
+    const estimatedTotalTokens =
+      (finalSize + globalSourceList.length + runContext.length) / CHARS_PER_TOKEN +
+      config.SYNTHESIS_MAX_TOKENS + SYNTHESIS_OVERHEAD_TOKENS;
+    if (estimatedTotalTokens > window) {
+      logger.warn(
+        `[PlanningService] Synthesis request for ${args.model.id} is an estimated ` +
+        `${Math.round(estimatedTotalTokens)} tokens against a ${window}-token context window ` +
+        `(corpus ${finalSize} chars, source list ${globalSourceList.length} chars, run context ` +
+        `${runContext.length} chars, output ceiling ${config.SYNTHESIS_MAX_TOKENS} tokens) — the ` +
+        `source list and/or run context are large enough on their own to overflow the window even ` +
+        `though the reduced corpus fits its budget. Sending it anyway — the provider may reject ` +
+        `this request.`,
+      );
+    }
+
     return this.callLead({
       ...args,
       systemPrompt: populate(reduced ? MERGE_SYNTHESIS_SECTION : ''),

package/src/index.ts

@@ -556,7 +556,9 @@ export default async function (pi: ExtensionAPI) {
 
     // Researcher sub-agent sessions already carry the authoritative steering copy:
     // the executor (deep) and quick orchestrator inject "ADDITIONAL USER GUIDANCE"/
-    // "ADDITIONAL CONSIDERATIONS" into the researcher system prompt themselves.
+    // "ADDITIONAL CONSIDERATIONS" into the researcher's initial user message themselves
+    // (kept OUT of the system prompt so its cacheable prefix stays byte-identical
+    // across researchers — see researcher-executor.ts).
     // Appending the same messages again here delivered every steering message
     // TWICE to every researcher — return the prompt untouched. (The coordinator and
     // the research lead never pass through this hook at all: they run via

package/src/infrastructure/browser/browser-task-scheduler.ts

@@ -23,7 +23,7 @@ import type { IScheduler, TaskDispatchListener } from '../../core/interfaces/sch
 import { cleanupOrphanedCamoufoxProcesses, getBrowserPidsForWorkers, killBrowserProcesses } from './browser-cleanup.ts';
 import { raceWithDeadline } from '../../utils/safe-unref.ts';
 import { PriorityTaskQueue } from './priority-task-queue.ts';
-import { getHealthCheckBudgetMs } from './config.ts';
+import { getHealthCheckBudgetMs, COLD_START_ALLOWANCE_MS } from './config.ts';
 
 /**
  * Grace added to the worker's own task budget before the dead-worker backstop
@@ -273,12 +273,17 @@ export class BrowserTaskScheduler implements IScheduler {
         const pool = await (await this.getWorkerPoolManager()).ensurePool(config);
         const startTime = Date.now();
 
-        // Task timeout = the search nav budget (SEARCH_TIMEOUT_MS) + a queue-wait/overhead
-        // margin (BROWSER_TASK_TIMEOUT_MS). Deriving from SEARCH_TIMEOUT_MS keeps the task
-        // ceiling coherent with the worker's own nav timeout — using a flat base here would
-        // kill a search before it had used its full nav budget.
+        // Task timeout = the search nav budget (SEARCH_TIMEOUT_MS) + an overhead margin
+        // (BROWSER_TASK_TIMEOUT_MS) + a cold-start allowance (COLD_START_ALLOWANCE_MS).
+        // Deriving from SEARCH_TIMEOUT_MS keeps the task ceiling coherent with the
+        // worker's own nav timeout — using a flat base here would kill a search before
+        // it had used its full nav budget. The cold-start term matters because eager
+        // browser warmup is deliberately disabled: the first search dispatched to a
+        // freshly created or just-reset worker pays a real Camoufox launch + context
+        // creation inline, before any navigation even starts — without this term that
+        // legitimate cold start reads as a dead/wedged worker (see COLD_START_ALLOWANCE_MS).
         const cfg = config || getConfig();
-        const timeoutMs = cfg.SEARCH_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS;
+        const timeoutMs = cfg.SEARCH_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS + COLD_START_ALLOWANCE_MS;
 
         // The deadline measures EXECUTION, not queue wait: the timer is armed by
         // `startDeadline()` from inside the enqueued callback, i.e. once the queue has
@@ -413,11 +418,13 @@ export class BrowserTaskScheduler implements IScheduler {
         this.resetIdleTimer();
         const pool = await (await this.getWorkerPoolManager()).ensurePool(config);
         const startTime = Date.now();
-        // Task timeout = the scrape nav budget (SCRAPE_TIMEOUT_MS) + the queue-wait/overhead
-        // margin (BROWSER_TASK_TIMEOUT_MS), mirroring the search path so both stay coherent.
+        // Task timeout = the scrape nav budget (SCRAPE_TIMEOUT_MS) + an overhead margin,
+        // mirroring the search path so both stay coherent. The mocked branch skips the
+        // cold-start allowance deliberately: PI_RESEARCH_MOCK_SCRAPE implies no real
+        // Camoufox launch is expected for scrape tasks, so there is nothing to budget for.
         const cfg = config || getConfig();
         const isMocking = process.env['PI_RESEARCH_MOCK_SCRAPE'] === 'true';
-        const timeoutMs = cfg.SCRAPE_TIMEOUT_MS + (isMocking ? 5000 : cfg.BROWSER_TASK_TIMEOUT_MS);
+        const timeoutMs = cfg.SCRAPE_TIMEOUT_MS + (isMocking ? 5000 : cfg.BROWSER_TASK_TIMEOUT_MS + COLD_START_ALLOWANCE_MS);
 
         // Armed on dispatch, not on enqueue — see runSearch for why.
         // See runSearch: dispatch time is tracked for measurement, not for the deadline.

package/src/infrastructure/browser/config.ts

@@ -346,13 +346,50 @@ function isFullMockMode(): boolean {
  *     and a budget below that sum makes the fallback ladder unreachable — so raising
  *     HEALTH_CHECK_TIMEOUT_MS used to make the health check strictly worse.
  *
- * Floored at the historical 105s so default installs are unchanged.
+ * Floored at the historical 105s, kept as a floor rather than a default: the
+ * derived value now exceeds it even at default timeouts once COLD_START_ALLOWANCE_MS
+ * (below) is folded into `longestSlotHold` — a cold Firefox launch was always able to
+ * hold a slot for close to that long, the 105s floor just didn't know it. The floor
+ * still matters for a hypothetical config where the derived value would otherwise land
+ * below it.
  */
 export const HEALTHCHECK_MIN_BUDGET_MS = 45_000 + 60_000;
 
 /** Navigation attempts executeHealthCheck makes: primary, retry, fallback endpoint. */
 const HEALTHCHECK_NAV_ATTEMPTS = 3;
 
+/**
+ * Hard ceiling on a single Camoufox browser launch (see launchOnce() in
+ * thread-worker-browser.ts, the single source of truth this mirrors — CI runners
+ * (2 vCPU) can take up to ~60s to start Firefox under load, floored generously
+ * above that).
+ */
+export const BROWSER_LAUNCH_TIMEOUT_MS = 90_000;
+
+/**
+ * Hard ceiling on creating one BrowserContext against an already-launched browser
+ * (see acquireTaskContext() in thread-worker-browser.ts, the single source of
+ * truth this mirrors).
+ */
+export const CONTEXT_CREATION_TIMEOUT_MS = 30_000;
+
+/**
+ * Worst-case time a worker can spend getting a browser+context ready before it
+ * starts a task's actual work. Eager warmup is deliberately disabled (thundering-
+ * herd avoidance — see thread-worker.ts), so the first task dispatched to a
+ * freshly created or just-reset worker pays this in full, inline with the task
+ * itself. Every deadline that bounds how long a task may legitimately hold a
+ * worker slot has to include this on top of its own nav budget, or a completely
+ * normal cold start on a fresh pool reads as a dead/wedged worker — the false
+ * positive `runSearch`/`runScrape`'s task-timeout ceiling and this budget were
+ * both built to eliminate, just triggered by a different clock.
+ *
+ * Deliberately NOT part of BROWSER_TASK_TIMEOUT_MS: that value is user-tunable
+ * overhead for per-task work, and cold-start cost isn't something a user should
+ * need to account for by hand when adjusting it.
+ */
+export const COLD_START_ALLOWANCE_MS = BROWSER_LAUNCH_TIMEOUT_MS + CONTEXT_CREATION_TIMEOUT_MS;
+
 export function getHealthCheckBudgetMs(config?: Config): number {
     const c = (config || getConfig()) as Partial<Config>;
     // Each field is read defensively. A missing or non-finite value would otherwise
@@ -363,7 +400,8 @@ export function getHealthCheckBudgetMs(config?: Config): number {
         typeof value === 'number' && Number.isFinite(value) ? value : fallback;
     const longestSlotHold =
         Math.max(ms(c.SEARCH_TIMEOUT_MS, 45_000), ms(c.SCRAPE_TIMEOUT_MS, 15_000))
-        + ms(c.BROWSER_TASK_TIMEOUT_MS, 10_000);
+        + ms(c.BROWSER_TASK_TIMEOUT_MS, 10_000)
+        + COLD_START_ALLOWANCE_MS;
     // Mirrors the worker's own floor in executeHealthCheck.
     const probeWork = HEALTHCHECK_NAV_ATTEMPTS * Math.max(10_000, ms(c.HEALTH_CHECK_TIMEOUT_MS, 10_000));
     return Math.max(HEALTHCHECK_MIN_BUDGET_MS, longestSlotHold + probeWork);