@lincoln504/pi-research 1.1.2 → 1.3.0

package/src/knowledge/writer-queue.ts

@@ -16,7 +16,7 @@ interface WriterQueueOptions {
   store: {
     isStoreClosed?: () => boolean;
     findByUrl: (url: string) => Promise<StoreDocument[]>;
-    deleteByUrlAndType: (url: string, type: string) => Promise<void>;
+    deleteByUrlAndType: (url: string, type: string, olderThan?: number) => Promise<void>;
     addDocuments: (docs: StoreDocument[]) => Promise<void>;
   };
   chunker: Chunker | null;
@@ -73,50 +73,58 @@ export class WriterQueue implements IWriterQueue {
     if (this.processing) return;
     this.processing = true;
 
-    while (this.queue.length > 0) {
-      const item = this.queue.shift()!;
-      try {
-        // FIX (#2): Chain per-URL to serialize concurrent ingests of the same URL.
-        // process() already runs sequentially, so we chain only for the race case
-        // where two enqueue() calls trigger concurrent process() calls.
-        const urlKey = normalizeUrl(item.url);
-        const prev = this.inflightByUrl.get(urlKey) ?? Promise.resolve();
-        const inflight = prev.then(() => this._ingestInner(item));
-        this.inflightByUrl.set(urlKey, inflight);
+    // try/finally around the whole drain: the latch and the drain notification used
+    // to sit on the normal exit path only. Anything escaping the loop — including
+    // from the catch block below, which itself awaits and logs — left `processing`
+    // stuck true forever: no further item would ever be ingested, drain() would never
+    // resolve, and dispose() would burn its full timeout on every later shutdown.
+    // enqueue() swallows this promise's rejection, so the wedge was silent.
+    try {
+      while (this.queue.length > 0) {
+        const item = this.queue.shift()!;
         try {
-          await inflight;
-        } finally {
-          if (this.inflightByUrl.get(urlKey) === inflight) {
-            this.inflightByUrl.delete(urlKey);
-          }
-        }
-      } catch (err) {
-        if (isEmbedderUnreachable(err)) {
-          logger.warn(`[writer-queue] Embedder unreachable for ${item.url}, retrying once after 2s...`);
-          await new Promise(r => setTimeout(r, 2000));
+          // FIX (#2): Chain per-URL to serialize concurrent ingests of the same URL.
+          // process() already runs sequentially, so we chain only for the race case
+          // where two enqueue() calls trigger concurrent process() calls.
+          const urlKey = normalizeUrl(item.url);
+          const prev = this.inflightByUrl.get(urlKey) ?? Promise.resolve();
+          const inflight = prev.then(() => this._ingestInner(item));
+          this.inflightByUrl.set(urlKey, inflight);
           try {
-            await this.ingest(item);
-          } catch (retryErr) {
-            logger.error(`[writer-queue] Retry failed for ${item.url}, dropping:`, retryErr);
-            metrics.increment('knowledge_ingest_dropped_total', 1, { reason: 'embedder_unreachable' });
+            await inflight;
+          } finally {
+            if (this.inflightByUrl.get(urlKey) === inflight) {
+              this.inflightByUrl.delete(urlKey);
+            }
+          }
+        } catch (err) {
+          if (isEmbedderUnreachable(err)) {
+            logger.warn(`[writer-queue] Embedder unreachable for ${item.url}, retrying once after 2s...`);
+            await new Promise(r => setTimeout(r, 2000));
+            try {
+              await this.ingest(item);
+            } catch (retryErr) {
+              logger.error(`[writer-queue] Retry failed for ${item.url}, dropping:`, retryErr);
+              metrics.increment('knowledge_ingest_dropped_total', 1, { reason: 'embedder_unreachable' });
+            }
+          } else if (isNoSpace(err)) {
+            logger.error(`[writer-queue] ENOSPC: disk full — dropping ${item.url}. Free up disk space to resume knowledge ingestion.`);
+            metrics.increment('knowledge_ingest_dropped_total', 1, { reason: 'enospc' });
+          } else {
+            logger.error(`[writer-queue] Failed to ingest ${item.url}:`, err);
+            metrics.increment('knowledge_ingest_dropped_total', 1, { reason: 'ingest_error' });
           }
-        } else if (isNoSpace(err)) {
-          logger.error(`[writer-queue] ENOSPC: disk full — dropping ${item.url}. Free up disk space to resume knowledge ingestion.`);
-          metrics.increment('knowledge_ingest_dropped_total', 1, { reason: 'enospc' });
-        } else {
-          logger.error(`[writer-queue] Failed to ingest ${item.url}:`, err);
-          metrics.increment('knowledge_ingest_dropped_total', 1, { reason: 'ingest_error' });
         }
       }
-    }
+    } finally {
+      this.processing = false;
 
-    this.processing = false;
-    
-    // Notify all drain callers
-    const resolvers = [...this.drainResolvers];
-    this.drainResolvers = [];
-    for (const resolve of resolvers) {
-      resolve();
+      // Notify all drain callers
+      const resolvers = [...this.drainResolvers];
+      this.drainResolvers = [];
+      for (const resolve of resolvers) {
+        resolve();
+      }
     }
   }
 
@@ -172,15 +180,28 @@ export class WriterQueue implements IWriterQueue {
     // Dedup: check if we already have this exact URL+type with identical content.
     // findByUrl applies scope filtering, so this only dedupes within the
     // current project's visible scope (local workspace + global entries).
+    // Compared against the NEWEST generation, not row order: after a failed prune
+    // two generations coexist and findByUrl's order is arbitrary — matching the
+    // OLD generation's hash would skip the refresh with the duplicates in place.
     const existing = await this.options.store.findByUrl(normalizedUrl);
     const sameType = existing.filter(c => c.metadata['ingestionType'] === incomingType);
-    if (sameType.length > 0 && sameType[0]!.metadata['contentHash'] === hash) {
-      logger.log(`[writer-queue] Skipping ${normalizedUrl} (${incomingType}) — content unchanged.`);
-      return;
-    }
-
     if (sameType.length > 0) {
-      await this.options.store.deleteByUrlAndType(normalizedUrl, incomingType);
+      const newestTs = Math.max(...sameType.map(d => Number(d.timestamp) || 0));
+      const newest = sameType.find(d => (Number(d.timestamp) || 0) === newestTs)!;
+      if (newest.metadata['contentHash'] === hash) {
+        // Content unchanged vs the current generation — but a prior failed prune
+        // may still have left older generations behind, and with stable content
+        // this skip is the only code that ever looks at this URL again. Collect
+        // them now instead of preserving the duplicates forever.
+        if (sameType.some(d => (Number(d.timestamp) || 0) < newestTs)) {
+          await this.options.store.deleteByUrlAndType(normalizedUrl, incomingType, newestTs).catch((err) => {
+            logger.warn(`[writer-queue] Sweeping superseded duplicates for ${normalizedUrl} (${incomingType}) failed:`, err);
+            metrics.increment('knowledge_ingest_stale_prune_failed_total', 1);
+          });
+        }
+        logger.log(`[writer-queue] Skipping ${normalizedUrl} (${incomingType}) — content unchanged.`);
+        return;
+      }
     }
 
     const rawChunks = this.options.chunker
@@ -189,6 +210,10 @@ export class WriterQueue implements IWriterQueue {
 
     if (rawChunks.length === 0) return;
 
+    // Single timestamp shared by every chunk of this write: it is both the row's
+    // recency value and the boundary used to prune the rows this write replaces.
+    const insertedAt = Date.now();
+
     const docs: StoreDocument[] = rawChunks.map((chunk, i) => ({
       url: normalizedUrl,
       text: chunk.text,
@@ -203,10 +228,27 @@ export class WriterQueue implements IWriterQueue {
         chunkIndex: i,
         totalChunks: rawChunks.length,
       },
-      timestamp: Date.now(),
+      timestamp: insertedAt,
     }));
 
+    // Write the replacement BEFORE removing what it replaces. Deleting first made
+    // the refresh destructive: addDocuments can fail (embedder unreachable, ENOSPC,
+    // store closing mid-write) and the perfectly good previous entry was already
+    // gone, so a failed refresh left the URL with no entry at all rather than a
+    // stale one. In this order a failure leaves the old entry intact and the retry
+    // simply tries again.
     await this.options.store.addDocuments(docs);
+
+    if (sameType.length > 0) {
+      // Prune only rows older than this write, so the delete cannot take the rows
+      // just inserted. Failing here leaves duplicate chunks — visible but harmless,
+      // and cleaned up by the next successful ingest of this URL — which is a far
+      // better outcome than throwing away a write that already succeeded.
+      await this.options.store.deleteByUrlAndType(normalizedUrl, incomingType, insertedAt).catch((err) => {
+        logger.warn(`[writer-queue] Replacement for ${normalizedUrl} (${incomingType}) is stored, but pruning the superseded chunks failed; duplicates remain until the next refresh:`, err);
+        metrics.increment('knowledge_ingest_stale_prune_failed_total', 1);
+      });
+    }
   }
 
   async drain(timeoutMs?: number): Promise<void> {

package/src/logger.ts

@@ -35,6 +35,7 @@ import {
   safeJsonStringify,
   formatArg,
   redactSecrets,
+  stripTerminalEscapes,
   type LogContext,
 } from './utils/log-utils.ts';
 import { LogRotation } from './utils/log-rotation.ts';
@@ -286,7 +287,10 @@ export class Logger implements ILogger {
       // escapes control chars on its own. CodeQL (js/log-injection) StringReplaceSanitizer
       // requires the replacement to be "" (empty string) — not ' ' — per its QL definition:
       //   replaces(s, "") and s.regexpMatch("\\n")
-      const msg = message.replace(/[\r\n]/g, '');
+      // redactSecrets removed only the colour/style CSI subset, so private-mode
+      // CSI (\x1b[?25l), OSC retitling, and DCS would still reach the terminal
+      // here — stripTerminalEscapes drops those plus residual control bytes.
+      const msg = stripTerminalEscapes(message.replace(/[\r\n]/g, ''));
       const rawSid = this.sessionId ?? '';
       const sid = rawSid.replace(/[\r\n]/g, '');
       const prefix = sid ? `[${sid}] ` : '';

package/src/observers/research-observer-impl.ts

@@ -26,6 +26,14 @@ import {
   clearCompletedResearchers,
 } from '../tui/research-panel.ts';
 
+/**
+ * Slice id for the run-queued placeholder box. Shown by onRunQueued while the
+ * run waits for a machine-wide run-cap slot (before ANY other lifecycle event)
+ * and removed by onStart once a slot is acquired — both quick and deep fire
+ * onStart before doing real work. Stable-id keyed like 'coord'/'eval'.
+ */
+const RUN_QUEUED_SLICE_ID = 'run-queued';
+
 export interface ObserverContext {
   panelState: ResearchPanelState;
   debouncedRefresh: () => void;
@@ -71,6 +79,9 @@ export function createResearchObserver(
 
   return {
     onStart: (query, complexity) => {
+      // A run-cap slot was acquired and the run is actually starting — drop the
+      // queued-run placeholder (no-op when the run never queued).
+      removeSlice(panelState, RUN_QUEUED_SLICE_ID);
       if (complexity === 0) {
         // Truncate at a CODEPOINT boundary (Array.from iterates codepoints), not a
         // code-unit index: query.slice(0, 20) can split a surrogate pair (emoji,
@@ -91,6 +102,26 @@ export function createResearchObserver(
       debouncedRefresh();
     },
 
+    onRunQueued: (slots, maxWaitMs) => {
+      // Fired before any other lifecycle event when every machine-wide run slot
+      // is held and this run is about to queue (for up to maxWaitMs). Without a
+      // visible notice the whole wait renders as an empty panel — the exact
+      // "looks like a hang" condition the callback exists to prevent. Surface it
+      // through the same slice/status channel every other phase uses; the
+      // non-numeric label routes updateSliceStatus to a persistent status (no
+      // timed pop), and onStart removes the placeholder once the run begins.
+      const waitMins = Math.max(1, Math.ceil(maxWaitMs / 60_000));
+      addSlice(panelState, RUN_QUEUED_SLICE_ID, 'queued', false);
+      activateSlice(panelState, RUN_QUEUED_SLICE_ID);
+      updateSliceStatus(
+        panelState,
+        RUN_QUEUED_SLICE_ID,
+        `waiting for a free run slot (all ${slots} in use, up to ${waitMins}m)`,
+        debouncedRefresh,
+      );
+      debouncedRefresh();
+    },
+
     onPlanningStart: (attempt) => {
       if (attempt === 1) {
         addSlice(panelState, 'coord', `coordinator`, false);

package/src/orchestration/abort-utils.ts

@@ -0,0 +1,60 @@
+/**
+ * Abort/Teardown Utilities
+ *
+ * Shared by the orchestration layer for two teardown concerns:
+ * - Classifying the "Aborted" sentinel consistently everywhere it is consumed.
+ * - Bounding waits on session aborts, which may never settle.
+ */
+
+/**
+ * Upper bound for awaiting a session abort during cleanup/teardown.
+ * session.abort() awaits the very in-flight request it is cancelling, which can
+ * be wedged (e.g. a provider retry loop against an exhausted quota) and never
+ * settle — so no teardown path may await it unbounded.
+ */
+export const SESSION_ABORT_SETTLE_TIMEOUT_MS = 10_000;
+
+/**
+ * True when an error message is the abort sentinel. Two forms exist and must
+ * classify identically:
+ * - bare 'Aborted' — thrown by the orchestrators' local abort races, and
+ * - '<researcher-id>: Aborted' — thrown by ensureAssistantResponse
+ *   (text-utils.ts) when an externally-aborted pi session resolves prompt()
+ *   normally with no salvageable text (the fast-stop abortAllSessions path).
+ * An exact-equality check misses the prefixed form, which made the executor
+ * RETRY a researcher the fast-stop path had just aborted: fresh session, fresh
+ * search/scrape burst, sessions re-registered after cleanup already ran.
+ */
+export function isAbortSentinel(message: string): boolean {
+  return /(^|: )Aborted$/.test(message);
+}
+
+/**
+ * Await an abort (which must never reject — callers attach their own .catch)
+ * for at most `timeoutMs`, then proceed with teardown. When the bound fires,
+ * `onTimeout` runs (callers log there); the abandoned abort keeps draining in
+ * the background and dies with the run's teardown. The timer never keeps the
+ * process alive, and is cleared when the abort settles first so it cannot fire
+ * a stale onTimeout later.
+ */
+export async function boundSessionAbort(
+  abort: Promise<void>,
+  onTimeout: () => void,
+  timeoutMs: number = SESSION_ABORT_SETTLE_TIMEOUT_MS,
+): Promise<void> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    await Promise.race([
+      abort,
+      new Promise<void>((resolve) => {
+        timer = setTimeout(() => {
+          onTimeout();
+          resolve();
+        }, timeoutMs);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/orchestration/deep-research-orchestrator.ts

@@ -7,10 +7,9 @@
 import type { ExtensionContext, AgentToolResult } from '@earendil-works/pi-coding-agent';
 import { type Model } from '@earendil-works/pi-ai';
 import { logger } from '../logger.ts';
-import { safeUnref } from '../utils/safe-unref.ts';
 import { metrics } from '../utils/metrics.ts';
 import { getSteeringMessages, consumeQueuedMessages, getActiveSteeringMessages, getFailedResearchers, getResearcherFailureReasons } from './session-state.ts';
-import { MAX_EXTRA_ROUNDS_WITH_STEERING } from '../constants.ts';
+import { MAX_EXTRA_ROUNDS_WITH_STEERING, resolveExcludedTools } from '../constants.ts';
 import {
   getMaxRounds,
 } from '../core/planning-utils.ts';
@@ -218,6 +217,17 @@ export class DeepResearchOrchestrator {
                 excludeTools: this.options.excludeTools,
                 steeringMessages: steeringTexts,
             });
+        } else if (this.currentRound >= maxRounds) {
+            // Last iteration: the `plan.action === 'synthesize' || currentRound >=
+            // maxRounds` break below fires no matter what the evaluator decides, and
+            // the forced-synthesis path after the loop runs updatePlanForRound again
+            // with mustSynthesize. So on every capped run whose evaluator would have
+            // said `delegate` — the common case, since it is being cut off mid-plan —
+            // this call is a second full-context coordinator request whose result is
+            // discarded. Break straight to the forced synthesis: exactly one
+            // coordinator call either way, and the same outcome.
+            logger.log(`[DeepOrchestrator] Round cap (${maxRounds}) reached — skipping the evaluator and going straight to final synthesis ${this.elapsed()}`);
+            break;
         } else {
             const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
             observer?.onEvaluationStart?.(this.currentRound);
@@ -234,6 +244,11 @@ export class DeepResearchOrchestrator {
                 reports: synthesisService.getAllReports(researchId),
                 previousPlan: planningService.getCurrentPlan(researchId),
                 totalResearchersPlanned: planningService.getTotalResearchersPlanned(researchId),
+                // Live, steering-extended budget — see maxRounds comment above. Without
+                // this, updatePlanForRound recomputes the BASE complexity-table value
+                // internally and understates the denominator once steering has extended
+                // the round budget, prematurely skewing its round-phase guidance to LATE.
+                maxRounds,
                 signal,
                 observer,
                 excludeTools: this.options.excludeTools,
@@ -283,11 +298,15 @@ export class DeepResearchOrchestrator {
                     clearTimeout(timeout);
                     reject(new Error('Research cancelled'));
                 };
+                // Deliberately REFERENCED: this sleep IS the run's sole pending
+                // operation at this moment (nothing else is in flight during a
+                // 'wait'), so an unref'd timer would let the process drain its
+                // event loop and exit 0 silently mid-run. Abortability, not
+                // unref, is what keeps cancellation responsive here.
                 const timeout = setTimeout(() => {
                     signal?.removeEventListener('abort', onAbort);
                     resolve();
                 }, 5000);
-                safeUnref(timeout);
                 signal?.addEventListener('abort', onAbort, { once: true });
             });
             
@@ -382,7 +401,7 @@ export class DeepResearchOrchestrator {
                 options: {
                     ...this.options,
                     config: this.config,
-                    excludeTools: this.options.excludeTools || ['grep'],
+                    excludeTools: resolveExcludedTools(this.options.excludeTools),
                     observer: this.observer,
                 },
                 currentRound: this.currentRound,
@@ -463,6 +482,8 @@ export class DeepResearchOrchestrator {
               previousPlan: planningService.getCurrentPlan(researchId),
               totalResearchersPlanned: planningService.getTotalResearchersPlanned(researchId),
               mustSynthesize: true,
+              // Live, steering-extended budget — see the in-loop call above.
+              maxRounds,
               signal,
               observer,
               excludeTools: this.options.excludeTools,

package/src/orchestration/headless-observer.ts

@@ -139,6 +139,10 @@ export class HeadlessObserver implements ResearchObserver {
     this.emit('researcher_progress', { id, status, tokens, cost });
   }
 
+  onResearcherTokensHint(id: string, inputTokens: number): void {
+    this.emit('researcher_tokens_hint', { id, inputTokens });
+  }
+
   onResearcherComplete(id: string, report: string): void {
     this.emit('researcher_complete', { id, report });
   }
@@ -167,6 +171,10 @@ export class HeadlessObserver implements ResearchObserver {
     this.emit('evaluation_decision', { action, plan, round });
   }
 
+  onSynthesisStart(): void {
+    this.emit('synthesis_start');
+  }
+
   onComplete(result: string): void {
     this.emit('complete', { result });
   }

package/src/orchestration/quick-research-orchestrator.ts

@@ -18,7 +18,7 @@ import { logger } from '../logger.ts';
 import { getConfig, type Config } from '../config.ts';
 import { createResearcherSession } from './researcher.ts';
 import { ensureAssistantResponse, parseCitations } from '../utils/text-utils.ts';
-import { getMaxScrapeBatches } from '../constants.ts';
+import { getMaxScrapeBatches, resolveExcludedTools } from '../constants.ts';
 import type { ResearchObserver } from '../core/interfaces/observer-interfaces.ts';
 import { HeadlessObserver, makeSafeObserver, type HeadlessObserverOptions } from './headless-observer.ts';
 import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
@@ -180,7 +180,7 @@ export class QuickResearchOrchestrator {
           modelRegistry: ctx.modelRegistry,
           systemPrompt: prompt,
           extensionCtx: ctx,
-          excludeTools: this.options.excludeTools || ['grep'],
+          excludeTools: resolveExcludedTools(this.options.excludeTools),
           config: this.config,
           getGlobalState: (): SystemResearchState => ({
             version: 1,

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

@@ -14,7 +14,7 @@ import type { Model } from '@earendil-works/pi-ai';
 import { resolveResearchModel } from '../core/llm/research-model-resolver.ts';
 import type { QueryResultWithError } from '../web-research/types.ts';
 import type { RunResearchersOptions } from './orchestration-types.ts';
-import { RESEARCHER_LAUNCH_DELAY_MS } from '../constants.ts';
+import { RESEARCHER_LAUNCH_DELAY_MS, resolveExcludedTools } from '../constants.ts';
 import { search } from '../web-research/search.ts';
 import { parseCitations } from '../utils/text-utils.ts';
 import { logger, resetLogger } from '../logger.ts';
@@ -39,6 +39,7 @@ import { getCachedScrapedContent, normalizeUrl, cleanupSharedLinks } from '../ut
 import { runResearcher } from './researcher-executor.ts';
 import { ResearchRunSemaphore, ResearchRunCapacityError } from '../infrastructure/research-run-semaphore.ts';
 import { recordResearcherFailure, shouldStopResearch, createResearchStopError } from './session-state.ts';
+import { isAbortSentinel, boundSessionAbort } from './abort-utils.ts';
 import type { ResearchSessionService } from './research-session-service.ts';
 import { QuickResearchOrchestrator } from './quick-research-orchestrator.ts';
 import { DeepResearchOrchestrator } from './deep-research-orchestrator.ts';
@@ -98,9 +99,7 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
     const configDisabledTools = researchConfig.DISABLED_TOOLS
       ? researchConfig.DISABLED_TOOLS.split(',').map((s) => s.trim()).filter(Boolean)
       : [];
-    const mergedExcludeTools = configDisabledTools.length > 0
-      ? [...new Set([...(excludeTools ?? []), ...configDisabledTools])]
-      : excludeTools;
+    const mergedExcludeTools = resolveExcludedTools(excludeTools, configDisabledTools);
 
     // Resolve model using centralized priority logic
     const selectedModel = await this.resolveResearchModel(options);
@@ -346,8 +345,34 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
       // without this an early check, up to maxConcurrent-1 extra researchers could
       // start past the stop threshold and waste a browser slot + an LLM call.
       if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
-        const sessionService = await getService<ResearchSessionService>(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
-        await sessionService.abortAllSessions(researchId);
+        // A SIGTERM mid-run disposes the container, and getService then throws
+        // "Cannot get service … during container disposal" — which would REPLACE
+        // the already-decided stop error with a raw service error. Teardown is
+        // happening either way, so a failure here must not gate the stop throw.
+        try {
+          const sessionService = await getService<ResearchSessionService>(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
+          // Bounded: abortAllSessions awaits each session's abort, and session.abort()
+          // can wedge on the very in-flight call it is cancelling — an unbounded await
+          // here would hang the fast-stop throw for as long as the wedged call takes.
+          // Proceed after the bound; the abandoned aborts drain in the background.
+          await boundSessionAbort(
+            sessionService.abortAllSessions(researchId),
+            () => logger.debug('[ResearchOrchestrationService] Fast-stop abortAllSessions did not settle within bound; proceeding with stop'),
+          );
+        } catch (abortErr) {
+          logger.debug(`[ResearchOrchestrationService] Fast-stop session abort unavailable (container disposing?): ${abortErr instanceof Error ? abortErr.message : String(abortErr)}`);
+        }
+        // abortAllSessions only reaches REGISTERED sessions; a researcher still
+        // building a session, in a retry backoff, or in its initial-links search
+        // loop self-stops via shouldStopResearch (researcher-executor.ts). Bound-
+        // await the active set so those self-stops settle BEFORE the stop error
+        // returns the run and releases its run-cap slot — bounded for the same
+        // reason as boundSessionAbort: one wedged researcher must not hang the
+        // already-decided stop.
+        await boundSessionAbort(
+          Promise.allSettled(active).then(() => undefined),
+          () => logger.debug('[ResearchOrchestrationService] Fast-stop: active researchers did not settle within bound; proceeding with stop'),
+        );
         throw createResearchStopError(sessionId, researchId);
       }
 
@@ -367,7 +392,7 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
         }) : null;
         try {
           await Promise.race([...active, ...(abortPromise ? [abortPromise] : [])])
-            .catch(err => { if (err.message !== 'Aborted') throw err; });
+            .catch(err => { if (!isAbortSentinel(err.message)) throw err; });
         } finally {
           if (signal && onAbort) signal.removeEventListener('abort', onAbort);
         }
@@ -396,11 +421,18 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
           });
         } catch (err) {
           const errMsg = err instanceof Error ? err.message : String(err);
-          // A user cancellation (quit mid-run) surfaces here as an 'Aborted' throw.
-          // That is a clean stop, not a researcher failure: don't log it at ERROR,
-          // don't count it toward the fast-stop threshold, and don't paint the TUI
-          // researcher slice red. Mirrors the guard in researcher-executor.ts.
-          if (signal?.aborted || errMsg === 'Aborted') {
+          // A user cancellation (quit mid-run) surfaces here as an abort-sentinel
+          // throw — either the race's bare 'Aborted' or the '<id>: Aborted' that
+          // ensureAssistantResponse raises for an externally-aborted session (the
+          // fast-stop path). Container disposal (SIGTERM mid-run) is the same
+          // clean-teardown class: the executor stops retrying on it, and counting
+          // its "during container disposal" throw as a researcher failure both
+          // paints a red slice with a bogus root cause and can trip
+          // shouldStopResearch during shutdown. None of these are researcher
+          // failures: don't log at ERROR, don't count toward the fast-stop
+          // threshold, don't paint the TUI slice red. Mirrors the guard in
+          // researcher-executor.ts.
+          if (signal?.aborted || isAbortSentinel(errMsg) || container?.isDisposing || errMsg.includes('during container disposal')) {
             logger.debug(`[ResearchOrchestrationService] Researcher ${id} cancelled (aborted).`);
           } else {
             logger.error(`[ResearchOrchestrationService] Researcher ${id} failed: ${errMsg}`);
@@ -438,9 +470,27 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
       }
 
       if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
-        const sessionService = await getService<ResearchSessionService>(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
-        // Abort sessions specifically for this researchId, not the whole piSessionId
-        await sessionService.abortAllSessions(researchId);
+        // getService can throw during container disposal — same guard as the
+        // pre-launch fast-stop above: the stop error must win, not a raw
+        // "Cannot get service … during container disposal".
+        try {
+          const sessionService = await getService<ResearchSessionService>(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
+          // Abort sessions specifically for this researchId, not the whole piSessionId.
+          // Bounded for the same reason as the pre-launch fast-stop above: a wedged
+          // session.abort() must not gate the stop error that is already decided.
+          await boundSessionAbort(
+            sessionService.abortAllSessions(researchId),
+            () => logger.debug('[ResearchOrchestrationService] Fast-stop abortAllSessions did not settle within bound; proceeding with stop'),
+          );
+        } catch (abortErr) {
+          logger.debug(`[ResearchOrchestrationService] Fast-stop session abort unavailable (container disposing?): ${abortErr instanceof Error ? abortErr.message : String(abortErr)}`);
+        }
+        // Bound-await the active set so unregistered researchers self-stop before
+        // the stop error releases the run-cap slot (see the pre-launch site).
+        await boundSessionAbort(
+          Promise.allSettled(active).then(() => undefined),
+          () => logger.debug('[ResearchOrchestrationService] Fast-stop: active researchers did not settle within bound; proceeding with stop'),
+        );
 
         throw createResearchStopError(sessionId, researchId);
       }

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

@@ -12,6 +12,7 @@ import type { AgentSession } from '@earendil-works/pi-coding-agent';
 import { logger } from '../logger.ts';
 import { ServiceLifecycle, type IService } from '../core/service-registry.ts';
 import { ServiceNames } from '../core/interfaces/service-names.ts';
+import { boundSessionAbort } from './abort-utils.ts';
 
 /**
  * Session entry with abort capability
@@ -99,26 +100,51 @@ export class ResearchSessionService implements IService {
   }
 
   /**
-   * Abort all active sessions for a specific sessionId, or all sessions if sessionId is omitted
+   * Abort all active sessions for a specific sessionId, or all sessions if sessionId is omitted.
+   *
+   * Each abort is bounded (boundSessionAbort): entry.abort() awaits the very
+   * in-flight call it is cancelling, which may never settle — and this method
+   * gates both the fast-stop throw (runResearchers) and run()'s finally via
+   * cleanup(), so one wedged session would otherwise hang the whole run's
+   * return. When the bound fires, teardown proceeds and the abandoned abort
+   * keeps draining in the background.
    */
   async abortAllSessions(sessionId?: string): Promise<void> {
     if (sessionId) {
-      const sessionMap = this.getSessionMap(sessionId);
-      const aborts = Array.from(sessionMap.values()).map((entry, index) =>
-        entry.abort().catch((err) => {
-          logger.warn(`[ResearchSessionService] Failed to abort session ${index}:`, err);
-        })
+      // Read path: peek, never create — getSessionMap would resurrect an empty
+      // bucket for an already-completed researchId and leak it forever.
+      const sessionMap = this.peekSessionMap(sessionId);
+      if (!sessionMap) return;
+      // Snapshot BEFORE awaiting: only the entries aborted below may be removed.
+      // A session registered (or re-registered under the same id) DURING the
+      // bounded awaits — e.g. a researcher retry building a fresh session — was
+      // never aborted here; a blanket clear() would silently orphan it live.
+      const snapshot = Array.from(sessionMap.entries());
+      const aborts = snapshot.map(([, entry], index) =>
+        boundSessionAbort(
+          entry.abort().catch((err) => {
+            logger.warn(`[ResearchSessionService] Failed to abort session ${index}:`, err);
+          }),
+          () => logger.debug(`[ResearchSessionService] Session ${index} abort did not settle within bound; continuing teardown`),
+        )
       );
       await Promise.all(aborts);
-      sessionMap.clear();
-      this.sessions.delete(sessionId);
+      for (const [id, entry] of snapshot) {
+        // Identity check: delete only the exact entry we aborted, not a
+        // same-id replacement registered while we awaited.
+        if (sessionMap.get(id) === entry) sessionMap.delete(id);
+      }
+      if (sessionMap.size === 0) this.sessions.delete(sessionId);
     } else {
       const aborts: Promise<void>[] = [];
       for (const sessionMap of this.sessions.values()) {
         aborts.push(...Array.from(sessionMap.values()).map((entry, index) =>
-          entry.abort().catch((err) => {
-            logger.warn(`[ResearchSessionService] Failed to abort session ${index}:`, err);
-          })
+          boundSessionAbort(
+            entry.abort().catch((err) => {
+              logger.warn(`[ResearchSessionService] Failed to abort session ${index}:`, err);
+            }),
+            () => logger.debug(`[ResearchSessionService] Session ${index} abort did not settle within bound; continuing teardown`),
+          )
         ));
       }
       await Promise.all(aborts);