@lincoln504/pi-research 1.4.3 → 1.5.1

package/src/knowledge/embedder.ts

@@ -50,6 +50,14 @@ export class Embedder {
   private initializingPromise: Promise<void> | null = null;
   private disposePromise: Promise<void> | null = null;
   private recoveryPromise: Promise<void> | null = null;
+  // Latched by the SerialQueue poison path (via EmbeddingServer): a native
+  // inference is permanently hung inside this pipeline. dispose() must then
+  // never call pipeline.dispose() — it would join the stuck native thread, the
+  // exact hazard the poison path's shutdown(false) avoided — yet this instance
+  // stays registered for process-exit cleanup (registerGlobalEmbedder), whose
+  // task calls dispose() unconditionally. Without the latch the teardown path
+  // re-created the hang the step-down deliberately abandoned.
+  private pipelineWedged = false;
 
   private model: string;
   private poolingMode: 'mean' | 'cls' | 'last_token';
@@ -656,6 +664,15 @@ export class Embedder {
     }
   }
 
+  /**
+   * Mark this embedder's pipeline as permanently wedged (a native inference hung
+   * past the SerialQueue hard deadline). From here on, dispose() abandons the
+   * pipeline instead of calling pipeline.dispose() — see pipelineWedged.
+   */
+  markPipelineWedged(): void {
+    this.pipelineWedged = true;
+  }
+
   /**
    * @param reason `'idle'` for the memory-reclaim pause driven by the idle timer —
    *   a later embed is allowed to revive the embedder. Anything else is terminal
@@ -678,9 +695,13 @@ export class Embedder {
     this.disposeReason = reason;
     this.state = 'disposing';
     this.disposePromise = (async () => {
-      // Wait for all active embeddings to complete
+      // Wait for all active embeddings to complete. Pointless when the pipeline
+      // is wedged: the hung call holds its activeEmbeddings slot forever, so the
+      // drain can only time out — skip straight to the (dispose-skipping)
+      // teardown below instead of burning the wait twice at process exit.
       const maxWaitMs = 5000;
       const drainActiveEmbeddings = async (): Promise<void> => {
+        if (this.pipelineWedged) return;
         const startTime = Date.now();
         while (this.activeEmbeddings > 0 && (Date.now() - startTime) < maxWaitMs) {
           await new Promise(resolve => setTimeout(resolve, 50));
@@ -709,14 +730,22 @@ export class Embedder {
       }
 
       if (this.pipeline) {
-        try {
-          if (typeof (this.pipeline as any).dispose === 'function') {
-            await (this.pipeline as DisposablePipeline).dispose();
+        if (this.pipelineWedged) {
+          // See pipelineWedged's declaration: disposing a wedged ORT session
+          // joins the permanently hung native thread. Abandon it — the native
+          // resources die with process exit, which is where this path runs.
+          logger.warn('[embedder] Skipping pipeline.dispose(): pipeline wedged by a permanently hung inference; abandoning native resources to process exit.');
+          this.pipeline = null;
+        } else {
+          try {
+            if (typeof (this.pipeline as any).dispose === 'function') {
+              await (this.pipeline as DisposablePipeline).dispose();
+            }
+          } catch (err) {
+            logger.warn('[embedder] Error during pipeline dispose:', err);
           }
-        } catch (err) {
-          logger.warn('[embedder] Error during pipeline dispose:', err);
+          this.pipeline = null;
         }
-        this.pipeline = null;
       }
 
       // Always release the GPU lock once on dispose (defensive: the gpuLockHeld flag

package/src/knowledge/store-operations.ts

@@ -13,6 +13,52 @@ import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
 import { StoreDocument } from '../core/interfaces/knowledge-interfaces.ts';
 
+/**
+ * Guard against a broken embedder silently writing corrupt vectors: a
+ * wrong-count, empty, ragged, or NaN/Inf-poisoned result would otherwise land
+ * in the FixedSizeList column and surface only as an opaque Arrow error or,
+ * worse, as silently degraded search (NaN distances break ANN ordering). Fail
+ * loudly at the last gate before persistence instead. Shared by the normal
+ * addDocuments path and the re-embed migration (which writes vectors through
+ * its own table handle and previously had no guard at all).
+ */
+export function assertValidEmbeddingVectors(
+  vectors: (Float32Array | number[])[],
+  expectedCount: number,
+  declaredDim: number | null | undefined,
+): void {
+  if (vectors.length !== expectedCount) {
+    throw new Error(
+      `[store] embedder returned ${vectors.length} vectors for ${expectedCount} documents`,
+    );
+  }
+  // Expected width: the embedder's declared dimension, falling back to the
+  // first vector's width. Every vector must match it exactly — a uniformly
+  // wrong width is just as corrupting as a ragged one.
+  const dim = declaredDim && declaredDim > 0 ? declaredDim : (vectors[0]?.length ?? 0);
+  if (dim === 0) {
+    throw new Error('[store] embedder returned empty/zero-width vectors');
+  }
+  for (let i = 0; i < vectors.length; i++) {
+    const v = vectors[i];
+    if (!v || v.length !== dim) {
+      throw new Error(
+        `[store] embedder returned a wrong-width vector at index ${i} (got ${v?.length ?? 0}, expected ${dim})`,
+      );
+    }
+    // A correct-width vector can still be poisoned: a WebGPU device-lost
+    // mid-inference, or a truncated server response coerced through
+    // Float32Array, yields NaN/Inf entries that pass every length check.
+    for (let j = 0; j < v.length; j++) {
+      if (!Number.isFinite(v[j]!)) {
+        throw new Error(
+          `[store] embedder returned a non-finite value (${v[j]}) at vector ${i}, position ${j}`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Add documents to the store
  */
@@ -35,44 +81,7 @@ export async function addDocumentsToStore(
 
   try {
     const vectors = await embedder.embedMany(docs.map(d => d.text));
-
-    // Guard against a broken embedder silently writing corrupt vectors: a
-    // wrong-count, empty, or ragged result would otherwise land in the
-    // FixedSizeList column and surface only as an opaque Arrow error or, worse,
-    // as silently degraded search. Fail loudly here instead.
-    if (vectors.length !== docs.length) {
-      throw new Error(
-        `[store] embedder returned ${vectors.length} vectors for ${docs.length} documents`,
-      );
-    }
-    // Expected width: the embedder's declared dimension, falling back to the
-    // first vector's width. Every vector must match it exactly — a uniformly
-    // wrong width is just as corrupting as a ragged one.
-    const declaredDim = embedder.getDimension?.();
-    const dim = declaredDim && declaredDim > 0 ? declaredDim : (vectors[0]?.length ?? 0);
-    if (dim === 0) {
-      throw new Error('[store] embedder returned empty/zero-width vectors');
-    }
-    for (let i = 0; i < vectors.length; i++) {
-      const v = vectors[i];
-      if (!v || v.length !== dim) {
-        throw new Error(
-          `[store] embedder returned a wrong-width vector at index ${i} (got ${v?.length ?? 0}, expected ${dim})`,
-        );
-      }
-      // A correct-width vector can still be poisoned: a WebGPU device-lost
-      // mid-inference, or a truncated server response coerced through
-      // Float32Array, yields NaN/Inf entries that pass every length check but
-      // silently corrupt the ANN index (NaN distances break ordering). Scan
-      // here — this is the last gate before the vector is persisted.
-      for (let j = 0; j < v.length; j++) {
-        if (!Number.isFinite(v[j]!)) {
-          throw new Error(
-            `[store] embedder returned a non-finite value (${v[j]}) at vector ${i}, position ${j}`,
-          );
-        }
-      }
-    }
+    assertValidEmbeddingVectors(vectors, docs.length, embedder.getDimension?.());
 
     const data = docs.map((doc, i) => ({
       vector: vectors[i]!,

package/src/knowledge/store.ts

@@ -22,7 +22,7 @@ import * as path from 'node:path';
 import { MigrationStrategy, MigrationResult } from './migration.ts';
 import { metrics } from '../utils/metrics.ts';
 import { createStoreTable, CURRENT_SCHEMA_VERSION } from './store-schema.ts';
-import { addDocumentsToStore, searchStore, findDocumentsByUrl, findRelevantUrls } from './store-operations.ts';
+import { addDocumentsToStore, assertValidEmbeddingVectors, searchStore, findDocumentsByUrl, findRelevantUrls } from './store-operations.ts';
 import { isEmbedderUnreachable } from './embedder-utils.ts';
 import { ServiceLifecycle } from '../core/service-registry.ts';
 import { ServiceNames } from '../core/service-interfaces.ts';
@@ -448,7 +448,16 @@ export class KnowledgeStore implements IKnowledgeStore {
         });
 
         const texts = batchDocs.map(d => d.text);
-        const vectors = await this.options.embedder.embedMany(texts);
+        // Reconnect-wrapped like the warm-up embed in openInternal: a re-embed
+        // migration is a LONG operation, exactly when a leader idle-dispose /
+        // step-down (ECONNREFUSED fast-fail) is most likely — and any throw
+        // here escalates through openInternal's fallback ladder to the 'backup'
+        // strategy, which replaces the fully-intact table with an EMPTY one.
+        // One transient blip must not convert "preserve my data" into that.
+        const vectors = await this.withEmbedderReconnect(embedder => embedder.embedMany(texts));
+        // Same last-gate integrity check as addDocumentsToStore: this path
+        // writes vectors through its own table handle and previously had none.
+        assertValidEmbeddingVectors(vectors, batchDocs.length, this.options.embedder.getDimension?.());
 
         const records = batchDocs.map((doc, idx) => ({
           vector: Array.from(vectors[idx]!),
@@ -527,10 +536,66 @@ export class KnowledgeStore implements IKnowledgeStore {
           // out of the way and start a fresh empty table over one manifest
           // write hiccup.
           logger.error('[store] Failed to persist canonical table name after rename — reverting to keep manifest and disk in sync.');
-          await fsPromises.rename(canonicalDir, tempDir);
-          this.tableName = tempTableName;
-          this.table = await this.db.openTable(this.tableName);
-          logger.info(`[store] Migrated data remains safe and accessible as ${tempTableName}; canonical rename deferred to a future successful manifest save.`);
+          try {
+            await fsPromises.rename(canonicalDir, tempDir);
+            this.tableName = tempTableName;
+            this.table = await this.db.openTable(this.tableName);
+            logger.info(`[store] Migrated data remains safe and accessible as ${tempTableName}; canonical rename deferred to a future successful manifest save.`);
+          } catch (revertErr) {
+            // The revert itself failed too. fs.rename is atomic on a single
+            // filesystem — a failed rename never leaves data half-moved — so
+            // the data is still fully at canonicalDir, not tempDir. The outer
+            // catch below was written for a DIFFERENT case (the first rename
+            // never happening at all) and would wrongly point the manifest at
+            // tempTableName, whose directory no longer exists on disk. Instead,
+            // try to persist a manifest against the name that actually matches
+            // disk right now, so the mismatch this whole branch exists to avoid
+            // doesn't reappear one level deeper.
+            logger.error(`[store] Revert rename also failed; data remains on disk at ${canonicalDir}: ${revertErr}`);
+            // Everything from here on is wrapped in its OWN try/catch and never
+            // rethrows: a third compounding failure (e.g. openTable() itself
+            // throwing, on the same underlying disk fault that already broke
+            // two renames) must not escape to the outer catch (renameErr)
+            // either — that one assumes data is still at tempDir, which by
+            // this point is doubly false.
+            // The manifest repair is deliberately NOT gated behind the table
+            // reopen: saveManifest depends only on writeFile/rename, not on an
+            // open table, so a reopen-only failure (a LanceDB-level fault on an
+            // otherwise-writable filesystem) must not skip a repair the code can
+            // still make — a skipped repair leaves the persisted manifest
+            // pointing at the nonexistent temp name, which is the next-restart
+            // empty-table hazard this whole branch exists to prevent.
+            this.tableName = canonicalName;
+            let reopened = false;
+            try {
+              this.table = await this.db.openTable(this.tableName);
+              reopened = true;
+            } catch (openErr) {
+              // A third compounding failure: even reopening the table at its
+              // actual on-disk location failed. This process has no working
+              // table handle for it, but the data itself should still be
+              // physically intact at canonicalDir (only the rename and its
+              // revert have run, and neither drops data — they only move a
+              // directory or fail outright). The manifest repair below still
+              // proceeds, so a future restart can find the data even though
+              // this process cannot serve it.
+              logger.error(`[store] CRITICAL: could not reopen the table at '${canonicalName}' after a failed rename revert (${openErr}). Data should still be intact on disk at ${canonicalDir}, but this process has no working table handle for it. Attempting the manifest repair anyway so a restart can find the data; verify ${canonicalDir} exists if problems persist.`);
+            }
+            try {
+              if (await this.saveManifest()) {
+                logger.warn(`[store] Recovered: manifest now points at '${canonicalName}', matching the data's actual on-disk location${reopened ? '' : ' (this process still has no working table handle — restart to serve it)'}.`);
+              } else {
+                // Both the revert and this recovery manifest save failed. The
+                // on-disk manifest (last persisted pointing at tempTableName,
+                // before the old table was dropped) now disagrees with disk.
+                // Fail loud rather than let a future restart silently create
+                // an empty table under the stale name.
+                logger.error(`[store] CRITICAL: could not persist a manifest matching disk after a failed rename revert. Data is intact on disk at ${canonicalDir} (table '${canonicalName}'), but the persisted manifest is stale and points at '${tempTableName}', which no longer exists. If this process exits before a future successful manifest save, the next start will not find the data automatically — manually repair the manifest to point at '${canonicalName}' before restarting.`);
+              }
+            } catch (manifestErr) {
+              logger.error(`[store] CRITICAL: manifest repair threw after a failed rename revert (${manifestErr}). Data is intact on disk at ${canonicalDir} (table '${canonicalName}'), but the persisted manifest is stale and points at '${tempTableName}'. Manually repair the manifest to point at '${canonicalName}' before restarting.`);
+            }
+          }
         }
       } catch (renameErr) {
         // If rename fails (cross-device, permissions, etc.) we keep the temp name
@@ -951,11 +1016,24 @@ export class KnowledgeStore implements IKnowledgeStore {
     // coexist, and LanceDB's fragment-scan order typically returns the OLDEST row
     // first — limit(1) would serve the superseded content (and feed its older
     // timestamp to the serve-age gate) until the next successful ingest.
-    const results = await table
+    const whereClause = `url = '${escapedUrl}' AND ingestion_type = 'synthesis-description' AND (${scopeFilter})`;
+    let results = await table
       .query()
-      .where(`url = '${escapedUrl}' AND ingestion_type = 'synthesis-description' AND (${scopeFilter})`)
+      .where(whereClause)
       .limit(16)
       .toArray();
+    if (results.length === 16) {
+      // Cap hit: the OLD generation alone may have filled all 16 slots (a long
+      // description chunks into many rows), leaving the newest generation
+      // entirely outside the fragment-scan window — the sort below would then
+      // pick "newest of the stale". Re-fetch with a bound two generations of
+      // one URL cannot plausibly reach.
+      results = await table
+        .query()
+        .where(whereClause)
+        .limit(1024)
+        .toArray();
+    }
 
     const duration = Date.now() - startTime;
     metrics.observe('knowledge_store_query_duration_ms', duration, { operation: 'rebuild_document' });

package/src/knowledge/writer-queue.ts

@@ -181,8 +181,10 @@ 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).
+    // findByUrl applies scope filtering, so this only dedupes within the current
+    // scope's VISIBLE rows — in project mode that is the workspace's own rows only
+    // (getScopeFilter() in project mode excludes global rows), which is correct because
+    // project mode doesn't serve global rows either.
     // 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.

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

@@ -43,6 +43,14 @@ export interface ObserverContext {
    */
   renderImmediate?: () => void;
   researchComplexity: number;
+  /**
+   * Whether prompt caching is active for the run's resolved model (see
+   * isPromptCachingActiveForModel). With caching active the effective
+   * per-researcher scrape-batch maximum is one higher, and progress units
+   * must be computed relative to that same effective count the tracker
+   * enforces — not the base configured value.
+   */
+  cachingActive?: boolean;
 }
 
 export interface ObserverState {
@@ -94,7 +102,7 @@ export function createResearchObserver(
         activateSlice(panelState, state.quickSliceLabel);
         updateSliceStatus(panelState, state.quickSliceLabel, 'starting...', debouncedRefresh);
 
-        const units = getUnitsPerResearcher();
+        const units = getUnitsPerResearcher(undefined, ctx.cachingActive);
         panelState.progress = { expected: units, made: 0 };
       }
       // Quick research: researcher is running → steering is acceptable
@@ -152,7 +160,7 @@ export function createResearchObserver(
     onPlanningSuccess: (plan) => {
       updateSliceStatus(panelState, 'coord', 'ready', debouncedRefresh);
       completeSlice(panelState, 'coord');
-      const unitsPerResearcher = getUnitsPerResearcher();
+      const unitsPerResearcher = getUnitsPerResearcher(undefined, ctx.cachingActive);
       const count = plan.researchers?.length || 0;
       const units = (count * unitsPerResearcher) + LEAD_EVAL_UNITS;
       panelState.progress = { expected: units, made: 0 };
@@ -319,7 +327,7 @@ export function createResearchObserver(
 
     onResearcherProgress: (id, status, tokens, cost) => {
       const sliceId = id === 'quick' ? state.quickSliceLabel : id;
-      const unitsPerResearcher = getUnitsPerResearcher();
+      const unitsPerResearcher = getUnitsPerResearcher(undefined, ctx.cachingActive);
       
       if (status !== undefined) {
         if (status.startsWith('done:')) {
@@ -350,7 +358,7 @@ export function createResearchObserver(
     onResearcherComplete: (id, _report) => {
       const sliceId = id === 'quick' ? state.quickSliceLabel : id;
       if (panelState.progress) {
-        const unitsPerResearcher = getUnitsPerResearcher();
+        const unitsPerResearcher = getUnitsPerResearcher(undefined, ctx.cachingActive);
         const current = progressCredits.get(id) ?? 0;
         const remaining = unitsPerResearcher - current;
         if (remaining > 0) {
@@ -365,7 +373,7 @@ export function createResearchObserver(
     onResearcherFailure: (id, _error) => {
       const sliceId = id === 'quick' ? state.quickSliceLabel : id;
       if (panelState.progress) {
-        const unitsPerResearcher = getUnitsPerResearcher();
+        const unitsPerResearcher = getUnitsPerResearcher(undefined, ctx.cachingActive);
         const current = progressCredits.get(id) ?? 0;
         const remaining = unitsPerResearcher - current;
         if (remaining > 0) {
@@ -430,7 +438,7 @@ export function createResearchObserver(
       } else {
         // Delegation: prepare for new round's search → researchers → steering acceptable
         if (plan?.researchers && plan.researchers.length > 0 && panelState.progress) {
-          const unitsPerResearcher = getUnitsPerResearcher();
+          const unitsPerResearcher = getUnitsPerResearcher(undefined, ctx.cachingActive);
           panelState.progress.expected += (plan.researchers.length * unitsPerResearcher) + LEAD_EVAL_UNITS;
         }
         panelState.steeringAcceptable = true;

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

@@ -226,13 +226,18 @@ export class DeepResearchOrchestrator {
         // to run the SAME round again. Announcing it each time emitted `round_start`
         // 1, 2, 2, 3 — a duplicate rather than the gap the post-loop guard was added for,
         // but the same broken contract for a consumer counting rounds.
-        if (this.currentRound > lastAnnouncedRound) {
+        const firstEntryThisRound = this.currentRound > lastAnnouncedRound;
+        if (firstEntryThisRound) {
           observer?.onRoundStart?.(this.currentRound);
           lastAnnouncedRound = this.currentRound;
         }
 
         // Check infrastructure health (advisory: logs status, never aborts the run).
-        await orchestrationService.checkHealth(this.currentRound, researchId, ctx);
+        // Once per round, not per loop entry: a 'wait' retry re-enters the same
+        // round and must not re-probe the same infrastructure it just probed.
+        if (firstEntryThisRound) {
+          await orchestrationService.checkHealth(this.currentRound, researchId, ctx);
+        }
 
         // 1. Update/Generate Plan
         let plan: ResearchPlan;
@@ -254,7 +259,14 @@ export class DeepResearchOrchestrator {
             });
         } else {
             const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
-            observer?.onEvaluationStart?.(this.currentRound);
+            // Same once-per-round contract as round_start above: a 'wait' retry
+            // re-enters this branch for the SAME round, and re-emitting
+            // evaluation_start per retry gave consumers counting evaluations
+            // duplicates (2, 2, 2 for one round-2 evaluation). The progress
+            // pulse below is a status update and stays per-entry.
+            if (firstEntryThisRound) {
+              observer?.onEvaluationStart?.(this.currentRound);
+            }
             observer?.onEvaluationProgress?.('evaluating');
             plan = await planningService.updatePlanForRound({
                 sessionId: researchId,

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

@@ -19,6 +19,7 @@ import { getConfig, type Config } from '../config.ts';
 import { createResearcherSession } from './researcher.ts';
 import { ensureAssistantResponse, parseCitations } from '../utils/text-utils.ts';
 import { getMaxScrapeBatches, resolveExcludedTools } from '../constants.ts';
+import { resolveResearchModel, isPromptCachingActiveForModel } from '../core/llm/research-model-resolver.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';
@@ -133,7 +134,15 @@ export class QuickResearchOrchestrator {
         }
 
         const researcherPromptTemplate = loadPrompt('researcher');
-        const maxScrapeBatches = getMaxScrapeBatches(this.config);
+        // Resolve the model here (same deterministic inputs createResearcherSession
+        // below will resolve again) purely to learn whether prompt caching will be
+        // active, so the batch count told to the model in the prompt below matches
+        // the limit ToolUsageTracker actually enforces — resolveResearchModel is a
+        // pure, cheap lookup over already-loaded registries, safe to call twice.
+        const cachingActiveForBudget = isPromptCachingActiveForModel(
+          resolveResearchModel({ modelRegistry: ctx.modelRegistry, config: this.config, hostModel: model, cwd: ctx.cwd })
+        );
+        const maxScrapeBatches = getMaxScrapeBatches(this.config, cachingActiveForBudget);
         const maxScrapeBatchesDisplay = maxScrapeBatches > 99 ? 'unlimited' : maxScrapeBatches.toString();
 
         const quickEvidenceSection =
@@ -162,19 +171,29 @@ export class QuickResearchOrchestrator {
         }
         evidenceLines.push(quickEvidenceSection);
 
+        // The system prompt carries only run-invariant instructions; the goal,
+        // knowledge-store results, evidence, and steering go in the initial USER
+        // message below. A byte-identical system prompt + tool set is the cacheable
+        // prefix providers key on, so back-to-back quick runs (and every follow-up
+        // turn within this session) reuse it via prompt-cache reads.
         const prompt = injectCurrentDate(researcherPromptTemplate, 'researcher')
-            // Function replacers: insert `$`-bearing dynamic content (scraped evidence,
-            // store descriptions, the user query) literally, not as a substitution pattern.
-            .replace('{{goal}}', () => query + steeringSection)
-            .replace('{{store_section}}', () => storeSection)
-            .replace('{{evidence_section}}', () => evidenceLines.join('\n\n'))
-            .replace('{{coordination_section}}', '')
             .replace('{{extra_tool_guidelines}}', '- `search`: Perform broad web searches (Round 1 only).')
             // Quick research has no research lead and no next round — see
             // RESEARCHER_DIGEST_SECTION. Its report IS the deliverable.
-            .replace('{{digest_section}}', '');
+            .replace('{{digest_section}}', '')
+            .trim();
 
-        logger.debug(`[QuickOrchestrator] System Prompt:\n${prompt}`);
+        // `$`-bearing dynamic content (the user query, store descriptions, steering)
+        // is plain string concatenation here — no String.replace substitution risk.
+        const userMessage = [
+          `Goal: ${query}`,
+          storeSection.trim(),
+          evidenceLines.join('\n\n').trim(),
+          steeringSection.trim(),
+          'Perform your research and submit your full report now.',
+        ].filter(Boolean).join('\n\n');
+
+        logger.debug(`[QuickOrchestrator] System Prompt:\n${prompt}\n\nUser Message:\n${userMessage}`);
 
         let lastSeenSearchCount = 0;
         const { session, resolvedModel } = await createResearcherSession({
@@ -287,7 +306,7 @@ export class QuickResearchOrchestrator {
           // whether the race resolves via session.prompt, timeout, or abort.
           let abortCleanup: (() => void) | undefined;
           try {
-            const promptPromise = session.prompt(query);
+            const promptPromise = session.prompt(userMessage);
             promptPromise.catch((err: Error) => logger.debug(`[QuickOrchestrator] Background session prompt rejection: ${err.message}`));
             await Promise.race([
               promptPromise,
@@ -337,6 +356,13 @@ export class QuickResearchOrchestrator {
 
           // Ensure CITED LINKS section is accurate and consistent
           result = synthesisService.ensureCitedLinks(this.options.researchId, result);
+          // Snapshot BEFORE steering guidance is appended: parseCitations absorbs
+          // any text trailing the last CITED LINKS entry into that entry's
+          // Description (the same mechanism that forced the weak-grounding notice
+          // to sit BEFORE the header), so knowledge-store descriptions must be
+          // parsed from the pre-steering text or a steered quick run stores the
+          // steering block inside the final source's description.
+          const citationSource = result;
 
           // Append steering guidance — only active (consumed by orchestrator) messages
           const finalSteeringMessages = getActiveSteeringMessages(this.options.sessionId);
@@ -367,7 +393,7 @@ export class QuickResearchOrchestrator {
               if (!writer) {
                 logger.debug('[QuickOrchestrator] Writer queue unavailable, skipping link descriptions');
               } else {
-              const citations = parseCitations(result);
+              const citations = parseCitations(citationSource);
               if (citations.length === 0) {
                 logger.warn('[QuickOrchestrator] Researcher produced no parseable CITED LINKS — no descriptions stored for this session');
               }

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

@@ -209,8 +209,12 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
       return result;
     } catch (error) {
       const researchDuration = Date.now() - researchStart;
-      metrics.observe('research_manager_latency_ms', researchDuration, { depth: String(depth), status: 'error', source: 'extension' });
-      metrics.increment('research_manager_requests_total', 1, { depth: String(depth), status: 'error', source: 'extension' });
+      // Label a user cancel 'cancelled', not 'error' — the orchestrators' own
+      // research_session_duration_ms one layer down already does, and a metrics
+      // consumer diffing the two layers read every quick-mode cancel as an error.
+      const status = signal?.aborted ? 'cancelled' : 'error';
+      metrics.observe('research_manager_latency_ms', researchDuration, { depth: String(depth), status, source: 'extension' });
+      metrics.increment('research_manager_requests_total', 1, { depth: String(depth), status, source: 'extension' });
       throw error;
     } finally {
       // Always release the run-cap slot — on success, error, or abort (the
@@ -366,6 +370,15 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
 
     const researchers = plan.researchers || [];
     const active = new Set<Promise<void>>();
+    // Set just before each fast-stop throw below. A researcher wedged past the
+    // bounded abort/settle waits is ABANDONED by the stop — its promise settles
+    // later, after the run's single terminal callback has fired (and, on the
+    // tool path, after endResearchSession freed the session state). Its late
+    // failure must then be suppressed: recordResearcherFailure would re-create
+    // the just-freed session entry via getPiState's create-on-read (a
+    // process-lifetime leak on the SDK's random per-run sessionIds), and
+    // onResearcherFailure would violate the no-events-after-terminal contract.
+    let runTerminated = false;
     // Honour MAX_CONCURRENT_RESEARCHERS — prevents resource spikes when a plan has many researchers.
     const maxConcurrent: number = (orchestratorOptions.config as Config)?.MAX_CONCURRENT_RESEARCHERS ?? DEFAULTS.MAX_CONCURRENT_RESEARCHERS;
     const maxFailedResearchers: number = (orchestratorOptions.config as Config)?.MAX_FAILED_RESEARCHERS ?? DEFAULTS.MAX_FAILED_RESEARCHERS;
@@ -406,6 +419,7 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
           Promise.allSettled(active).then(() => undefined),
           () => logger.debug('[ResearchOrchestrationService] Fast-stop: active researchers did not settle within bound; proceeding with stop'),
         );
+        runTerminated = true;
         throw createResearchStopError(sessionId, researchId);
       }
 
@@ -467,6 +481,10 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
           // researcher-executor.ts.
           if (signal?.aborted || isAbortSentinel(errMsg) || container?.isDisposing || errMsg.includes('during container disposal')) {
             logger.debug(`[ResearchOrchestrationService] Researcher ${id} cancelled (aborted).`);
+          } else if (runTerminated) {
+            // Abandoned-by-fast-stop researcher settling AFTER the run's
+            // terminal error — see the runTerminated declaration above.
+            logger.debug(`[ResearchOrchestrationService] Researcher ${id} settled after the run's fast-stop terminal error; suppressing post-terminal failure recording (${errMsg}).`);
           } else {
             logger.error(`[ResearchOrchestrationService] Researcher ${id} failed: ${errMsg}`);
             // Record failure (with its root cause) for stopping logic and for the
@@ -525,6 +543,7 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
           () => logger.debug('[ResearchOrchestrationService] Fast-stop: active researchers did not settle within bound; proceeding with stop'),
         );
 
+        runTerminated = true;
         throw createResearchStopError(sessionId, researchId);
       }
     }

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

@@ -34,6 +34,26 @@ const NO_SOURCES_NOTE =
 const UNVERIFIED_LINKS_NOTE =
   '_None of the links above could be verified: no page fetch succeeded this session and no citation could be matched to retrieved content. They may be inaccurate or invented — check each one before relying on it._';
 
+// Below this many cited sources, a completed report is WEAKLY grounded: it will
+// still read as a fully sourced document, but almost none of its claims can trace to
+// retrieved content — exactly the shape of a run where scrapes mostly failed (bot
+// blocks, resource starvation) or the topic had little real coverage, and the model
+// filled the gaps from its own weights. Observed in production: a depth-1 run whose
+// report cited ONE page shipped with no caveat and fabricated most of its specifics;
+// the calling agent had to detect the degradation itself. The note gives readers
+// (human or agent) the machine-visible signal that was missing.
+const WEAK_GROUNDING_MIN_SOURCES = 3;
+
+function weakGroundingNote(count: number): string {
+  // "cited", not "verified": since the provenance gate was removed (see the
+  // comment in extractGlobalCitations' caller), this count includes citations
+  // the model wrote whose pages were never successfully retrieved — claiming
+  // they were "verified" overstated what the pipeline checked.
+  return `_Grounding notice: only ${count} source${count === 1 ? ' is' : 's are'} cited in this report. ` +
+    'Claims not attributable to the cited source' + (count === 1 ? '' : 's') +
+    ' above should be treated as unverified — cross-check anything load-bearing before relying on it._';
+}
+
 
 /**
  * Redact inline `https?://` tokens in synthesis prose whose URL was NOT retrieved
@@ -382,6 +402,16 @@ export class ResearchSynthesisService implements IService {
         // fabricated source can still reach the user; inline URLs also violate the
         // required format. Verified inline references (in `trustedUrls`) are kept.
         body = redactUnverifiedProseUrls(body, trustedUrls);
+        if (globalCitations.length < WEAK_GROUNDING_MIN_SOURCES) {
+          // The notice goes BEFORE the CITED LINKS header, never after it: anything
+          // trailing the last citation entry is absorbed into that entry's
+          // Description by parseCitations, and quick mode re-parses this exact
+          // string to build knowledge-store entries — a notice placed after the
+          // list polluted the stored description of the final source on precisely
+          // the degraded runs the notice exists to flag.
+          logger.warn(`[ResearchSynthesisService] Report is weakly grounded: only ${globalCitations.length} cited source(s) — appending grounding notice.`);
+          return `${body}\n\n${weakGroundingNote(globalCitations.length)}\n\n${verifiedLinksSection}`;
+        }
         return `${body}\n\n${verifiedLinksSection}`;
       }
       logger.warn('[ResearchSynthesisService] Synthesis missing CITED LINKS - appending verified version');
@@ -393,6 +423,12 @@ export class ResearchSynthesisService implements IService {
       const validIds = new Set(globalCitations.map((c) => c.id));
       let prose = rewriteCitationMarkers(synthesis.trim(), new Map(), (n) => !validIds.has(n));
       prose = redactUnverifiedProseUrls(prose, trustedUrls);
+      if (globalCitations.length < WEAK_GROUNDING_MIN_SOURCES) {
+        // Before the CITED LINKS header for the same parseCitations-absorption
+        // reason as the replace path above.
+        logger.warn(`[ResearchSynthesisService] Report is weakly grounded: only ${globalCitations.length} cited source(s) — appending grounding notice.`);
+        return `${prose}\n\n${weakGroundingNote(globalCitations.length)}\n\n${verifiedLinksSection}`;
+      }
       return `${prose}\n\n${verifiedLinksSection}`;
     }