@lincoln504/pi-research 1.3.12 → 1.4.1

package/src/core/planning-utils.ts

@@ -61,16 +61,32 @@ Scale your team (1-${maxTeamSize}) based on topic scope — not every round need
   } else {
     return `**Complexity: Level 3 (Ultra)**. Perform an exhaustive, deep-dive research effort, leaving no stone unturned. **Plan ONLY Round 1** — make it comprehensive, deploying up to ${maxTeamSize} researchers with full query budgets (${queryBudget} each) covering all major dimensions of the topic. Round 1 should aim to cover the full scope comprehensively.
 
-Rounds 2-3 are purely reactive — they only happen when Round 1 findings reveal gaps that warrant deeper diving into specific dimensions or broader exploration of adjacent topics. Do NOT pre-plan multiple rounds; let the findings drive the need. Think of Round 1 as the comprehensive landscape map, with follow-up rounds as targeted expeditions into areas that need more detail.
+Follow-up rounds are purely reactive — they only happen when Round 1 findings reveal gaps that warrant deeper diving into specific dimensions or broader exploration of adjacent topics. Do NOT pre-plan multiple rounds; let the findings drive the need. Think of Round 1 as the comprehensive landscape map, with follow-up rounds as targeted expeditions into areas that need more detail.
 
 **ULTRA-SPECIFICITY MANDATE**: Level 3 demands granular, exhaustive detail on every fact that benefits from it — exact figures, dates, names, mechanisms, edge cases, historical context, technical specifics, and primary-source precision. Plan dedicated researchers for drilling into the ultra-specific dimensions of any finding where greater detail adds value.`;
   }
 }
 
 /**
- * Get complexity-specific guidance for the evaluator
+ * Get complexity-specific guidance for the evaluator.
+ *
+ * `researchRounds` is the number of rounds that can still DELEGATE — the caller's
+ * live, steering-extended budget minus the terminal synthesis-only iteration. It is
+ * a parameter rather than a table lookup because this text sits in the same prompt
+ * as the round-phase guidance, which is already phrased against that number: a
+ * hardcoded per-level constant here told a Level 3 router it had "3 rounds
+ * available" three lines above "Round 1 of 2", and put the two apart by a further
+ * round whenever steering extended the budget. Every round count the model is shown
+ * must come from the same source.
  */
-export function getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3): string {
+export function getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3, researchRounds: number): string {
+  const rounds = Math.max(1, Math.floor(researchRounds));
+  // One line, correct in both directions. At a budget of one there is no follow-up to
+  // recommend and saying otherwise invites the model to defer to a round it will never
+  // get; above one, the encouragement to use the budget is the point.
+  const budgetLine = rounds === 1
+    ? 'This run has ONE research round, and it has already happened — there is no follow-up round to defer to, so decide on what is in front of you.'
+    : `This run has ${rounds} research rounds in total; lean toward using them rather than finishing early.`;
   if (complexity === 1) {
     return `**Level 1 (Normal)** - Thorough, well-rounded investigation with solid multi-source coverage.
 
@@ -84,14 +100,14 @@ export function getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3): string {
 - **SYNTHESIZE when**: You are confident the research is genuinely complete. This means multiple angles covered with substantial findings across all major topics, diverse sources cited throughout, and no significant gaps in coverage.
 - **DELEGATE when**: ANY gaps remain in major topics, insufficient source diversity, missing details, or areas that need deeper exploration. Don't synthesize prematurely.
 
-**DEFAULT PATH: When in doubt, DELEGATE**. It is better to conduct additional research rounds than to synthesize with incomplete findings. Level 2 is designed for multi-round research. Each round adds depth and citation diversity — but do not delegate unnecessarily. Synthesize after Round 1 ONLY if the researcher produced comprehensive coverage of the topic with good source diversity. If Round 1 has any gaps, delegate Round 2. A third round is only warranted when Round 2 still leaves significant holes. Scale researcher count to match the gaps — focused gaps may only need 1 researcher, while broad gaps benefit from the full team.`;
+**DEFAULT PATH: When in doubt, DELEGATE**. It is better to conduct additional research rounds than to synthesize with incomplete findings. Level 2 is designed for multi-round research. Each round adds depth and citation diversity — but do not delegate unnecessarily. Synthesize after Round 1 ONLY if the researcher produced comprehensive coverage of the topic with good source diversity; if it has any gaps, delegate. ${budgetLine} Scale researcher count to match the gaps — focused gaps may only need 1 researcher, while broad gaps benefit from the full team.`;
   } else {
     return `**Level 3 (Ultra)** - Exhaustive, comprehensive deep-dive with extensive citations.
 
 - **SYNTHESIZE when**: You are confident the research is genuinely and exhaustively complete. This means exhaustively covered across ALL substantial avenues with multiple diverse sources per major topic, comprehensive citations throughout, and no meaningful gaps remain.
 - **DELEGATE when**: ANY meaningful gaps, nuanced angles, insufficient source diversity, inadequate citations, or areas needing deeper investigation remain.
 
-**DEFAULT PATH: When in doubt, DELEGATE**. It is better to conduct additional research rounds than to synthesize with incomplete findings. Level 3 has ${MAX_ROUNDS_LEVEL_3} rounds available. Be generous with follow-up delegation — lean toward using all available rounds. Each round adds breadth, depth, and citation diversity. Delegate for follow-up whenever remaining gaps or under-explored angles exist, even if progress has been good. Only synthesize when you have genuinely comprehensive coverage across all major areas with no meaningful gaps that another round would address.
+**DEFAULT PATH: When in doubt, DELEGATE**. It is better to conduct additional research rounds than to synthesize with incomplete findings. ${budgetLine} Be generous with follow-up delegation. Each round adds breadth, depth, and citation diversity. Delegate for follow-up whenever remaining gaps or under-explored angles exist, even if progress has been good. Only synthesize when you have genuinely comprehensive coverage across all major areas with no meaningful gaps that another round would address.
 
 **ULTRA-SPECIFICITY MANDATE**: For every fact, finding, or topic area where greater granularity adds value, delegate additional researchers to pursue it. This includes: exact figures and statistics, precise dates and timelines, technical mechanisms, named individuals and their specific contributions, primary-source verbatim data, edge cases, and any dimension where surface-level coverage would leave the reader with unanswered questions.`;
   }

package/src/core/service-initialization.ts

@@ -11,6 +11,7 @@ import { ServiceNames } from './service-interfaces.ts';
 import type { IStateManager } from './interfaces/state-manager-interfaces.ts';
 import { SchedulerService } from './scheduler-service.ts';
 import { PlanningService } from './planning-service.ts';
+import { ownsLiveEmbeddingServer } from '../infrastructure/embedding/embedding-factory.ts';
 import { logger } from '../logger.ts';
 
 /**
@@ -167,9 +168,24 @@ export async function disposeCoreServices(container: ServiceContainer = getServi
         // process that never touched embeddings; an unconditional clear here would
         // deregister ANOTHER process's live leader, leaving it an invisible leader
         // (its check treats a missing entry as benign) and forcing a duplicate GPU
-        // model election on the next caller.
-        await stateManager.clearEmbeddingServer({ pid: process.pid });
-        logger.debug('[ServiceInitialization] Cleared embedding server state before disposal');
+        // model election on the next caller. That unconditional form produced 80
+        // orphan windows totalling 147 hours before it was pid-scoped, the worst
+        // running four days.
+        //
+        // A pid is not enough on its own, though: it cannot separate "my leftover
+        // registration" from "my server, still listening". This clear runs BEFORE
+        // disposeAllServices, so our own server is typically still up — and this is
+        // the one clear in the tree issued on behalf of an instance the caller does
+        // not hold, so it is the only one that can delete a live registration it
+        // owns. When we hold the server, leave it: its own dispose clears the entry
+        // under a serverId compare-and-set, which is the correct owner-scoped
+        // teardown and runs moments later in disposeAllServices.
+        if (ownsLiveEmbeddingServer()) {
+          logger.debug('[ServiceInitialization] Skipping embedding-server state clear — this process owns the live server; its own dispose deregisters it');
+        } else {
+          await stateManager.clearEmbeddingServer({ pid: process.pid });
+          logger.debug('[ServiceInitialization] Cleared embedding server state before disposal');
+        }
       }
     } catch {
       // Non-fatal: embedding server state will be cleaned up on next startup via PID check

package/src/healthcheck/index.ts

@@ -7,7 +7,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { getConfig } from '../config.ts';
-import { isBrowserAvailable, resolveHeadlessMode } from '../infrastructure/browser/config.ts';
+import { isBrowserAvailable, resolveHeadlessMode, getHealthCheckBudgetMs } from '../infrastructure/browser/config.ts';
 import { runBrowserHealthCheck } from '../infrastructure/browser/task-execution-service.ts';
 import { getService, tryGetServiceContainerFromCtx, getServiceContainer, ServiceLifecycle } from '../core/service-registry.ts';
 import type { ServiceContainer } from '../core/service-registry.ts';
@@ -78,7 +78,16 @@ export function registerHealthChecks(registry: IHealthRegistryService, container
     // launch (camoufox download/spawn) can legitimately take minutes, so we never
     // go below that, but a user who raises HEALTH_CHECK_TIMEOUT_MS past it is
     // respected (same pattern as the KnowledgeStore check's Math.max floor).
-  }, { timeoutMs: Math.max(healthTimeoutMs, 150000), critical: true });
+    //
+    // This must ALSO never be less than getHealthCheckBudgetMs(): that is the
+    // deadline runBrowserHealthCheck's own scheduler call arms internally (derived
+    // from SEARCH_TIMEOUT_MS/SCRAPE_TIMEOUT_MS/BROWSER_TASK_TIMEOUT_MS so it always
+    // out-waits the longest a task can legitimately hold a worker slot). A fixed
+    // 150s floor here can be smaller than that derived budget at raised timeouts,
+    // which would abort this registry-level race before the inner check ever gets
+    // to return — reporting a merely busy pool as unhealthy, the exact failure
+    // class the derived budget exists to prevent, one call-frame further out.
+  }, { timeoutMs: Math.max(healthTimeoutMs, 150000, getHealthCheckBudgetMs(config)), critical: true });
 
   // Register Knowledge Store Check — NON-critical: the store is the optional cache
   // research must run without (see the darwin-x64 comment below). A failure here

package/src/index.ts

@@ -558,9 +558,10 @@ export default async function (pi: ExtensionAPI) {
     // the executor (deep) and quick orchestrator inject "ADDITIONAL USER GUIDANCE"/
     // "ADDITIONAL CONSIDERATIONS" into the researcher system prompt themselves.
     // Appending the same messages again here delivered every steering message
-    // TWICE to every researcher — return the prompt untouched. (The coordinator/
-    // evaluator never pass through this hook at all: they run via completeSimple,
-    // not an agent session, and get steering from planning-service directly.)
+    // TWICE to every researcher — return the prompt untouched. (The coordinator and
+    // the research lead never pass through this hook at all: they run via
+    // completeSimple, not an agent session, and get steering from planning-service
+    // directly.)
     const isResearcher = event.systemPrompt?.includes('RESEARCHER_AGENT_MARKER');
     if (isResearcher) {
       return { systemPrompt: event.systemPrompt };

package/src/infrastructure/browser/browser-client.ts

@@ -8,20 +8,21 @@
 import * as http from 'node:http';
 import type { Config } from '../../config.ts';
 import { getConfig } from '../../config.ts';
+
 import type { SearchResult } from '../../web-research/types.ts';
-import type { IScheduler } from '../../core/interfaces/scheduler-interfaces.ts';
+import type { IScheduler, TaskDispatchListener } from '../../core/interfaces/scheduler-interfaces.ts';
 import { logger } from '../../logger.ts';
 import { errorTracker } from '../../utils/error-tracker.ts';
 import { redactSecrets } from '../../utils/log-utils.ts';
 import { Utf8Body } from '../../utils/http-body.ts';
 import { getClientAgent } from './client-agent.ts';
+import { getHealthCheckBudgetMs } from './config.ts';
 import type { NodeError } from '../../types/index.ts';
 
 /**
- * Client-side patience margin on top of the leader's own task budget. The leader
- * already bounds each task (nav budget + queue-wait margin) and answers with the
- * more informative in-band timeout; the follower only needs headroom for the HTTP
- * hop and leader-side dispatch, so its own timer never answers first.
+ * Client-side patience margin on top of a leader budget that bounds the WHOLE
+ * call (only the healthcheck does, now). The follower needs headroom for the HTTP
+ * hop, so its own timer never answers first.
  */
 const CLIENT_PATIENCE_MARGIN_MS = 15_000;
 
@@ -34,41 +35,65 @@ const CLIENT_PATIENCE_MARGIN_MS = 15_000;
  */
 const CLIENT_TIMEOUT_CAP_MS = 300_000;
 
-/**
- * Mirror of the leader's fixed healthcheck budget in
- * BrowserTaskScheduler.runHealthCheck (45s probe deadline + 60s queue-wait
- * margin) — not config-derived there either.
- */
-const HEALTHCHECK_LEADER_BUDGET_MS = 45_000 + 60_000;
+
+/** Fraction of the owning caller's budget at which the wedge detector fires, so the
+ *  failure is reported and retriable inside the life of whatever asked for it. */
+const OWNER_BUDGET_FRACTION = 0.8;
 
 /**
- * Per-operation follower timeout: the leader's own budget for that task kind
- * plus a patience margin, bounded by an absolute cap.
+ * Per-operation follower timeout.
+ *
+ * The rule this used to state — "the follower is at least as patient as the leader" —
+ * is no longer the rule, and the change was deliberate; it is written out here because
+ * it is the obvious thing to reach for and it is wrong for two of the three cases
+ * below. What it replaced was worse still: a flat 60s that undercut the leader's
+ * healthcheck budget (105s) and its config-driven search/scrape budgets (130s+ within
+ * schema bounds), and whose message matches isTaskTimeoutError, so the retry gates
+ * skipped it — long tasks failed client-side, unretried, while the leader was still
+ * working on them.
+ *
+ * Search and scrape do not derive from the leader's TASK budget. That budget bounds
+ * EXECUTION only — it is armed when the queue dispatches, not when the request
+ * lands — so leader turnaround is queue wait plus that budget, and no value derived
+ * from it alone can out-wait it. Deriving one anyway is how a follower came to
+ * abandon requests the leader was still queueing, the same defect the leader-side
+ * deadline had. This timer is a detector for a leader that is listening but no
+ * longer answering; work waits, and is not discarded because the pool was busy.
+ *
+ * It is derived from the budget of whatever OWNS the call instead, because a
+ * detector that fires after its caller is already dead detects nothing. The flat
+ * 300s cap was exactly that: RESEARCHER_TIMEOUT_MS defaults to 300s and its schema
+ * minimum is 180s, so the researcher holding the request was always killed first
+ * and the user got a bare researcher timeout with nothing said about the browser
+ * leader — where before they at least got a request-timeout they could classify
+ * and retry. Firing at a fraction of the owner's budget leaves room for the
+ * failure to be reported and retried within the life of the thing that asked.
  *
- * Invariant: the follower is at least as patient as the leader. The old flat 60s
- * undercut the leader's healthcheck budget (105s) and config-driven search/scrape
- * budgets (up to 130s+ within schema bounds), and the client-timeout text matches
- * isTaskTimeoutError, so retry gates skipped it — long tasks failed client-side,
- * unretried, while the leader was still working on them.
+ * The healthcheck keeps a budget-derived value: its leader side bounds the WHOLE call,
+ * wait included — the probe's wait timer rejects rather than queueing indefinitely — so
+ * a liveness probe stays as impatient as a liveness probe should be. (It used to be
+ * described as answering "healthy, saturated" instead of failing; that branch was
+ * unreachable and has been removed. The bound is what matters here, not the verdict.)
+ * Even there the old invariant is only conditional: at the schema's extreme settings
+ * the derived leader budget exceeds the absolute cap, and the cap wins. That is the
+ * intended order — five minutes is already far past the point where a liveness probe
+ * tells anyone anything, whatever the leader is still doing.
  */
 export function resolveClientRequestTimeoutMs(operation: string, config?: Config): number {
-    const cfg = config ?? getConfig();
-    let leaderBudgetMs: number;
     switch (operation) {
         case 'search':
-            // BrowserTaskScheduler.runSearch: SEARCH_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_MS.
-            leaderBudgetMs = cfg.SEARCH_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS;
-            break;
-        case 'browser-task':
-            // BrowserTaskScheduler.runScrape: SCRAPE_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_MS.
-            leaderBudgetMs = cfg.SCRAPE_TIMEOUT_MS + cfg.BROWSER_TASK_TIMEOUT_MS;
-            break;
+        case 'browser-task': {
+            const ownerBudgetMs = (config ?? getConfig()).RESEARCHER_TIMEOUT_MS;
+            return Math.min(CLIENT_TIMEOUT_CAP_MS, Math.floor(ownerBudgetMs * OWNER_BUDGET_FRACTION));
+        }
         default:
-            // healthcheck, plus any future/unknown path: the largest fixed budget.
-            leaderBudgetMs = HEALTHCHECK_LEADER_BUDGET_MS;
-            break;
+            // healthcheck, plus any future/unknown path: the leader's own budget plus a
+            // margin. Read from the SAME function the leader reads, not from a local
+            // copy of the constant — the two were separate literals and would have
+            // drifted the moment either moved, leaving the follower less patient than
+            // the leader it is waiting on.
+            return Math.min(CLIENT_TIMEOUT_CAP_MS, getHealthCheckBudgetMs(config) + CLIENT_PATIENCE_MARGIN_MS);
     }
-    return Math.min(CLIENT_TIMEOUT_CAP_MS, leaderBudgetMs + CLIENT_PATIENCE_MARGIN_MS);
 }
 
 /**
@@ -99,7 +124,7 @@ export class BrowserClient implements IScheduler {
 
         return new Promise((resolve, reject) => {
             const agent = getClientAgent();
-            // Config-derived per task kind: leader budget + margin, capped.
+            // Wedge detector for search/scrape; leader budget + margin for the healthcheck.
             const timeoutMs = resolveClientRequestTimeoutMs(operation, config);
             let resolved = false;
             const controller = new AbortController();
@@ -269,11 +294,20 @@ export class BrowserClient implements IScheduler {
         });
     }
 
-    async runSearch(query: string, config?: Config, signal?: AbortSignal): Promise<SearchResult[]> {
+    /**
+     * `onTaskEvent` is deliberately not invoked here. A follower sees only the
+     * leader's final reply, never the moment the leader's queue hands the task to
+     * a worker, so it has nothing truthful to report. Calling it on send would
+     * arm the caller's guard against queue wait — precisely the bug being fixed —
+     * so the caller's guard stays disarmed and this class bounds the call itself
+     * (see resolveClientRequestTimeoutMs).
+     */
+    async runSearch(query: string, config?: Config, signal?: AbortSignal, _onTaskEvent?: TaskDispatchListener): Promise<SearchResult[]> {
         return this.request('/search', { query }, signal, config);
     }
 
-    async runScrape(url: string, config?: Config, signal?: AbortSignal): Promise<any> {
+    /** See runSearch on why `onTaskEvent` is not invoked. */
+    async runScrape(url: string, config?: Config, signal?: AbortSignal, _onTaskEvent?: TaskDispatchListener): Promise<any> {
         return this.request('/scrape', { url }, signal, config);
     }