@lincoln504/pi-research 1.3.12 → 1.4.3

package/src/utils/cancellation.ts

@@ -0,0 +1,36 @@
+/**
+ * Cancellation detection shared by the agent-facing tools.
+ *
+ * Every tool wrapper is built to never throw: a failure becomes prose the agent
+ * reads and acts on. That contract is right for a failure and wrong for a
+ * cancellation, because the prose is written to explain a *fault* — "this may be
+ * due to API rate limiting", "unable to search security databases, try again
+ * later", "may be due to network issues or YouTube bot-protection". When the user
+ * presses Ctrl-C, the in-flight work rejects with an abort and those sentences are
+ * simply false. The agent believes them: it retries, spends budget the user just
+ * asked it to stop spending, and can carry the invented cause into the report.
+ *
+ * A cancellation must therefore propagate. The run is ending either way, and the
+ * throw is what unwinds the agent loop instead of feeding it a fabricated fault.
+ */
+
+/**
+ * True when `error` represents the abort of `signal` (or an abort in general)
+ * rather than a genuine failure of the work.
+ *
+ * The message-shape check is the load-bearing part in practice. Cancellation
+ * crosses several layers here — worker IPC, HTTP to the browser leader, the
+ * research orchestrator's own abort plumbing — and only some of them preserve
+ * `AbortError` as the error name; the rest arrive as a plain Error whose message
+ * is the reason string. `signal.aborted` alone is not sufficient either: a tool
+ * may be handed no signal at all, and a signal can abort after the failure it is
+ * being asked to explain.
+ */
+export function isCancellation(error: unknown, signal?: AbortSignal | null): boolean {
+  if (signal?.aborted) return true;
+  if (error instanceof Error && error.name === 'AbortError') return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return /^(aborted|the operation was aborted|research (aborted|cancelled|canceled)|operation cancelled|operation canceled)\.?$/i.test(
+    message.trim(),
+  );
+}

package/src/utils/coverage-digest.ts

@@ -0,0 +1,204 @@
+/**
+ * Coverage digests — the routing half of the evaluator's input.
+ *
+ * A researcher emits a short, structured account of what it covered at the HEAD of its
+ * report, delimited by `COVERAGE DIGEST` / `END COVERAGE DIGEST`. The digest is split off
+ * when the report is stored, so every consumer of a report body sees one without routing
+ * metadata in it. The router reads a fresh report in full WITH its digest beside it, and
+ * represents every earlier round by digest alone; the synthesizer reads bodies only.
+ *
+ * Why the head and not the tail: the tail already belongs to `CITED LINKS`, and a report
+ * that gets truncated mid-write (timeout, token ceiling — see researcher-executor's
+ * partial-report path) loses its tail first. A digest at the head survives truncation,
+ * which is exactly the case where the router most needs to know what was and wasn't
+ * established.
+ *
+ * Everything here is defensive: a missing, unterminated, or oversized digest must degrade
+ * to a usable router input, never to a lost report body. The report is the run's product;
+ * the digest is an optimization.
+ */
+
+import { parseCitations, lastCitedLinksHeaderIndex } from './text-utils.ts';
+
+/** Opening delimiter, matched line-leading and case-insensitively. */
+export const COVERAGE_DIGEST_HEADER = 'COVERAGE DIGEST';
+
+/** Closing delimiter. Required — see `splitCoverageDigest`. */
+export const COVERAGE_DIGEST_TERMINATOR = 'END COVERAGE DIGEST';
+
+/**
+ * How far into the report the opening delimiter may appear and still count.
+ *
+ * The digest is specified to be the first thing in the report, but models routinely emit
+ * a short preamble ("Here is my report:") ahead of it. This window tolerates that while
+ * refusing to match the phrase occurring incidentally in the middle of prose — a report
+ * ABOUT research methodology could well discuss a "coverage digest", and treating that as
+ * a delimiter would silently truncate everything before it out of the synthesis corpus.
+ */
+const DIGEST_HEAD_WINDOW_CHARS = 600;
+
+/**
+ * Ceiling on the digest text handed to the router.
+ *
+ * A well-formed digest is a handful of lines. A digest much larger than this means the
+ * model wrote its findings inside the delimiters, which would reintroduce exactly the
+ * unbounded routing input this protocol exists to remove. The body is unaffected — it is
+ * whatever follows the terminator either way — so capping here costs nothing but router
+ * detail.
+ */
+export const MAX_DIGEST_CHARS = 2400;
+
+/**
+ * Terminator must appear within this distance of the header for the block to be treated
+ * as a digest. Bounds the damage from a model that writes the opening delimiter, forgets
+ * the closing one, and happens to write `END COVERAGE DIGEST` much later (or from a
+ * report that quotes both delimiters while discussing this very protocol).
+ */
+const MAX_DIGEST_BLOCK_CHARS = 8000;
+
+/**
+ * The `{{digest_section}}` block of the researcher prompt, for a run that has a research
+ * lead to route (depth 1+).
+ *
+ * Left EMPTY for quick research: that mode has no lead and no second round, its report goes
+ * straight to the user, and asking for routing metadata there would spend output tokens on
+ * a reader that does not exist — while telling the model about a "research lead" that is
+ * not part of its run.
+ */
+export const RESEARCHER_DIGEST_SECTION = `Your report has three parts in this exact order: a COVERAGE DIGEST block, the report body, and the CITED LINKS list.
+
+### Part 1 — COVERAGE DIGEST (first, mandatory)
+
+Open the report with this block, exactly as shown. The research lead reads it to decide what still needs investigating. On the round your report arrives the lead reads the digest alongside the full report and checks one against the other; on every later round it sees ONLY this digest — so anything you leave out of it is invisible to every decision after the first.
+
+${COVERAGE_DIGEST_HEADER}
+Goal: [your assigned goal, restated in one line]
+Covered: [the specific topics you actually established from sources, separated by semicolons — be concrete, name the things you found out, not the areas you looked at]
+Unsubstantiated: [claims you searched for but could not ground in any source; write "none" if there are none]
+Gaps: [what a follow-up researcher would still need to investigate on this goal; write "none" if your goal is fully covered]
+Sources: [the number of entries in your CITED LINKS list]
+${COVERAGE_DIGEST_TERMINATOR}
+
+Rules for the digest:
+- Keep it under 150 words total. It is an index, not a summary — no [N] citations, no findings prose, no URLs.
+- Be honest about \`Gaps\` and \`Unsubstantiated\`. Claiming full coverage you do not have is the single most damaging thing you can write here: it argues for ending the research on this topic, and after the round it arrives there is no report left for the lead to check the claim against.
+- Write both delimiter lines exactly, in capitals, each on its own line.
+
+### Part 2 — Report body
+
+`;
+
+/** Line-leading delimiter matcher, tolerating the markdown decoration models add. */
+function delimiterRegex(word: string): RegExp {
+  return new RegExp(`(^|\\n)([ \\t]*(?:#{1,6}[ \\t]*|>[ \\t]*|\\*\\*[ \\t]*)?)${word}\\b`, 'i');
+}
+
+export interface SplitReport {
+  /** Digest text WITHOUT the delimiter lines, trimmed and capped. Empty when absent. */
+  digest: string;
+  /** The report body with the digest block removed. Never empty unless the input was. */
+  body: string;
+}
+
+/**
+ * Split a researcher report into its coverage digest and its body.
+ *
+ * Both delimiters are required. A header with no terminator is treated as NO digest and
+ * the report is returned intact: the alternative — guessing where the block ends — risks
+ * swallowing the findings, and a report that reaches the synthesizer whole is strictly
+ * better than one that reaches it short.
+ */
+export function splitCoverageDigest(report: string): SplitReport {
+  if (!report) return { digest: '', body: report };
+
+  const headerMatch = delimiterRegex(COVERAGE_DIGEST_HEADER).exec(report);
+  if (!headerMatch) return { digest: '', body: report };
+
+  const lineStart = headerMatch.index + headerMatch[1]!.length;
+  if (lineStart > DIGEST_HEAD_WINDOW_CHARS) return { digest: '', body: report };
+
+  // Search for the terminator strictly AFTER the header line, so `END COVERAGE DIGEST`
+  // cannot match the header's own trailing text.
+  const afterHeaderWord = lineStart + headerMatch[2]!.length + COVERAGE_DIGEST_HEADER.length;
+  // Consume the header's WHOLE line, not just the matched word — mirrors the terminator
+  // handling below. A model that writes `**COVERAGE DIGEST**` matches on the leading
+  // marker; without this, the trailing `**` (or a closing `:`, `##`, etc.) would dangle
+  // at the head of the digest text instead of being discarded as delimiter.
+  const headerNewline = report.indexOf('\n', afterHeaderWord);
+  const afterHeader = headerNewline < 0 ? afterHeaderWord : headerNewline + 1;
+  const rest = report.slice(afterHeader);
+  const endMatch = delimiterRegex(COVERAGE_DIGEST_TERMINATOR).exec(rest);
+  if (!endMatch) return { digest: '', body: report };
+
+  const endLineStart = endMatch.index + endMatch[1]!.length;
+  if (endLineStart > MAX_DIGEST_BLOCK_CHARS) return { digest: '', body: report };
+
+  const digestRaw = rest.slice(0, endLineStart).trim();
+  // Consume the terminator's WHOLE line, not just the matched word: a model that writes
+  // `**END COVERAGE DIGEST**` matches on the leading marker and would otherwise leave the
+  // trailing `**` dangling at the head of the body. The terminator line is delimiter, so
+  // none of it belongs to the report.
+  const afterWord = endMatch.index + endMatch[0]!.length;
+  const nextNewline = rest.indexOf('\n', afterWord);
+  const bodyAfter = nextNewline < 0 ? '' : rest.slice(nextNewline + 1);
+
+  // Anything the model wrote BEFORE the digest (a preamble) is kept — it is part of the
+  // report, and dropping content is never the safe default here.
+  const bodyBefore = report.slice(0, lineStart);
+  const body = `${bodyBefore}${bodyAfter}`.trim();
+
+  const digest = digestRaw.length > MAX_DIGEST_CHARS
+    ? `${digestRaw.slice(0, MAX_DIGEST_CHARS).trimEnd()}\n(digest truncated)`
+    : digestRaw;
+
+  // A digest is only worth having if a body survives it. If the "body" came out empty the
+  // model put the entire report inside the delimiters; return the original so nothing is
+  // lost, and let the derived digest below serve routing.
+  if (!body) return { digest: '', body: report };
+
+  return { digest, body };
+}
+
+/**
+ * Build a minimal digest for a report that carries none.
+ *
+ * Reached for older/partial reports and for models that ignore the format instruction.
+ * The router must never be blind to a researcher that actually ran, so this derives the
+ * two facts that can be read off any report mechanically — its opening topic line and how
+ * many sources it cited — and says plainly that the rest is unknown. A router told
+ * "coverage unknown" delegates; a router told nothing assumes the gap was filled.
+ */
+export function deriveCoverageDigest(body: string): string {
+  const citationCount = parseCitations(body).length;
+
+  // The report's first line is its topic title by the researcher prompt's format. Read it
+  // from the prose region only — a report that is nothing BUT a CITED LINKS section would
+  // otherwise present a URL line as its topic.
+  const citedIdx = lastCitedLinksHeaderIndex(body);
+  const prose = citedIdx >= 0 ? body.slice(0, citedIdx) : body;
+  const firstLine = prose
+    .split('\n')
+    .map((l) => l.replace(/^[#>*\s]+/, '').trim())
+    .find((l) => l.length > 0) ?? '';
+
+  const topic = firstLine.length > 200 ? `${firstLine.slice(0, 200).trimEnd()}…` : firstLine;
+
+  return [
+    `Covered: ${topic || 'unknown — the report has no readable topic line'}`,
+    `Gaps: unknown — this researcher emitted no coverage digest`,
+    `Sources: ${citationCount}`,
+  ].join('\n');
+}
+
+/**
+ * Render the router's view of the run: one block per researcher, in report order.
+ *
+ * Deliberately mirrors the findings block's `### Researcher <id>` shape so the router's
+ * researcher ids line up with the ids the synthesizer and the query history already use.
+ */
+export function formatDigestsForRouter(digests: ReadonlyMap<string, string>): string {
+  if (digests.size === 0) return '';
+  return Array.from(digests.entries())
+    .map(([id, digest]) => `### Researcher ${id}\n${digest}`)
+    .join('\n\n');
+}

package/src/utils/host-config.ts

@@ -27,11 +27,22 @@ let _configDirName: string | undefined;
  * Resolution order: explicit env override (`PI_RESEARCH_CONFIG_DIR_NAME`) →
  * the host `@earendil-works/pi-coding-agent` package (only where it is actually
  * resolvable, i.e. the main pi process) → the stable default `.pi`.
+ *
+ * The override is a directory NAME, not a path: it is joined onto
+ * `os.homedir()` by every caller (getGlobalConfigDir() in config.ts), which in
+ * turn is the base for config.env (API keys, chmod 0600), the state dir
+ * (locks, run semaphores), and the knowledge_db. A value containing a path
+ * separator or `..` traverses out of HOME entirely — scripts/cleanup.cjs
+ * already rejects exactly that in its own copy of this resolution (see its
+ * `rawDirName`/`dirName` guard); this must reject it the same way, since this
+ * is the copy every actual run resolves secrets and state through.
  */
 export function getConfigDirName(): string {
   if (_configDirName !== undefined) return _configDirName;
   const override = process.env['PI_RESEARCH_CONFIG_DIR_NAME'];
-  if (override) return (_configDirName = override);
+  if (override && !override.includes('/') && !override.includes('\\') && override !== '.' && override !== '..') {
+    return (_configDirName = override);
+  }
   try {
     const require = createRequire(import.meta.url);
     const host = require('@earendil-works/pi-coding-agent') as { CONFIG_DIR_NAME?: string };

package/src/utils/llm-usage.ts

@@ -12,7 +12,7 @@
  */
 
 import type { Model } from '@earendil-works/pi-ai';
-import { extractUsage } from '../types/llm.ts';
+import { extractUsage, type TokenUsage } from '../types/llm.ts';
 import { logger } from '../logger.ts';
 import { metrics } from './metrics.ts';
 
@@ -51,12 +51,35 @@ function warnIfUnpriced(model: Model<any>, tokens: number, cost: number): void {
   );
 }
 
+/**
+ * Record the prompt-cache split alongside the plain token counter.
+ *
+ * `llm_tokens_total` folds cached and uncached input into one number, so a run whose
+ * prefix cache never hits is indistinguishable from one that hits on every call — the
+ * cost line moves, but nothing says why. These two counters are the only signal that
+ * prompt caching is working at all, and they are what a caching regression shows up in:
+ * a prompt edit that pushes volatile text ahead of stable text drives `cache_read` to
+ * zero while `cache_write` keeps climbing.
+ *
+ * Zero-valued counters are still emitted (when the provider reported the field at all)
+ * so "cache is off" and "provider does not report caching" stay distinguishable: the
+ * first shows the counter at 0, the second omits it.
+ */
+function recordCacheTokens(parsed: Partial<TokenUsage>, labels: Record<string, string>): void {
+  if (typeof parsed.cacheRead === 'number') {
+    metrics.increment('llm_cache_read_tokens_total', parsed.cacheRead, labels);
+  }
+  if (typeof parsed.cacheWrite === 'number') {
+    metrics.increment('llm_cache_write_tokens_total', parsed.cacheWrite, labels);
+  }
+}
+
 /** Structural subset of the run observer — just the token sinks. Kept structural (rather
  *  than importing ResearchObserver from core/) so this foundation-layer helper does not
  *  depend on an upper layer; the full ResearchObserver satisfies it. */
 export interface TokenSink {
   onTokensConsumed?: (tokens: number, cost: number) => void;
-  /** Phase-scoped sinks, fed from the `component` label ('coordinator'/'evaluator');
+  /** Phase-scoped sinks, fed from the `component` label ('coordinator', 'router'/'synthesizer');
    *  they drive the TUI coord/eval cost rows and the SDK planning_tokens /
    *  evaluation_tokens events. */
   onPlanningTokens?: (tokens: number, cost: number) => void;
@@ -64,7 +87,7 @@ export interface TokenSink {
 }
 
 export interface RecordUsageOptions {
-  /** Metrics `component` label (e.g. 'coordinator', 'evaluator', 'researcher'). */
+  /** Metrics `component` label (e.g. 'coordinator', 'router', 'synthesizer', 'researcher'). */
   component: string;
   /** Optional complexity label, stringified for the metric labels. */
   complexity?: number | string;
@@ -83,23 +106,27 @@ export function recordLlmUsage(
   opts: RecordUsageOptions
 ): { tokens: number; cost: number } {
   if (!rawUsage) return { tokens: 0, cost: 0 };
-  const { tokens, cost } = extractUsage(model, rawUsage);
+  const { tokens, cost, parsed } = extractUsage(model, rawUsage);
   warnIfUnpriced(model, tokens, cost);
   if (tokens > 0 || cost > 0) {
     const labels: Record<string, string> = { component: opts.component };
     if (opts.complexity !== undefined) labels['complexity'] = String(opts.complexity);
     metrics.increment('llm_tokens_total', tokens, labels);
     metrics.increment('llm_cost_total', cost, labels);
+    recordCacheTokens(parsed, labels);
     opts.observer?.onTokensConsumed?.(tokens, cost);
     // Phase-scoped events: coordinator/evaluator call sites label their usage
-    // 'coordinator'/'evaluator' (see planning-service.ts); route those to the
+    // 'coordinator'/'router'/'synthesizer' (see planning-service.ts); route those to the
     // dedicated observer hooks so the TUI coord/eval cost rows and the SDK
     // planning_tokens/evaluation_tokens events fire. Before this mapping the hooks
     // had zero emit sites (regression in c90d7f37) — coordinator/evaluator usage
     // reached only onTokensConsumed, which the TUI observer does not implement.
     if (opts.component === 'coordinator') {
       opts.observer?.onPlanningTokens?.(tokens, cost);
-    } else if (opts.component === 'evaluator') {
+    } else if (opts.component === 'router' || opts.component === 'synthesizer') {
+      // Both halves of the research lead feed the one evaluation row. They used to be a
+      // single 'evaluator' component; splitting the roles must not split the cost the
+      // user sees, so they are summed here rather than given separate sinks.
       opts.observer?.onEvaluationTokens?.(tokens, cost);
     }
   }

package/src/utils/log-utils.ts

@@ -255,6 +255,16 @@ export function redactSecrets(message: string): string {
     // never negative; it still prefers the larger rawLength when the
     // REDACT_SCAN_LENGTH cut discarded raw content redaction then shrank.
     out = `${out.slice(0, keep)}…[truncated ${Math.max(rawLength, out.length) - keep} chars]`;
+  } else if (rawLength > scanEnd) {
+    // The scanEnd cut (line 220) already dropped `rawLength - scanEnd` raw
+    // chars before redaction ever ran. If redaction then net-shrinks the
+    // scanned prefix enough that `out.length` no longer exceeds
+    // MAX_LOG_MESSAGE_LENGTH (e.g. many long hex/JWT runs each collapsed to
+    // the short literal '[REDACTED]'), the branch above never fires and this
+    // message would otherwise read as complete — silently hiding the tail of
+    // a large scraped page or provider error body with no indication
+    // anything was cut.
+    out = `${out}…[truncated ${rawLength - scanEnd} chars]`;
   }
   return out;
 }

package/src/utils/metrics-summary.ts

@@ -133,9 +133,19 @@ export function extractRunStats(snapshot: IMetricsSnapshot): ResearchStats | nul
   // Researchers launched
   const researchersLaunched = sumCounter(counters, 'researchers_launched_total');
 
-  // Search queries — combine browser search and regular search
+  // Search queries. These two counters count the SAME queries, one layer apart:
+  // browser-search increments `browser_search_queries_total` exactly once per query
+  // across its success/no-results/timeout/error branches, and its only caller then
+  // increments `search_queries_total` by successes plus failures — the same set. Summing
+  // them reported "N searches" at exactly twice the truth in the report footer and the
+  // session metrics view, and three times it on the outer-catch path, which adds
+  // `queries.length` a second time.
+  //
+  // Same shape as the URL counters below, and resolved the same way: the per-query
+  // counter IS the count; the caller-level one is a fallback for a search that threw
+  // before dispatching anything, where the inner counter never fired at all.
   const browserSearchQueries = sumCounter(counters, 'browser_search_queries_total');
-  const searchQueries = sumCounter(counters, 'search_queries_total') + browserSearchQueries;
+  const searchQueries = browserSearchQueries || sumCounter(counters, 'search_queries_total');
 
   // URLs discovered via search. browser_search_unique_urls_total is the
   // cross-query deduped subset of the SAME batch counted by
@@ -203,8 +213,14 @@ export function extractRunStats(snapshot: IMetricsSnapshot): ResearchStats | nul
     }
   }
 
-  // Rounds completed — evaluator runs give us the round count
-  const roundsCompleted = sumCounter(counters, 'evaluator_runs_total');
+  // Rounds completed. This read `evaluator_runs_total`, whose only reference in the
+  // whole repository was this line — the emit site was deleted in c90d7f37 and the
+  // reader was left behind, so the value was always 0 and `buildResearchSummary`'s
+  // `roundsCompleted > 1` gate meant the "N rounds" element had never once rendered for
+  // any multi-round run. The orchestrator now emits a counter that says what it means.
+  // The old name is still summed so a snapshot captured before this change still reads.
+  const roundsCompleted =
+    sumCounter(counters, 'research_rounds_completed_total') || sumCounter(counters, 'evaluator_runs_total');
 
   // Complexity
   let complexity = 1;

package/src/utils/metrics.ts

@@ -83,7 +83,7 @@ export class MetricsRegistry {
   public increment(name: string, value: number = 1, labels?: Labels): void {
     const key = this.getKey(name, labels);
     this.counters.set(key, (this.counters.get(key) ?? 0) + value);
-    if (name === 'llm_cost_total' || name === 'llm_tokens_total') {
+    if (name.startsWith('llm_')) {
       logger.debug(`[Metrics] Incremented ${name} by ${value}${labels ? ` (labels: ${JSON.stringify(labels)})` : ''}`);
     }
   }
@@ -243,6 +243,32 @@ class SessionMetrics {
     return this.getActive().measure(name, action, labels);
   }
 
+  /**
+   * Emit API that ALWAYS targets the session registry, ignoring any active run
+   * context.
+   *
+   * For process-lifetime callbacks that happen to be *registered* during a run.
+   * AsyncLocalStorage resolves at emit time from the async resource that fired,
+   * and for a listener installed on a long-lived emitter that resource is the
+   * emitter itself — created, for every lazily-initialized subsystem here, inside
+   * whichever run first needed it. So a worker-pool error handler installed during
+   * run 1 keeps writing into run 1's registry for the rest of the process: those
+   * counts disappear from every later run's summary (the registry was discarded
+   * when the run ended) and the dead registry stays reachable through the closure.
+   *
+   * Use this only where the emission is genuinely process-scoped. Anything that
+   * describes work a run asked for belongs in the run registry, which is what the
+   * plain emit methods above give you.
+   */
+  public readonly session = {
+    increment: (name: string, value: number = 1, labels?: Labels): void =>
+      this._session.increment(name, value, labels),
+    setGauge: (name: string, value: number, labels?: Labels): void =>
+      this._session.setGauge(name, value, labels),
+    observe: (name: string, value: number, labels?: Labels): void =>
+      this._session.observe(name, value, labels),
+  };
+
   // ── Session-level read API ─────────────────────────────────────────────
 
   /** Snapshot of the session registry (infrastructure / cross-run metrics). */

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

@@ -5,7 +5,8 @@
  */
 
 import { runWorkerSearch } from '../infrastructure/browser/task-execution-service.ts';
-import { getMaxWorkers } from '../infrastructure/browser/config.ts';
+import { getMaxWorkers, COLD_START_ALLOWANCE_MS } from '../infrastructure/browser/config.ts';
+import { isTaskTimeoutError } 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';
@@ -80,20 +81,28 @@ export async function performSearch(
     // Hard cap per query so a single Cloudflare block or hung browser worker
     // cannot stall the entire Promise.all burst.
     //
-    // The budget is the worker's nav budget (SEARCH_TIMEOUT_MS) PLUS the
-    // queue-wait/overhead margin (BROWSER_TASK_TIMEOUT_MS), mirroring the
-    // scheduler's own task-timeout ceiling in BrowserTaskScheduler.runSearch
-    // (= SEARCH_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_MS). This clock starts at
-    // ENQUEUE (before runWorkerSearch queues onto the shared browser pool), so
-    // a budget of only SEARCH_TIMEOUT_MS would let a query that sat in the
-    // saturated worker queue burn its ENTIRE nav budget waiting for a slot and
-    // abort with zero actual search work — exactly the "Query timed out after
-    // 45000ms (likely blocked or slow startup)" cascade observed under
-    // concurrent load. Including the margin lets a queued query still use its
-    // full nav budget once a worker picks it up, and keeps this layer's hard
-    // cap coherent with the scheduler's so it never preempts the worker's own
-    // (post-dequeue) deadline.
-    const QUERY_TIMEOUT_MS = (config?.SEARCH_TIMEOUT_MS ?? 45_000) + (config?.BROWSER_TASK_TIMEOUT_MS ?? 10_000);
+    // The budget mirrors the scheduler's own task ceiling in
+    // BrowserTaskScheduler.runSearch (= SEARCH_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_MS +
+    // COLD_START_ALLOWANCE_MS) so this layer never preempts the worker's deadline with
+    // a shorter one.
+    //
+    // Both clocks now start at DISPATCH (see startQueryDeadline below), which is
+    // what makes mirroring the value correct. While this one started at enqueue,
+    // equal values meant the two raced and whichever fired first reported — which
+    // is why the same starvation shows up in the logs under two different messages
+    // on different days. The earlier response to that was to widen this budget
+    // (nav plus a margin) so a queued query could still use its full nav budget
+    // once picked up. That treats the symptom: a margin only buys one extra
+    // query's worth of wait, and a burst four times the pool's reach exhausts any
+    // constant. Measuring execution instead of waiting is the fix; the sum
+    // survives as the budget because a search legitimately costs nav plus overhead.
+    //
+    // COLD_START_ALLOWANCE_MS is part of the sum for the same reason it is part of
+    // the scheduler's own ceiling: the first query dispatched to a freshly created or
+    // just-reset worker pays a real browser launch + context creation inline before
+    // any navigation starts, and this layer's budget must not fire before the
+    // scheduler's own (correct, larger) deadline gets a chance to.
+    const QUERY_TIMEOUT_MS = (config?.SEARCH_TIMEOUT_MS ?? 45_000) + (config?.BROWSER_TASK_TIMEOUT_MS ?? 10_000) + COLD_START_ALLOWANCE_MS;
 
     // Deduplicated: resultMap and the failures map are both keyed by the query
     // string, so two tasks for the same string race last-writer-wins — instance A
@@ -108,11 +117,34 @@ export async function performSearch(
     // timeout guess that misdirects to the network or system load.
     let sampleWorkerError = '';
 
-    const searchTasks = filteredQueries.map(async (query) => {
+    const runQuery = async (query: string): Promise<void> => {
         const queryStartTime = Date.now();
         const timeoutController = new AbortController();
-        const timeoutId = setTimeout(() => timeoutController.abort(), QUERY_TIMEOUT_MS);
-        safeUnref(timeoutId);
+        // Armed by onDispatch below — when the browser queue hands this query to a
+        // worker — not here. Arming here charged queue wait to the query's budget, so
+        // a burst larger than the pool could serve inside one budget killed its own
+        // tail: every query enqueued in the same millisecond, and 90s later the ones
+        // still waiting aborted together having done no work. Measured at 78 of 100.
+        // The scheduler owns the execution deadline; this is the caller-side mirror of
+        // it, and against a follower scheduler — which cannot observe leader dispatch
+        // and so never calls onDispatch — it stays disarmed and the client's own
+        // bound applies instead.
+        let timeoutId: NodeJS.Timeout | undefined;
+        const onTaskEvent = (event: 'dispatched' | 'settled') => {
+            // Disarm on every event, so the clock only ever runs while a worker is
+            // actually holding this query. Arming alone was not enough: retries inside
+            // runWorkerSearch dispatch AGAIN, and between a failed attempt and its
+            // redispatch there is a backoff sleep, a re-enqueue and a fresh queue wait.
+            // A timer left running across that gap aborts the retry for its
+            // predecessor's overrun, and reports it as "the browser pool was
+            // saturated" — the same charge-the-wait-to-the-work mistake, one attempt
+            // removed.
+            if (timeoutId) clearTimeout(timeoutId);
+            timeoutId = undefined;
+            if (event !== 'dispatched') return;
+            timeoutId = setTimeout(() => timeoutController.abort(), QUERY_TIMEOUT_MS);
+            safeUnref(timeoutId);
+        };
 
         try {
             if (signal?.aborted) {
@@ -124,7 +156,7 @@ export async function performSearch(
               ? AbortSignal.any([signal, timeoutController.signal])
               : timeoutController.signal;
 
-            const results = await runWorkerSearch(query, config, querySignal, 1, sessionId, container);
+            const results = await runWorkerSearch(query, config, querySignal, 1, sessionId, container, undefined, onTaskEvent);
             const queryDuration = Date.now() - queryStartTime;
             metrics.observe('browser_search_query_duration_ms', queryDuration);
 
@@ -168,7 +200,21 @@ export async function performSearch(
             }
         } catch (error) {
             const queryDuration = Date.now() - queryStartTime;
-            const isTimeout = timeoutController.signal.aborted && !signal?.aborted;
+            // Two clocks can end this query, and only one of them used to be recognised.
+            // The scheduler's own execution deadline is armed in the same synchronous
+            // block as this layer's guard, with the SAME duration derived from the same
+            // two config values — so on the leader path the scheduler's timer is always
+            // registered first, always fires first, and its rejection clears this layer's
+            // timer before Node ever reaches it. `timeoutController.signal.aborted` was
+            // therefore false for every real search timeout in the leader path.
+            //
+            // The consequences all pointed the wrong way: the query was logged at ERROR,
+            // counted as `status=error`, and reported to the researcher as "an
+            // infrastructure failure" — while `timeoutCount` stayed at zero, making the
+            // whole-burst timeout attribution below unreachable. A task timeout is a
+            // timeout whichever clock names it.
+            const isTimeout = (timeoutController.signal.aborted || isTaskTimeoutError(error))
+                && !signal?.aborted;
             const status = isTimeout ? 'timeout' : 'error';
             
             if (isTimeout) timeoutCount++;
@@ -211,9 +257,43 @@ export async function performSearch(
             clearTimeout(timeoutId);
             if (onProgress) onProgress(seenUrls.size);
         }
-    });
+    };
 
-    await Promise.all(searchTasks);
+    // Dispatch through a bounded number of lanes instead of handing every query to
+    // Promise.all at once.
+    //
+    // The old form started ALL N queries simultaneously, which meant N minus maxWorkers of
+    // them sat in the shared browser queue with their per-query deadline ALREADY TICKING —
+    // the clock started at enqueue, not when a worker picked the query up. That made the
+    // number of queries which could possibly succeed `maxWorkers x (budget / latency)`
+    // rather than N. Measured on a level-3 run: 100 queries dispatched into 6 workers went
+    // 94 deep in the queue, 78 of them aborted at the 90s mark having never run, and the
+    // burst returned 49 results. Worse, each of those was reported to its researcher as a
+    // timeout with "retrying the same query later is reasonable", so the next round
+    // re-queued them and the burst grew.
+    //
+    // A lane only picks up its next query when the previous one finishes, so the shared
+    // queue never builds a backlog and every query eventually runs. The burst takes longer
+    // in wall-clock terms; it no longer discards most of itself to get there.
+    //
+    // Lanes are not what makes a query's deadline honest — dispatch-armed timers do that,
+    // at both this layer and the scheduler's, and they hold no matter how deep the queue
+    // gets. Lanes remain because bounding depth is worth having on its own: the pool is
+    // shared with scrapes and healthchecks and with other concurrent runs, and a burst that
+    // dumps its whole plan into the queue delays all of them.
+    const lanes = Math.max(1, Math.min(maxWorkers, filteredQueries.length));
+    let nextIndex = 0;
+    const runLane = async (): Promise<void> => {
+        for (;;) {
+            const index = nextIndex++;
+            if (index >= filteredQueries.length) return;
+            // Stop pulling new work once the caller has cancelled; queries already
+            // dispatched settle through their own abort path.
+            if (signal?.aborted) return;
+            await runQuery(filteredQueries[index]!);
+        }
+    };
+    await Promise.all(Array.from({ length: lanes }, () => runLane()));
 
     // A cancelled run is not a broken one. Every query aborts with zero results,
     // which walks straight into the total-failure branch below and reports