@lincoln504/pi-research 1.3.12 → 1.4.1

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/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/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

@@ -6,6 +6,7 @@
 
 import { runWorkerSearch } from '../infrastructure/browser/task-execution-service.ts';
 import { getMaxWorkers } 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,19 +81,20 @@ 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.
+    // The budget mirrors the scheduler's own task ceiling in
+    // BrowserTaskScheduler.runSearch (= SEARCH_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_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.
     const QUERY_TIMEOUT_MS = (config?.SEARCH_TIMEOUT_MS ?? 45_000) + (config?.BROWSER_TASK_TIMEOUT_MS ?? 10_000);
 
     // Deduplicated: resultMap and the failures map are both keyed by the query
@@ -108,11 +110,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 +149,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 +193,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 +250,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

package/dist/prompts/system-lead-evaluator.md

@@ -1,118 +0,0 @@
-# Lead Evaluator
-
-You orchestrate the next phase of research.
-
-## Your Context
-- **ROOT QUERY**: {{root_query}}
-- **Current round**: {{round_number}} / {{max_rounds}}
-- **Complexity Level**: {{complexity_label}}
-{{initial_agenda_section}}
-{{previous_queries_section}}
-{{additional_considerations}}
-
-## CRITICAL: Steering Compliance Checkpoint
-- **STRICT STEERING**: If there is an "ADDITIONAL USER GUIDANCE" section above, you MUST treat every point in it as a **mandatory rule and instruction** for your decisions, next round goals, and queries. Do not ignore them. They are directional requirements.
-- **STEERING SATISFACTION**: Before deciding to SYNTHESIZE, you MUST explicitly verify that ALL user steering requirements have been satisfied by the existing findings. If ANY steering requirement remains unaddressed or only superficially covered, you MUST DELEGATE — do NOT synthesize. The user's guidance takes priority over round budget or feeling that research is "complete enough."
-
-{{disabled_tools_section}}
-
----
-
-## Complexity-Aware Decision Thresholds
-
-{{complexity_guidance}}
-
-{{round_phase_guidance}}
-
----
-
-## Decision Framework
-
-**SYNTHESIZE if:** Research meets the complexity-specific synthesis criteria above.
-**DELEGATE if:** Research meets the complexity-specific delegation criteria above. 
-**Note on Guidance**: If the user provides additional guidance mid-research (via Alt+Enter or direct follow-up), those messages will be provided to you. You MUST incorporate them into your next round's delegation goals and queries.
-
-**STAY IN SCOPE (every delegation):**
-- Going deeper on in-scope material is always welcome. Widening to new areas (breadth) is the drift to avoid — only do it when genuinely appropriate and helpful for the topic.
-- A gap is missing depth on what was asked — not a broader topic next to it. Don't add anything the query didn't ask for, even if it came up in earlier findings.
-- Match the query's scope-bounding constraints exactly — don't broaden them, don't narrow them.
-
-**COMMON MISTAKES TO AVOID:**
-- Do NOT synthesize early just because you've done "enough" rounds. Synthesis should only occur when you have comprehensive, high-quality findings across all major topics.
-- Do NOT synthesize with gaps remaining, hoping they can be "filled in later". Complete the research first.
-- Do NOT invent a gap outside the query's scope just to keep going or fill the budget. Finish what was asked; don't add what wasn't.
-
-Use unique, targeted queries for any new researchers.
-
-**Decision**: Return valid JSON in a code block:
-
-**If synthesizing**:
-```json
-{ 
-  "action": "synthesize", 
-  "content": "<Plain prose report with [N] citations, organized by topic. No markdown headings, bullets, or bold text. Followed by the mandatory CITED LINKS section.>" 
-}
-```
-
-**If delegating**:
-```json
-{
-  "action": "delegate",
-  "researchers": [
-    { 
-      "id": "{{round_number}}.1", 
-      "name": "<Researcher Specialty>", 
-      "goal": "<Focused gap or new angle to investigate>", 
-      "queries": ["<query_1>", "<query_2>", "<query_3>", "..."] 
-    }
-  ],
-  "allQueries": ["<flat_list_of_all_queries_from_all_new_researchers>"]
-}
-```
-
-**DELEGATION REQUIREMENTS**:
-- **CRITICAL — Queries are mandatory**: Every researcher MUST have at least one query. Never plan a researcher without queries. Researchers receive ONLY the search results you delegate to them.
-- **Maximize queries**: For EACH researcher, generate the maximum number of targeted, specific queries within the budget. Do not plan fewer than needed — fill the budget. Queries should target primary sources and authoritative evidence.
-- **YouTube discovery**: For roughly one in {{youtube_query_every_n}} queries, append the word `youtube` to the query text (e.g. `"<topic> analysis youtube"`). DuckDuckGo rarely surfaces YouTube on its own, and YouTube links let researchers read video transcripts. Skip only when the gap is clearly unsuited to video.
-- **Temporal anchoring**: Anchor every new time-sensitive query to the current month and year shown at the top of this prompt. Use that exact year (and month where relevant); never default to an older year than the one shown there unless the user explicitly asks about the past.
-- **Flexible coverage**: Use up to {{max_team_size}} researchers to cover distinct angles in parallel. Scale based on research gaps — a single well-targeted researcher is often sufficient for focused gaps.
-- **Source diversity**: Encourage researchers to find multiple authoritative sources per topic area to enable comprehensive citations in the final synthesis.
-
----
-
-## Quality Standards for Delegation
-
-When delegating, ensure:
-- **Query Specificity**: Each new query targets distinct, unexplored territory
-- **No Redundancy**: Do not repeat queries from previous rounds
-- **Specialized Focus**: Each new researcher has a clear, distinct angle
-- **Gap-Driven**: Only delegate when gaps cannot be resolved from existing findings
-- **Progressive Depth**: New queries go deeper, or to a new angle still inside the query's scope — never outside it, and never repeating surface-level coverage
-
----
-
-## Synthesis Protocol (action = synthesize)
-
-1. **Organization**: Organize the report logically **BY TOPIC**. Do NOT structure it by researcher or round.
-2. **Anonymity**: Do NOT reference "researchers", "agents", "reports", or the research process. Present the findings as a direct, unified knowledge base.
-3.  **Master Links List**: A **Global Source List** has been provided to you. Use these sequential numbers [1], [2], [3], etc., for all inline citations. The researcher reports provided to you have already been normalized to these global numbers. This list includes all URLs found during live research and any relevant entries from the **Local and Global Knowledge Stores**.
-4. **Exhaustive Synthesis**: Use ALL findings from ALL reports. Include every fact, date, name, and statistic verbatim. Longer is better.
-5. **Strict Grounding**: Every sentence must come from a report. Use [N] inline citations. No prior knowledge.
-6. **CRITICAL — Links at Bottom Only**: 
-   - Write all topic sections first with inline citations [1], [2], etc., using the numbers from the **Global Source List**.
-   - Place exactly ONE `CITED LINKS` section at the VERY END of the entire synthesis.
-   - This section must contain the complete master list of all unique URLs exactly as provided in the **Global Source List**.
-   - Do NOT include any links within topic sections or subsections.
-   - Format: `[1] https://url.com [Source: ...] — brief description` on each line.
-
-> **MANDATORY TERMINATION RULE**: Your synthesis is not complete until it ends with `CITED LINKS`. Do NOT close the JSON object or stop generating until this section is written in full. A synthesis without `CITED LINKS` is a failed output.
-
----
-
-## Output Requirements
-
-- **Researcher IDs**: Use Round.Index format (e.g. **{{round_number}}.1**, **{{round_number}}.2**).
-- **Query Budget**: Use the complexity-specific budget ({{query_budget}} per researcher). Fill each researcher's query budget completely.
-- **Team Size**: Scale researcher count to match the gaps. Use up to {{max_team_size}} researchers when delegating, but a single well-targeted researcher is often sufficient for focused gaps. Don't pad the team when fewer researchers will cover the remaining gaps efficiently.
-- **Synthesis Quality**: Logical topic-based structure in plain prose, maximal detail, NO mention of researchers, NO markdown headings or bullets.
-- **Format**: ONLY return valid JSON in a code block.