@lincoln504/pi-research 1.1.2 → 1.3.0

package/src/orchestration/research-synthesis-service.ts

@@ -92,9 +92,12 @@ export class ResearchSynthesisService implements IService {
       this.sessions.set(sessionId, reports);
       return reports;
     }
-    // Evict the least-recently-used session when at capacity. Because every
-    // store/read touches its session to the end (above), the head is the genuinely
-    // stalest session, not merely the first-created — so an in-flight run is spared.
+    // Evict the least-recently-used session when at capacity. Every STORE touches
+    // its session to the end (above); reads deliberately do not (peekSessionReports
+    // exists so a stray read cannot create-and-evict). A run in its read-only
+    // synthesis phase therefore stops refreshing its recency — tolerable only
+    // because reaching MAX_SESSIONS at all needs ~200 uncleaned sessions in one
+    // process (run cap 3, sessions cleared after each run), i.e. a leaking host.
     if (this.sessions.size >= ResearchSynthesisService.MAX_SESSIONS) {
       const oldestKey = this.sessions.keys().next().value;
       if (oldestKey !== undefined) {
@@ -107,6 +110,25 @@ export class ResearchSynthesisService implements IService {
     return reports;
   }
 
+  /**
+   * Read a session's reports WITHOUT creating an entry for an unknown id.
+   *
+   * The read-only accessors below must not go through `getSessionReports`: that
+   * is create-on-read, so a query for an id we have never seen inserts an empty
+   * map — and at MAX_SESSIONS that insert evicts the current head. The LRU touch
+   * protects sessions that are read or written, but an in-flight run whose
+   * researchers are all still executing (reports stored early, nothing touched
+   * since) is exactly the stalest key, so a stray read for an unknown session
+   * could evict a live run's reports and silently shrink its final synthesis.
+   *
+   * Returns a shared empty map for unknown ids — callers here only read.
+   */
+  private peekSessionReports(sessionId: string): ReadonlyMap<string, string> {
+    return this.sessions.get(sessionId) ?? ResearchSynthesisService.EMPTY_REPORTS;
+  }
+
+  private static readonly EMPTY_REPORTS: ReadonlyMap<string, string> = new Map<string, string>();
+
   /**
    * Store a researcher report
    * @param sessionId - Session identifier
@@ -121,14 +143,14 @@ export class ResearchSynthesisService implements IService {
    * Get a report by ID
    */
   getReport(sessionId: string, id: string): string | undefined {
-    return this.getSessionReports(sessionId).get(id);
+    return this.peekSessionReports(sessionId).get(id);
   }
 
   /**
    * Get all reports
    */
   getAllReports(sessionId: string): Map<string, string> {
-    return new Map(this.getSessionReports(sessionId));
+    return new Map(this.peekSessionReports(sessionId));
   }
 
   /**
@@ -137,7 +159,7 @@ export class ResearchSynthesisService implements IService {
   getReportsForRound(sessionId: string, round: number): Map<string, string> {
     const roundReports = new Map<string, string>();
     const prefix = `${round}.`;
-    for (const [key, report] of this.getSessionReports(sessionId).entries()) {
+    for (const [key, report] of this.peekSessionReports(sessionId).entries()) {
       if (key.startsWith(prefix)) {
         roundReports.set(key, report);
       }
@@ -149,14 +171,14 @@ export class ResearchSynthesisService implements IService {
    * Get total number of reports
    */
   getReportCount(sessionId: string): number {
-    return this.getSessionReports(sessionId).size;
+    return this.peekSessionReports(sessionId).size;
   }
 
   /**
    * Check if there are any reports
    */
   hasReports(sessionId: string): boolean {
-    return this.getSessionReports(sessionId).size > 0;
+    return this.peekSessionReports(sessionId).size > 0;
   }
 
   /**
@@ -177,7 +199,7 @@ export class ResearchSynthesisService implements IService {
    * @returns Fallback synthesis string
    */
   buildFallbackSynthesis(sessionId: string, currentRound: number = 0): string {
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
     const reportCount = reports.size;
     const roundInfo = currentRound > 0 ? ` (up to Round ${currentRound})` : '';
     let synthesis = `Research Findings${roundInfo}\n\n`;
@@ -211,7 +233,7 @@ export class ResearchSynthesisService implements IService {
    * @returns Synthesis with guaranteed and verified CITED LINKS section
    */
   ensureCitedLinks(sessionId: string, synthesis: string): string {
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
 
     // Primary source: citations the researchers wrote into their reports. These are
     // the richest (they carry descriptions and source tags), so they win when present.
@@ -374,7 +396,7 @@ export class ResearchSynthesisService implements IService {
   extractAllCitations(sessionId: string): Array<{ url: string; description: string; source?: string }> {
     const seen = new Set<string>();
     const allCitations: Array<{ url: string; description: string; source?: string }> = [];
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
 
     for (const report of reports.values()) {
       const citations = parseCitations(report);

package/src/orchestration/researcher-executor.ts

@@ -19,7 +19,8 @@ import { getService, tryGetServiceContainerFromCtx } from '../core/service-regis
 import type { ResearchSessionService } from './research-session-service.ts';
 import { loadPrompt } from '../core/llm/prompts.ts';
 import { injectCurrentDate } from '../core/llm/inject-date.ts';
-import { recordResearcherFailure, getSteeringMessages } from './session-state.ts';
+import { recordResearcherFailure, getSteeringMessages, shouldStopResearch } from './session-state.ts';
+import { isAbortSentinel, boundSessionAbort } from './abort-utils.ts';
 import type { RunResearcherOptions } from './orchestration-types.ts';
 import { search } from '../web-research/search.ts';
 
@@ -46,6 +47,15 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
   
   const id = String(researcherConfig.id);
   const container = tryGetServiceContainerFromCtx(ctx);
+
+  // Fast-stop self-check: when the run's failure threshold trips, runResearchers'
+  // fast-stop path aborts only REGISTERED sessions — a researcher that is still
+  // acquiring initial links, sleeping between attempts, or rebuilding a session
+  // has none, and would otherwise sail on into a full LLM session + scrape burst
+  // AFTER the run already returned and released its run-cap slot. Every launch /
+  // retry boundary below consults this and exits quietly instead (the stop error
+  // is the run's outcome, not this researcher's failure).
+  const stopRequested = (): boolean => shouldStopResearch(sessionId, researchId, config.MAX_FAILED_RESEARCHERS);
   observer?.onResearcherStart?.(id, researcherConfig.name, researcherConfig.goal, round);
   metrics.increment('researchers_launched_total', 1, { mode: 'deep', complexity: String(complexity), round: String(round) });
 
@@ -81,12 +91,12 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
     const maxLinkAttempts = config.RESEARCHER_MAX_RETRIES + 1;
     for (let linkAttempt = 1; linkAttempt <= maxLinkAttempts && effectiveInitialLinks.length === 0; linkAttempt++) {
       if (linkAttempt > 1) {
-        if (signal?.aborted || container?.isDisposing) break;
+        if (signal?.aborted || container?.isDisposing || stopRequested()) break;
         const delay = Math.min(1000 * Math.pow(2, linkAttempt - 2), config.RESEARCHER_MAX_RETRY_DELAY_MS);
         logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results; retry ${linkAttempt - 1}/${config.RESEARCHER_MAX_RETRIES} after ${delay}ms`);
         await new Promise(r => setTimeout(r, delay));
       }
-      if (signal?.aborted || container?.isDisposing) break;
+      if (signal?.aborted || container?.isDisposing || stopRequested()) break;
       try {
         const queryResults = await search(retryQueries, config, signal, undefined, container);
         const urls = new Set<string>();
@@ -99,6 +109,17 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       }
     }
 
+    // A cancel/teardown/fast-stop lands here with zero links because the loop
+    // above breaks on abort/disposal/stop — that is a clean stop, not a "search
+    // produced nothing" researcher failure. Return quietly (mirrors the
+    // cancellation treatment in runResearchers) instead of recording a failure,
+    // bumping the skip metric, and painting a red failed slice with a bogus root
+    // cause on a plain cancel.
+    if (signal?.aborted || container?.isDisposing || stopRequested()) {
+      logger.debug(`[ResearcherExecutor] Researcher ${id} cancelled while acquiring initial links; skipping quietly.`);
+      return;
+    }
+
     if (effectiveInitialLinks.length === 0) {
       logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links after ${maxLinkAttempts} attempt(s); skipping.`);
       // Use the resolved sessionId (= piSessionId), NOT the raw ctx.sessionId: when
@@ -124,11 +145,44 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
   const deliveredSteeringIds = new Set<string>();
 
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    // Launch boundary: never build a session for a run that is already cancelled
+    // or fast-stopped. The abort sentinel keeps the wrapper's clean-cancel
+    // classification (runResearchers treats it exactly like the race's throw);
+    // the fast-stop exit is quiet — see stopRequested above.
+    if (signal?.aborted) throw new Error('Aborted');
+    if (stopRequested()) {
+      logger.debug(`[ResearcherExecutor] Researcher ${id} exiting before attempt ${attempt}: fast-stop threshold crossed.`);
+      return;
+    }
     if (attempt > 1) {
       const delay = Math.min(1000 * Math.pow(2, attempt - 2), config.RESEARCHER_MAX_RETRY_DELAY_MS);
       logger.warn(`[ResearcherExecutor] Researcher ${id} retry ${attempt - 1}/${config.RESEARCHER_MAX_RETRIES} after ${delay}ms`);
       observer?.onResearcherProgress?.(id, 'retry');
-      await new Promise(r => setTimeout(r, delay));
+      // Abortable: a cancel during this backoff must wake the sleep immediately —
+      // an inert setTimeout held the loop for up to RESEARCHER_MAX_RETRY_DELAY_MS
+      // after the cancel and then re-entered a full attempt (fresh session +
+      // billed prompt). Mirrors the stagger sleep in runResearchers.
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(() => {
+          if (signal) signal.removeEventListener('abort', onAbort);
+          resolve();
+        }, delay);
+        const onAbort = () => { clearTimeout(timer); resolve(); };
+        if (signal) {
+          if (signal.aborted) onAbort();
+          else signal.addEventListener('abort', onAbort, { once: true });
+        }
+      });
+      // Re-launch boundary after the sleep: a cancel, fast-stop, or container
+      // teardown landing DURING the backoff must not re-enter a full attempt —
+      // this is exactly the window the fast-stop path cannot reach, because
+      // abortAllSessions only aborts registered sessions and a between-attempts
+      // researcher has none.
+      if (signal?.aborted) throw new Error('Aborted');
+      if (stopRequested() || container?.isDisposing) {
+        logger.debug(`[ResearcherExecutor] Researcher ${id} exiting after backoff: fast-stop or container teardown.`);
+        return;
+      }
     }
 
     // Generate prompt for this attempt, incorporating ALL steering messages delivered so far
@@ -229,6 +283,32 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       throw registrationError;
     }
 
+    // Post-registration self-check: this session is now visible to
+    // abortAllSessions(), but that scan is point-in-time — a stop/cancel that
+    // landed anywhere between createResearcherSession() resolving and
+    // registerSession() actually running (the `await getService(...)` above can
+    // yield the event loop) would have missed this session entirely, and every
+    // other guard in this function only fires BEFORE session creation or
+    // BETWEEN attempts. Nothing between here and session.prompt() below awaits
+    // anything, so this single check closes the whole window: either it fires
+    // here, or the run is not stopping and prompt() is about to make this
+    // session's registration meaningful. Mirrors the top-of-loop launch
+    // boundary above exactly (signal throws, fast-stop returns quietly) —
+    // deliberately NOT container?.isDisposing: like that boundary, this is
+    // still attempt 1's launch, and a disposing container must let this
+    // attempt's own session.prompt() fail naturally into the catch block's
+    // disposal classification rather than being pre-empted here.
+    if (signal?.aborted || stopRequested()) {
+      logger.debug(`[ResearcherExecutor] Researcher ${id} exiting right after session creation: fast-stop/cancel landed before prompt() was reached.`);
+      await boundSessionAbort(
+        session.abort().catch((err) => logger.warn(`[ResearcherExecutor] Failed to abort researcher session ${id} on post-creation fast-stop:`, err)),
+        () => logger.warn(`[ResearcherExecutor] Researcher ${id} session abort did not settle within 10s; continuing cleanup`),
+      );
+      sessionService.unregisterSession(researchId, id);
+      if (signal?.aborted) throw new Error('Aborted');
+      return;
+    }
+
     let lastSteeringCheck = Date.now();
 
     // User-supplied observer callbacks (SDK consumers) are invoked from inside
@@ -399,13 +479,19 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
         logger.debug(`[ResearcherExecutor] Researcher ${id} salvage attempt failed:`, salvageErr);
       }
       
-      // Skip retries when the run is being torn down: an aborted signal, an explicit
-      // "Aborted" error, or the service container entering disposal (SIGTERM/quit
-      // mid-run, which throws "…during container disposal" from getService). Retrying
-      // during disposal is futile — services are being destroyed — and it relaunches
-      // search bursts into a WorkerPool that dispose() is simultaneously destroying,
-      // producing a storm of "Cannot execute a task on destroying pool" errors.
-      if (signal?.aborted || errMsg === 'Aborted' || errMsg.includes('during container disposal') || container?.isDisposing) {
+      // Skip retries when the run is being torn down: an aborted signal, the abort
+      // sentinel, or the service container entering disposal (SIGTERM/quit mid-run,
+      // which throws "…during container disposal" from getService). The sentinel has
+      // TWO forms — the race's bare 'Aborted' above AND the '<id>: Aborted' that
+      // ensureAssistantResponse throws when a fast-stop abortAllSessions() aborted
+      // this session externally (prompt() then resolves normally) — so match it via
+      // isAbortSentinel, not exact equality: the prefixed form used to slip past
+      // this guard and RETRY a researcher the fast-stop path had just aborted.
+      // Retrying during disposal is futile — services are being destroyed — and it
+      // relaunches search bursts into a WorkerPool that dispose() is simultaneously
+      // destroying, producing a storm of "Cannot execute a task on destroying pool"
+      // errors.
+      if (signal?.aborted || isAbortSentinel(errMsg) || errMsg.includes('during container disposal') || container?.isDisposing) {
         logger.debug(`[ResearcherExecutor] Researcher ${id} aborted or container disposing, skipping retries.`);
         break; // Break out of the attempt loop
       }
@@ -423,18 +509,12 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       // never settle — never let per-attempt cleanup hang the retry loop on it. The
       // retry builds a fresh session; the abandoned abort keeps draining in the
       // background and its session dies with the run's teardown.
-      await Promise.race([
+      await boundSessionAbort(
         session.abort().catch((err) => {
           logger.warn(`[ResearcherExecutor] Failed to abort researcher session ${id}:`, err);
         }),
-        new Promise<void>((resolve) => {
-          const t = setTimeout(() => {
-            logger.warn(`[ResearcherExecutor] Researcher ${id} session abort did not settle within 10s; continuing cleanup`);
-            resolve();
-          }, 10_000);
-          t.unref?.();
-        }),
-      ]);
+        () => logger.warn(`[ResearcherExecutor] Researcher ${id} session abort did not settle within 10s; continuing cleanup`),
+      );
       sessionService?.unregisterSession(researchId, id);
 
       // Restore the default thinking label now that the researcher is done.

package/src/orchestration/researcher.ts

@@ -23,6 +23,7 @@ import { logger } from '../logger.ts';
 
 import { resolveResearchModel } from '../core/llm/research-model-resolver.ts';
 import { getRuntimeForRegistry } from '../core/llm/model-registry-factory.ts';
+import { boundSessionAbort } from './abort-utils.ts';
 
 export interface CreateResearcherSessionOptions {
   cwd: string;
@@ -158,27 +159,45 @@ export async function createResearcherSession(options: CreateResearcherSessionOp
       thinkingLevel: config?.LLM_THINKING_LEVEL ?? 'off',
     });
 
-    // Customize the agent thinking label for researchers (e.g. "Researcher 1.1")
-    // so non-TUI surfaces can tell concurrent researchers apart. Skip this in the
-    // research TUI (mode === 'tui'): the panel already shows every researcher, and
-    // the host renders this label as dim/italic thinking text ABOVE the panel —
-    // stray output the panel was meant to replace. Use the researcherId passed by
-    // the caller (not regex on the prompt, since the ID is never templated in).
-    if (extensionCtx.mode !== 'tui' && extensionCtx.hasUI && typeof extensionCtx.ui.setHiddenThinkingLabel === 'function') {
-      extensionCtx.ui.setHiddenThinkingLabel(
-        researcherId ? `Researcher ${researcherId}` : undefined
-      );
+    // The session above is LIVE from here on, but the caller only receives it at
+    // the return below — a throw anywhere in this tail (a host UI callback, the
+    // validity check) would rethrow a session nobody owns, leaking it unaborted.
+    // Abort it best-effort (bounded: session.abort() awaits the in-flight call it
+    // cancels and may never settle) before rethrowing.
+    try {
+      // Customize the agent thinking label for researchers (e.g. "Researcher 1.1")
+      // so non-TUI surfaces can tell concurrent researchers apart. Skip this in the
+      // research TUI (mode === 'tui'): the panel already shows every researcher, and
+      // the host renders this label as dim/italic thinking text ABOVE the panel —
+      // stray output the panel was meant to replace. Use the researcherId passed by
+      // the caller (not regex on the prompt, since the ID is never templated in).
+      if (extensionCtx.mode !== 'tui' && extensionCtx.hasUI && typeof extensionCtx.ui.setHiddenThinkingLabel === 'function') {
+        extensionCtx.ui.setHiddenThinkingLabel(
+          researcherId ? `Researcher ${researcherId}` : undefined
+        );
+      }
+
+      logger.log(`[Researcher] Created session with model=${modelToUse?.id || 'unknown'}`);
+
+      if (!result || !result.session) {
+        throw new Error('Session creation returned invalid result');
+      }
+
+      sessionRef.session = result.session;
+
+      return { session: result.session, resolvedModel: modelToUse };
+    } catch (tailError) {
+      const session = result?.session;
+      if (session && typeof session.abort === 'function') {
+        await boundSessionAbort(
+          (async () => session.abort())().catch((abortErr) => {
+            logger.warn('[Researcher] Failed to abort never-returned session:', abortErr);
+          }),
+          () => logger.warn('[Researcher] Never-returned session abort did not settle within bound; continuing'),
+        );
+      }
+      throw tailError;
     }
-
-    logger.log(`[Researcher] Created session with model=${modelToUse?.id || 'unknown'}`);
-
-    if (!result || !result.session) {
-      throw new Error('Session creation returned invalid result');
-    }
-
-    sessionRef.session = result.session;
-
-    return { session: result.session, resolvedModel: modelToUse };
   } catch (error) {
     const errorMsg = error instanceof Error ? error.message : String(error);
     throw new Error(`Failed to create researcher session: ${errorMsg}`, {

package/src/orchestration/session-state.ts

@@ -520,6 +520,17 @@ export function endResearchSession(piSessionId: string | undefined, researchId:
   // but preserve steering messages if any remain (they might arrive between
   // the last research end and the next research start)
   if (state.order.length === 0 && state.panels.size === 0) {
+    // Drop steering messages this run already consumed ('active') — and any
+    // 'popped' remnants, which are likewise already resolved — before deciding
+    // whether to keep the session alive. Without this, a message the run that
+    // just ended already consumed stayed in the array and leaked into a later,
+    // unrelated run's steering (both getActiveSteeringMessages/getSteeringMessages
+    // reads and the before_agent_start injection gate), since nothing distinguishes
+    // "steering for THIS run" from "steering already applied to a finished run".
+    // Only messages still 'queued' (arrived in the gap, never attached to any run)
+    // are genuinely eligible for the gap-preservation this block performs.
+    state.steeringMessages = state.steeringMessages.filter(m => m.status === 'queued');
+
     // Only fully delete if there are no remaining steering messages
     const hasRemainingSteering = state.steeringMessages.length > 0;
     if (!hasRemainingSteering) {

package/src/sdk.ts

@@ -28,6 +28,9 @@ import type {
   ResearchOptions
 } from './core/interfaces/orchestration-interfaces.ts';
 import type { IPlanningService } from './core/interfaces/planning-interfaces.ts';
+import type { ResearchObserver, HeadlessObserverOptions } from './core/interfaces/observer-interfaces.ts';
+import type { ResearchPlan } from './core/interfaces/research-plan-types.ts';
+import { HeadlessObserver } from './orchestration/headless-observer.ts';
 import type { Model } from '@earendil-works/pi-ai';
 import { type ExtensionContext, ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { logger, createLogger, setLogger } from './logger.ts';
@@ -94,6 +97,13 @@ export interface ResearcherOutcome {
   failureReasons: Record<string, string>;
 }
 let _lastResearcherOutcome: ResearcherOutcome | null = null;
+// Monotonic SDK-lifetime counter, bumped by _doShutdown. A run left in flight across
+// shutdownResearchSDK() settles AFTER the shutdown wiped the `_last*` accessors and
+// cleared session metrics; its catch/finally would then repopulate them, so a
+// re-initialized SDK reported a phantom run from the previous lifetime. Each run
+// captures the generation at start and every post-run telemetry write is gated on it
+// still matching.
+let _sdkGeneration = 0;
 
 // Signal handler state — registered once, removed on clean shutdown.
 let _onSignal: ((signal: string) => void) | null = null;
@@ -489,6 +499,18 @@ export async function runDeepResearch(
   // here instead of vanishing into the never-read global tracker.
   const runTracker = new ErrorTracker();
 
+  // Stamp the run with the current shutdown generation: if shutdownResearchSDK()
+  // completes while this run is still in flight, _doShutdown bumps the generation
+  // and every telemetry write below is skipped — the shutdown wipe must win over
+  // an older-generation run settling late (see _sdkGeneration).
+  const runGeneration = _sdkGeneration;
+
+  // Planned-researcher count, captured DURING the run via the observer wrapper —
+  // it is unreadable from the planning service once runResearch() settles (the deep
+  // orchestrator clears that per-run state in its own finally first).
+  let plannedResearchers = 0;
+  const observer = wrapObserverForOutcomeCapture(options.observer, (count) => { plannedResearchers += count; });
+
   try {
     // Resolve the orchestrator INSIDE the try: getService() can throw (container
     // disposal race with shutdown, or an unregistered service), and if that throw
@@ -506,6 +528,9 @@ export async function runDeepResearch(
       depth: depth as ResearchDepth,
       complexity: complexity as 1 | 2 | 3,
       initialLinks: options.initialLinks,
+      // The caller's observer, wrapped so the SDK captures the planned-researcher
+      // events for getLastResearcherOutcome() (must land AFTER the options spread).
+      observer,
       // Forward the SDK's resolved config so initResearchSDK({ config }) overrides
       // actually reach the orchestrator and every downstream service. A per-call
       // options.config (if provided) takes precedence over the SDK-global config.
@@ -522,27 +547,40 @@ export async function runDeepResearch(
     // unbounded across calls (a long-lived SDK/benchmark process). runRegistry.observe() lands
     // it in this run's snapshot, matching the tool path's run-scoped emission.
     runRegistry.observe('research_manager_latency_ms', completedAt - researchStart, { depth: depthLabel, status: 'success', source: 'sdk' });
-    _lastRunSummary = {
-      runId: researchId, startedAt: researchStart, completedAt,
-      durationMs: completedAt - researchStart, status: 'success', snapshot: runRegistry.getSnapshot(),
-    };
-    metrics.recordRunSummary(_lastRunSummary);
-    _lastErrorReport = runTracker.getReport();
-    logRunErrorSummary(_lastErrorReport, depthLabel, 'success');
-    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
+    // Generation guard: skip every module-level telemetry write if a shutdown
+    // completed mid-run — the wipe must not be resurrected by a stale run.
+    if (runGeneration === _sdkGeneration) {
+      _lastRunSummary = {
+        runId: researchId, startedAt: researchStart, completedAt,
+        durationMs: completedAt - researchStart, status: 'success', snapshot: runRegistry.getSnapshot(),
+      };
+      metrics.recordRunSummary(_lastRunSummary);
+      _lastErrorReport = runTracker.getReport();
+      logRunErrorSummary(_lastErrorReport, depthLabel, 'success');
+      // Re-check the generation AFTER the await: the gate above was evaluated
+      // before it, so a shutdown completing during the capture would otherwise
+      // land this assignment after the wipe — a phantom outcome from a dead run.
+      const outcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot, plannedResearchers);
+      if (runGeneration === _sdkGeneration) _lastResearcherOutcome = outcome;
+    }
     return result;
   } catch (err) {
     const completedAt = Date.now();
     // Per-run scope (see the success path above) — avoids unbounded session-scope accumulation.
     runRegistry.observe('research_manager_latency_ms', completedAt - researchStart, { depth: depthLabel, status: 'error', source: 'sdk' });
-    _lastRunSummary = {
-      runId: researchId, startedAt: researchStart, completedAt,
-      durationMs: completedAt - researchStart, status: 'error', snapshot: runRegistry.getSnapshot(),
-    };
-    metrics.recordRunSummary(_lastRunSummary);
-    _lastErrorReport = runTracker.getReport();
-    logRunErrorSummary(_lastErrorReport, depthLabel, 'error');
-    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
+    // Generation guard — see the success path above.
+    if (runGeneration === _sdkGeneration) {
+      _lastRunSummary = {
+        runId: researchId, startedAt: researchStart, completedAt,
+        durationMs: completedAt - researchStart, status: 'error', snapshot: runRegistry.getSnapshot(),
+      };
+      metrics.recordRunSummary(_lastRunSummary);
+      _lastErrorReport = runTracker.getReport();
+      logRunErrorSummary(_lastErrorReport, depthLabel, 'error');
+      // Re-check after the await — see the success path above.
+      const outcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot, plannedResearchers);
+      if (runGeneration === _sdkGeneration) _lastResearcherOutcome = outcome;
+    }
     throw err;
   } finally {
     // Free the per-run PiSessionState that shouldStopResearch()/getFailedResearchers()
@@ -603,16 +641,73 @@ function logRunErrorSummary(report: ErrorReport | null, depthLabel: string, stat
   logger.warn(`[SDK] run ${status} with ${report.totalErrors} tracked error(s) across ${report.uniquePatterns} pattern(s) [${depthLabel}]${top ? ` — top: ${top}` : ''}`);
 }
 
+/**
+ * Wrap the caller's observer so the SDK sees the planned-researcher events the deep
+ * orchestrator emits DURING the run. The count cannot be read back afterwards: the
+ * orchestrator's own finally runs cleanupResearchServices → clearPlanningState(researchId)
+ * BEFORE runResearch() resolves for the SDK, so a post-run getTotalResearchersPlanned()
+ * always sees 0. onPlanningSuccess (round 1) and onEvaluationDecision('delegate', …)
+ * (later rounds) fire at exactly the points the orchestrator increments that counter —
+ * it suppresses the delegate decision for a round-cap delegation it discards, so the
+ * captured total only counts researchers that were actually going to run.
+ *
+ * An { onProgress } options bag is normalized into a HeadlessObserver HERE rather than
+ * left to the orchestrator (which uses the same shape check): if the orchestrator wrapped
+ * the bag itself, the planning events would dispatch on ITS HeadlessObserver instance and
+ * never reach this capture layer. Mirrors makeSafeObserver's empty-target Proxy so a
+ * frozen caller observer can never trip the Proxy own-property invariant.
+ */
+function wrapObserverForOutcomeCapture(
+  observer: ResearchObserver | HeadlessObserverOptions | undefined,
+  onPlanned: (count: number) => void,
+): ResearchObserver {
+  const base: ResearchObserver | undefined =
+    observer && typeof (observer as HeadlessObserverOptions).onProgress === 'function' && !(observer instanceof HeadlessObserver)
+      ? new HeadlessObserver(observer as HeadlessObserverOptions)
+      : (observer as ResearchObserver | undefined);
+
+  return new Proxy({} as ResearchObserver, {
+    get(_target, prop) {
+      if (prop === 'onPlanningSuccess') {
+        return (plan: ResearchPlan) => {
+          onPlanned(plan?.researchers?.length ?? 0);
+          base?.onPlanningSuccess?.(plan);
+        };
+      }
+      if (prop === 'onEvaluationDecision') {
+        return (action: 'synthesize' | 'delegate', plan?: ResearchPlan, round?: number) => {
+          if (action === 'delegate') onPlanned(plan?.researchers?.length ?? 0);
+          base?.onEvaluationDecision?.(action, plan, round);
+        };
+      }
+      if (!base) return undefined;
+      const value = Reflect.get(base, prop, base);
+      return typeof value === 'function' ? (value as (...args: unknown[]) => unknown).bind(base) : value;
+    },
+    has(_target, prop) {
+      if (prop === 'onPlanningSuccess' || prop === 'onEvaluationDecision') return true;
+      return base ? Reflect.has(base, prop) : false;
+    },
+  });
+}
+
 /**
  * Capture how many researchers were planned/launched/failed for this run, BEFORE
  * the caller's `finally` block frees the PiSessionState (endResearchSession) that
  * getFailedResearchers()/getResearcherFailureReasons() read from. Best-effort:
  * this is instrumentation only and must never affect the run's own result.
  */
-async function captureResearcherOutcome(sessionId: string, researchId: string, snapshot: IMetricsSnapshot): Promise<ResearcherOutcome | null> {
+async function captureResearcherOutcome(sessionId: string, researchId: string, snapshot: IMetricsSnapshot, plannedFromObserver: number): Promise<ResearcherOutcome | null> {
   try {
-    const planningService = await getService<IPlanningService>(ServiceNames.PLANNING, undefined, globalContainer!);
-    const planned = planningService.getTotalResearchersPlanned(researchId);
+    // Deep runs: the observer-captured count is authoritative — the orchestrator's
+    // finally already cleared the planning service's per-run entry by the time the SDK
+    // regains control (see wrapObserverForOutcomeCapture). The service read stays as a
+    // fallback for any path that never emits the planning events.
+    let planned = plannedFromObserver;
+    if (planned === 0) {
+      const planningService = await getService<IPlanningService>(ServiceNames.PLANNING, undefined, globalContainer!);
+      planned = planningService.getTotalResearchersPlanned(researchId);
+    }
     const launched = extractRunStats(snapshot)?.researchersLaunched ?? 0;
     const failed = getFailedResearchers(sessionId, researchId);
     return {
@@ -825,6 +920,14 @@ export async function shutdownResearchSDK(): Promise<void> {
 async function _doShutdown(): Promise<void> {
   logger.log('[SDK] Shutting down Research SDK...');
 
+  // Invalidate the pending telemetry writes of any run still in flight FIRST —
+  // before runCleanup and the other long awaits below. The invariant: a run
+  // settling at ANY point after shutdown begins fails the generation gate. Bumping
+  // at the end instead left the whole teardown (cleanup, clearSession, service
+  // disposal) as a window in which a settling run passed the gate and wrote a
+  // phantom run-summary into the just-cleared session metrics.
+  _sdkGeneration++;
+
   const errors: Error[] = [];
 
   try {
@@ -886,6 +989,9 @@ async function _doShutdown(): Promise<void> {
   _lastRunSummary = null;
   _lastErrorReport = null;
   _lastResearcherOutcome = null;
+  // (No generation bump here — it happened at the TOP of this function, so any
+  // run settling during the teardown above already failed the gate and could not
+  // repopulate the `_last*` accessors or session metrics being wiped.)
   // The module-level config cache survives the globals above. Without this, a
   // shutdown → env/config-file change → re-init cycle in one process silently
   // reuses the first init's config. (The CLI/skill are unaffected — they pass

package/src/security/cisa-kev.ts

@@ -10,6 +10,7 @@ import type { Vulnerability, CisaKevResult } from './types.ts';
 import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError, MAX_BULK_JSON_BODY_BYTES } from '../utils/http-body.ts';
 
 const CISA_KEV_URL = 'https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json';
 
@@ -183,10 +184,16 @@ export async function searchCisaKev(
 
     let data: unknown;
     try {
-      data = await response.json();
-    } catch {
+      // The KEV feed is the whole catalogue in one document — legitimately tens of
+      // megabytes and growing — so it reads against the bulk cap, not the default.
+      data = await readJsonCapped(response, MAX_BULK_JSON_BODY_BYTES);
+    } catch (err) {
+      if (err instanceof BodyTooLargeError) {
+        metrics.increment('cisa_kev_errors_total', 1, { error_type: 'body_too_large' });
+        throw err;
+      }
       metrics.increment('cisa_kev_errors_total', 1, { error_type: 'malformed_json' });
-      throw new Error('CISA KEV feed returned a malformed JSON response.');
+      throw new Error('CISA KEV feed returned a malformed JSON response.', { cause: err });
     }
 
     // CISA KEV format is an array of vulnerability objects or nested in a response object