@lincoln504/pi-research 1.2.0 → 1.3.0

package/src/knowledge/embedder.ts

@@ -68,6 +68,28 @@ export class Embedder {
   private idleTimer: NodeJS.Timeout | null = null;
   private readonly IDLE_TIMEOUT_MS = 60 * 1000;
   private activeEmbeddings = 0;
+  /**
+   * Embed calls actively INSIDE the model (a pipeline invocation in flight), as
+   * opposed to activeEmbeddings, which counts whole embed()/embedMany() calls —
+   * including callers parked on recoveryPromise after a device loss. recoverToCpu
+   * drains THIS count before swapping the pipeline: parked callers still hold
+   * their activeEmbeddings slot (decremented downstream in their finally), so a
+   * drain on activeEmbeddings could never succeed with ≥2 concurrent device-loss
+   * failures and always burned the full timeout.
+   */
+  private activeInferences = 0;
+  /**
+   * Callers parked on recoveryPromise — they JOINED an in-flight recovery while
+   * still holding their activeEmbeddings slot (the decrement runs downstream in
+   * their finally, after the joined recovery settles). recoverToCpu's drain must
+   * distinguish them from callers still progressing toward the pipeline (parked
+   * on the per-call GPU lock, or between embedMany batches): parked joiners can
+   * never finish until recovery completes (waiting on them deadlocks into the
+   * drain timeout), while the progressing callers MUST be waited for — disposing
+   * the pipeline under them raises a TypeError no device-error classifier
+   * recognizes, so their embed fails unrecovered.
+   */
+  private recoveryWaiters = 0;
   /**
    * Why the in-flight dispose was started. An IDLE dispose is a memory-reclaim
    * pause that a later embed is expected to undo, so initialize() waits it out and
@@ -389,13 +411,36 @@ export class Embedder {
     return text;
   }
 
+  /**
+   * Run the pipeline over an input, tracked in activeInferences so recoverToCpu's
+   * drain loop waits only on calls genuinely inside the model.
+   */
+  private async runInference(input: string | string[]): Promise<any> {
+    // A disposal/recovery that raced this call may have nulled the pipeline out
+    // from under us. Calling through null raises a bare TypeError that nothing
+    // classifies (the writer queue drops the document as a generic ingest_error);
+    // throw the reconnect-classified signal instead — isEmbedderUnreachable
+    // matches "aborted" — so the caller retries via a fresh embedder.
+    if (!this.pipeline) {
+      throw new Error('[embedder] embed aborted: pipeline disposed before inference could run — reconnect required');
+    }
+    this.activeInferences++;
+    try {
+      return await logger.runCapturingStderr(async () => {
+        return await this.pipeline!(input, this.pipelineOpts());
+      });
+    } finally {
+      this.activeInferences--;
+    }
+  }
+
   async embed(text: string): Promise<Float32Array> {
     await this.initialize();
     // Compute the input BEFORE the active-count increment: truncateText is a pure
     // string op, and keeping it (and nothing else) ahead of the try/finally means
     // every path that can throw or await is inside the finally that decrements the
     // counter. Otherwise a throw here (or in acquireGpuLock) would leak the count,
-    // permanently wedging recoverToCpu (15s spin) and dispose (5s hang).
+    // permanently wedging dispose (5s hang).
     const input = this.truncateText(this.queryPrefix ? this.queryPrefix + text : text);
     this.stopIdleTimer();
     this.activeEmbeddings++;
@@ -408,9 +453,7 @@ export class Embedder {
           logger.warn('[embedder] GPU per-call lock timeout after 15s — proceeding without lock');
         }
       }
-      const output = await logger.runCapturingStderr(async () => {
-        return await this.pipeline!(input, this.pipelineOpts());
-      });
+      const output = await this.runInference(input);
       return output.data as Float32Array;
     } catch (err) {
       if (isWebGpuDeviceError(err)) {
@@ -425,9 +468,7 @@ export class Embedder {
         // dereferencing a null pipeline would raise a TypeError that MASKS the
         // original device error — rethrow the original instead.
         if (!this.pipeline) throw err;
-        const output = await logger.runCapturingStderr(async () => {
-          return await this.pipeline!(input, this.pipelineOpts());
-        });
+        const output = await this.runInference(input);
         return output.data as Float32Array;
       }
       throw err;
@@ -472,9 +513,7 @@ export class Embedder {
 
           let output: any;
           try {
-            output = await logger.runCapturingStderr(async () => {
-              return await this.pipeline!(batch, this.pipelineOpts());
-            });
+            output = await this.runInference(batch);
           } catch (err) {
             if (isWebGpuDeviceError(err)) {
               if (lockAcquired && this.stateManager) {
@@ -487,9 +526,7 @@ export class Embedder {
               // Same guard as embed(): recoverToCpu may have skipped (disposing/idle),
               // leaving pipeline null — rethrow the original error, not a TypeError.
               if (!this.pipeline) throw err;
-              output = await logger.runCapturingStderr(async () => {
-                return await this.pipeline!(batch, this.pipelineOpts());
-              });
+              output = await this.runInference(batch);
             } else {
               throw err;
             }
@@ -513,7 +550,17 @@ export class Embedder {
   }
 
   private async recoverToCpu(): Promise<void> {
-    if (this.recoveryPromise) return this.recoveryPromise;
+    if (this.recoveryPromise) {
+      // Counted join: this caller still holds its activeEmbeddings slot while
+      // parked here, and the drain below must not wait on parked joiners (see
+      // the recoveryWaiters field comment).
+      this.recoveryWaiters++;
+      try {
+        return await this.recoveryPromise;
+      } finally {
+        this.recoveryWaiters--;
+      }
+    }
 
     // Guard: if disposal has already started, skip recovery — the embedder is going away.
     if (this.state === 'disposing' || this.state === 'idle') {
@@ -521,22 +568,42 @@ export class Embedder {
       return;
     }
 
-    this.recoveryPromise = (async () => {
+    // Close the initialize() re-entry window SYNCHRONOUSLY, before the first
+    // await: initialize() only checks 'ready'/'disposing' and initializingPromise,
+    // so until the recovery promise below is published, a concurrent
+    // embed()/embedMany() passed every guard and launched a second concurrent
+    // _initializeInternal — racing pipeline/state assignments, leaking the losing
+    // pipeline, and (device was flipped to 'cpu' only after the drain loop)
+    // reloading the exact WebGPU backend that just failed. Flip device first so
+    // no joiner can ever observe 'webgpu' again this session.
+    this.state = 'initializing';
+    this.device = 'cpu';
+
+    const recovery = (async () => {
       logger.warn('[embedder] WebGPU device error detected during operation — falling back to CPU for the remainder of this session');
-      
+
       markWebGpuFallback();
-      
+
       await releaseGpuLock(this.stateManager, this.gpuLockHeld);
       this.gpuLockHeld = false;
-      
-      this.state = 'initializing';
-      
-      // Wait for other concurrent embeddings to finish before disposing the pipeline
+
+      // Drain in-flight callers before disposing the pipeline, on BOTH counts:
+      //  - activeInferences > 0: a call genuinely inside the model.
+      //  - activeEmbeddings - recoveryWaiters > 1: callers past initialize() but
+      //    not yet inside the model — parked on the per-call GPU lock, or between
+      //    embedMany batches. Self counts as 1 (this recovery runs from a caller
+      //    holding its own slot); parked joiners are subtracted because they can
+      //    never finish until THIS recovery completes (an uncorrected
+      //    activeEmbeddings drain always burned the full timeout under
+      //    multi-caller device loss). An inferences-only drain (the prior form)
+      //    disposed the pipeline under a lock-parked caller, whose embed then
+      //    failed with an unclassified TypeError, masking the device loss.
       const maxWaitMs = 15000;
       const startTime = Date.now();
-      // We expect activeEmbeddings to be at least 1 (the current caller).
-      // If multiple callers are in recoverToCpu, they all wait for recoveryPromise.
-      while (this.activeEmbeddings > 1 && (Date.now() - startTime) < maxWaitMs) {
+      while (
+        (this.activeInferences > 0 || this.activeEmbeddings - this.recoveryWaiters > 1) &&
+        (Date.now() - startTime) < maxWaitMs
+      ) {
         await new Promise(resolve => setTimeout(resolve, 50));
       }
 
@@ -544,25 +611,40 @@ export class Embedder {
         try { if (typeof (this.pipeline as any).dispose === 'function') await (this.pipeline as DisposablePipeline).dispose(); } catch (err) { logger.warn('[embedder] Error disposing pipeline:', err); }
         this.pipeline = null;
       }
-      this.device = 'cpu';
-      
-      this.initializingPromise = this._initializeInternal();
+
       try {
-          await this.initializingPromise;
-          this.state = 'ready';
+        await this._initializeInternal();
       } catch (e) {
-          this.state = 'failed';
-          throw e;
-      } finally {
-          this.initializingPromise = null;
+        this.state = 'failed';
+        throw e;
       }
+      // Same guard as initialize(): a terminal dispose may have landed while the
+      // CPU pipeline loaded — never overwrite 'disposing' with 'ready'. (Cast
+      // defeats control-flow narrowing, which cannot see the awaited init racing
+      // dispose() — same idiom as the state re-checks in initialize().)
+      if ((this.state as EmbedderState) === 'disposing') {
+        logger.warn('[embedder] Recovery finished but embedder was disposed in the meantime.');
+        return;
+      }
+      this.state = 'ready';
       logger.warn('[embedder] CPU fallback recovery complete.');
     })();
 
+    this.recoveryPromise = recovery;
+    // Publish for initialize(): a caller arriving mid-recovery must join the
+    // WHOLE recovery (drain + pipeline swap + re-init), not start its own. This
+    // and the assignments above run before recovery's first await, so there is
+    // no window in which a joiner can slip past.
+    this.initializingPromise = recovery;
+
     try {
-      await this.recoveryPromise;
+      await recovery;
     } finally {
-      this.recoveryPromise = null;
+      if (this.recoveryPromise === recovery) this.recoveryPromise = null;
+      // Guarded: by the time this finally runs, a fresh initialize() may already
+      // own initializingPromise (e.g. after a failed recovery) — never null it out
+      // from under that caller.
+      if (this.initializingPromise === recovery) this.initializingPromise = null;
     }
   }
 
@@ -590,14 +672,16 @@ export class Embedder {
     this.disposePromise = (async () => {
       // Wait for all active embeddings to complete
       const maxWaitMs = 5000;
-      const startTime = Date.now();
-      while (this.activeEmbeddings > 0 && (Date.now() - startTime) < maxWaitMs) {
-        await new Promise(resolve => setTimeout(resolve, 50));
-      }
-
-      if (this.activeEmbeddings > 0) {
-        logger.warn(`[embedder] Disposing with ${this.activeEmbeddings} active embeddings (timed out)`);
-      }
+      const drainActiveEmbeddings = async (): Promise<void> => {
+        const startTime = Date.now();
+        while (this.activeEmbeddings > 0 && (Date.now() - startTime) < maxWaitMs) {
+          await new Promise(resolve => setTimeout(resolve, 50));
+        }
+        if (this.activeEmbeddings > 0) {
+          logger.warn(`[embedder] Disposing with ${this.activeEmbeddings} active embeddings (timed out)`);
+        }
+      };
+      await drainActiveEmbeddings();
 
       if (this.initializingPromise) {
         try {
@@ -605,6 +689,15 @@ export class Embedder {
         } catch (_e) {
           // Initialize failed, which is fine
         }
+        // A caller parked on that same init increments activeEmbeddings only
+        // AFTER init resolves — i.e. after the drain above already passed — and
+        // initialize()'s disposed-mid-init branch returns cleanly, so its embed
+        // proceeds into runInference. Yield one macrotask so those callers reach
+        // their increment, then drain AGAIN; otherwise the pipeline below is
+        // torn down under a just-started inference (an unclassified TypeError
+        // the writer queue drops as a generic ingest_error).
+        await new Promise(resolve => setTimeout(resolve, 0));
+        await drainActiveEmbeddings();
       }
 
       if (this.pipeline) {

package/src/knowledge/store.ts

@@ -256,7 +256,12 @@ export class KnowledgeStore implements IKnowledgeStore {
             // getDimension() report the correct new width. (re-embed needs the warm
             // embedder regardless.)
             if (this.options.embedder.getDimension() === null) {
-              await this.options.embedder.embedMany([' ']);
+              // Reconnect-wrapped: after a service re-scope this warm-up can be
+              // the FIRST embed against a stale cached instance (a stepped-down
+              // leader fast-fails with ECONNREFUSED); without the wrapper that
+              // single fast-fail aborted the whole open, burning an init retry
+              // per attempt against the same dead instance.
+              await this.withEmbedderReconnect(embedder => embedder.embedMany([' ']));
             }
             try {
               await this.handleModelChange(storedModel || 'unknown', this.options.modelName, strategy);
@@ -977,9 +982,19 @@ export class KnowledgeStore implements IKnowledgeStore {
         config: Index.fts(),
         replace: true,
       });
-      // Record the version AFTER indexing (createIndex commits its own transactions) so the
-      // next call compares against this post-rebuild baseline and only rebuilds on real writes.
-      this.lastFtsVersion = await (await this.getFreshTable()).version();
+      // Record the post-rebuild baseline from THIS handle, whose version() is
+      // checkout-stable: it advances with our own createIndex commits but not with
+      // commits from other handles/processes. Re-reading through a fresh handle
+      // here (the old code) read the LATEST version instead — addDocuments takes
+      // no lock, so rows committed DURING the rebuild were absorbed into the
+      // baseline as already-indexed and stayed out of the BM25 leg until an
+      // unrelated later commit. Each createIndex commits exactly one version
+      // (measured on lancedb 0.29, fresh and replace alike); anything beyond
+      // version+2 means a concurrent commit rebased beneath our index commits, so
+      // fall back to the conservative pre-rebuild baseline — the next cleanup
+      // sees version > baseline and rebuilds over the missed rows.
+      const postVersion = await table.version();
+      this.lastFtsVersion = postVersion <= version + 2 ? postVersion : version;
       logger.info('[store] FTS indexes rebuilt (text + content).');
       return true;
     } catch (err) {
@@ -1027,7 +1042,12 @@ export class KnowledgeStore implements IKnowledgeStore {
         // rebuilds + re-optimizes (the disk-bloat regression). A stale baseline (index not
         // current, or never built) is left untouched so the next rebuild still detects the
         // pending change.
-        const wasFtsIndexCurrent = !stale && this.lastFtsVersion !== null && this.lastFtsVersion === await table.version();
+        // The row count is sampled BEFORE the version read: since optimize never changes
+        // the row set, a same-handle count that differs after the call proves rows were
+        // committed DURING optimize's window (rebased beneath its compaction commits) —
+        // rows the FTS index does not cover, which the baseline advance below must skip.
+        const rowCountBefore = !stale && this.lastFtsVersion !== null ? await table.countRows() : null;
+        const wasFtsIndexCurrent = rowCountBefore !== null && this.lastFtsVersion === await table.version();
         // cleanupOlderThan defaults to now: prune every prunable old version. The
         // current version is always retained, and (with deleteUnverified=false)
         // physical files inside LanceDB's safety window are kept regardless.
@@ -1043,9 +1063,14 @@ export class KnowledgeStore implements IKnowledgeStore {
         const bytesRemoved = stats?.prune?.bytesRemoved ?? 0;
         logger.info(`[store] Optimize complete: removed ${removed} old version(s), reclaimed ${bytesRemoved} bytes (${duration}ms).`);
         // Keep the FTS skip-guard baseline in sync with optimize's layout-only version bump
-        // so the next rebuildFtsIndex correctly skips when no content changed.
-        if (wasFtsIndexCurrent) {
-          this.lastFtsVersion = await (await this.getFreshTable()).version();
+        // so the next rebuildFtsIndex correctly skips when no content changed. Stamp from
+        // THIS handle (checkout-stable: it advances with optimize's own commits but not
+        // with foreign ones — a fresh re-open here read the latest version and absorbed
+        // concurrent commits), and only when the row count is unchanged: a differing count
+        // means an addDocuments landed inside optimize's window and must not be recorded
+        // as already-indexed (the baseline stays put, so the next rebuild catches it).
+        if (wasFtsIndexCurrent && (await table.countRows()) === rowCountBefore) {
+          this.lastFtsVersion = await table.version();
         }
         return true;
       } catch (err) {
@@ -1113,11 +1138,19 @@ export class KnowledgeStore implements IKnowledgeStore {
       // `_backup_` dirs are intentional, user-recoverable snapshots from the
       // 'backup' migration strategy. RETAIN the most recent one (deleting it
       // would make 'backup' silently equivalent to 'drop'); prune only older,
-      // superseded backups so they don't accumulate. ISO-timestamp names sort
-      // chronologically, so the last entry is newest.
+      // superseded backups so they don't accumulate. Rank by the trailing
+      // `_backup_<timestamp>` suffix, NOT by whole-name sort: the prefix is the
+      // table name AT BACKUP TIME — legitimately `knowledge` OR
+      // `knowledge_migration_<ts>` (persisted re-embed rename failure) — and
+      // `knowledge_b…` < `knowledge_m…` lexicographically, so a whole-name sort
+      // retained an OLD migration-named backup while deleting a NEWER
+      // `knowledge_backup_*`.
       if (backupDirs.length > 1) {
-        backupDirs.sort();
-        for (const name of backupDirs.slice(0, -1)) {
+        const ranked = await Promise.all(
+          backupDirs.map(async name => ({ name, ts: await this.backupDirTimestamp(name) }))
+        );
+        ranked.sort((a, b) => a.ts - b.ts);
+        for (const { name } of ranked.slice(0, -1)) {
           const fullPath = path.join(this.options.dbDir, name);
           logger.info(`[store] Removing superseded backup directory: ${name}`);
           await fsPromises.rm(fullPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
@@ -1128,6 +1161,27 @@ export class KnowledgeStore implements IKnowledgeStore {
     }
   }
 
+  /**
+   * Creation time of a backup dir, for retention ranking in
+   * pruneOrphanedMigrationDirs. Parses the trailing `_backup_<timestamp>` suffix
+   * (an ISO timestamp with `:`/`.` mapped to `-`, exactly as migrationBackup
+   * writes it); falls back to directory mtime for names that don't parse, and to
+   * 0 (ranked oldest, pruned first) if even stat fails.
+   */
+  private async backupDirTimestamp(name: string): Promise<number> {
+    const m = name.match(/_backup_(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z\.lance$/);
+    if (m) {
+      const parsed = Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`);
+      if (!Number.isNaN(parsed)) return parsed;
+    }
+    try {
+      const stat = await fsPromises.stat(path.join(this.options.dbDir, name));
+      return stat.mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
   async count(): Promise<number> {
     if (!this.db) return 0;
     // Track against close() — this read had no try/catch, so a teardown racing db.close()

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,7 +7,6 @@
 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, resolveExcludedTools } from '../constants.ts';
@@ -245,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,
@@ -294,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 });
             });
             
@@ -474,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 });
   }