@lincoln504/pi-research 1.6.5 → 1.6.7

package/src/infrastructure/browser/thread-worker-browser.ts

@@ -136,18 +136,18 @@ export async function initBrowser(): Promise<void> {
         // (consumers install without our lockfile, so a floating range resolves
         // to a newer, broken version):
         //
-        //   • camoufox-js  ^0.10.2  → the two ORIGINAL reasons for this pin have
-        //     both lapsed (camoufox restored Windows assets in v152.0.4-beta.26,
-        //     2026-07-16; and impit's `only-allow pnpm` guard existed only in
-        //     0.13.1/0.14.0), but a THIRD, worse one replaced them. 0.12.0
-        //     requires `better-sqlite3 ^13.0.1`, and better-sqlite3 13 DROPPED
-        //     PREBUILT BINARIES: 12.x installs via `prebuild-install || node-gyp
-        //     rebuild`, 13.x has no install script at all, so npm falls back to
-        //     auto-running `node-gyp rebuild` for its binding.gyp and every
-        //     install needs a full C++ toolchain. Measured: `npm ci` fails
-        //     outright on the Windows CI runner ("could not find a version of
-        //     Visual Studio 2017 or newer"), which is most Windows consumers.
-        //     Upgrading again means checking better-sqlite3 first, not camoufox.
+        //   • camoufox-js  ^0.12.0 (2026-08-30 refresh) → the 0.10.x pin survived
+        //     two refresh cycles on three since-lapsed blockers (Windows assets
+        //     returned in v152.0.4-beta.26, 2026-07-16; impit's `only-allow pnpm`
+        //     guard existed only in 0.13.1/0.14.0; and better-sqlite3 13's changed
+        //     install model). The refresh accepted better-sqlite3 13. MEASURED on
+        //     13.0.3: `prebuilds/` for all eight platform/arch pairs ship INSIDE
+        //     the tarball and load at runtime via node-gyp-build — no install
+        //     script, no toolchain needed on modern npm (≥11.19 skips the
+        //     injected `node-gyp rebuild` that a binding.gyp without an install
+        //     script triggers; it was that needless rebuild, not a missing
+        //     binary, that broke toolchain-less Windows installs). A future bump
+        //     must still check better-sqlite3 first, not camoufox.
         //   • playwright-core  1.60.0 (exact) → playwright-core and the camoufox
         //     binary are one matched Juggler-protocol pair. 1.61 added a
         //     viewport.isMobile field the build REJECTS ("property
@@ -155,13 +155,12 @@ export async function initBrowser(): Promise<void> {
         //     launch below. Corroborated upstream: camoufox-js 0.12.0 declares
         //     `peerDependencies: playwright-core "<1.61.0"`, the same bound this
         //     pin has held by hand.
-        //   • impit  0.13.0 (exact, a direct dep though only camoufox-js uses it)
-        //     → camoufox-js 0.10.2 requires `impit ^0.13.0`, and within that range
-        //     0.13.0 is the only version free of the `preinstall: npx only-allow
-        //     pnpm` guard (an upstream mistake in 0.13.1/0.14.0, dropped again in
-        //     0.14.1) that hard-fails `npm install -g`. The exact pin is also the
-        //     ONLY way to force a version for consumers, since npm `overrides`
-        //     don't propagate to installers of a published package.
+        //   • impit  0.14.4 (exact, a direct dep though only camoufox-js uses it;
+        //     2026-08-30 refresh from 0.13.0) → kept EXACT because it is the only
+        //     way to force a version for consumers: npm `overrides` don't
+        //     propagate to installers of a published package, and impit's
+        //     mid-stream `only-allow pnpm` guard incident (0.13.1/0.14.0) showed
+        //     floating ranges breaking fresh global installs our lockfile masks.
         //
         // What is NOT pinned: the browser BINARY. `camoufox-js fetch` takes no
         // version argument — it walks the GitHub releases newest-first and takes

package/src/knowledge/chunker.ts

@@ -40,6 +40,14 @@ export class Chunker {
     let sentenceExtensions = 0;
     let newlineExtensions = 0;
     let spaceExtensions = 0;
+    // Running count of ``` fences in text[0..start) — fence parity for the
+    // code-block-atomicity check. Maintained incrementally at the bottom of
+    // the loop (each iteration scans only the span of text newly consumed);
+    // the previous text.slice(0, start) rescan per iteration made chunking
+    // O(n²): ~350MB of allocation+regex scanning for a 1MB document, on the
+    // ingest hot path, worst exactly on the largest pages.
+    let fencesBefore = 0;
+    let lastFenceScan = 0;
 
     while (start < text.length) {
       const iterationStart = start;
@@ -49,10 +57,9 @@ export class Chunker {
         let slice = text.slice(start, end);
         let extendedForCodeBlock = false;
         
-        // 0. Code blocks atomicity
-        const textBefore = text.slice(0, start);
-        const codeBlockMatchesBefore = textBefore.match(/```/g);
-        const startsInCodeBlock = codeBlockMatchesBefore && codeBlockMatchesBefore.length % 2 !== 0;
+        // 0. Code blocks atomicity (fence parity from the running counter —
+        // see fencesBefore above).
+        const startsInCodeBlock = fencesBefore % 2 !== 0;
 
         // Hard cap: never extend a chunk beyond 4x targetSize (min 2000 chars) for code blocks.
         // A very large code block (e.g. a package compatibility table) can otherwise
@@ -232,6 +239,17 @@ export class Chunker {
           }
         }
       }
+
+      // Advance the running fence counter over the span this iteration newly
+      // consumed. start only ever moves forward (start-side forward-progress
+      // guard), so scanning [lastFenceScan, start) once keeps fencesBefore
+      // exactly equal to the fence count in text[0..start) that the next
+      // iteration's parity check needs — amortized O(n) across the whole loop.
+      if (start > lastFenceScan) {
+        const newlyConsumed = text.slice(lastFenceScan, start).match(/```/g);
+        if (newlyConsumed) fencesBefore += newlyConsumed.length;
+        lastFenceScan = start;
+      }
     }
 
     const duration = Date.now() - startTime;

package/src/knowledge/embedder-init.ts

@@ -208,6 +208,40 @@ export async function isModelCached(model: string): Promise<boolean> {
 
     const entries = await readdir(onnxDir).catch(() => [] as string[]);
 
+    // External-weights integrity: transformers.js exports most embedding models as a
+    // small graph stub (model.onnx) that references its real weights in a SIBLING
+    // model.onnx_data. An interrupted download can leave EXACTLY the stub without the
+    // weights — every check above passes (the stub is a valid protobuf, config and
+    // tokenizer are present), so this function reported "cached", the loader ran with
+    // allowRemoteModels=false, and transformers failed with "model.onnx_data ... not
+    // found locally" — an error isCorruptModelError did not classify, so no purge and
+    // no re-download: init retried into the same wall until the caller's budget died.
+    // Detect the reference in the graph bytes and require the weights file when it is
+    // present. The scan is bounded to 1MB: a self-contained (internal-weights) model.onnx
+    // is far larger than that, and the reference string lives in the small external-data
+    // layout's protobuf.
+    const onnxPath = path.default.join(onnxDir, 'model.onnx');
+    const onnxStat = await stat(onnxPath).catch(() => null);
+    if (onnxStat && onnxStat.size > 0 && onnxStat.size <= 1024 * 1024) {
+      try {
+        const handle = await import('node:fs/promises');
+        const fh = await handle.default.open(onnxPath, 'r');
+        try {
+          const { buffer, bytesRead } = await fh.read(Buffer.alloc(Math.min(onnxStat.size, 1024 * 1024)), 0, Math.min(onnxStat.size, 1024 * 1024), 0);
+          const referencesExternalWeights = buffer.subarray(0, bytesRead).includes('model.onnx_data');
+          if (referencesExternalWeights && !entries.includes('model.onnx_data')) {
+            return false;
+          }
+        } finally {
+          await fh.close();
+        }
+      } catch {
+        // A read failure here is NOT evidence of a poisoned cache — treat the
+        // verdict as inconclusive and fall through to the historical checks
+        // (the loader-side corrupt classification remains the backstop).
+      }
+    }
+
     // If an external weights file is listed, it must be non-empty — an interrupted
     // download can leave a zero-length model.onnx_data that crashes the ONNX loader.
     const hasExternalWeights = entries.includes('model.onnx_data');
@@ -259,7 +293,13 @@ export function isCorruptModelError(err: unknown): boolean {
     msg.includes('deserialize') ||
     msg.includes('file_length') ||
     msg.includes('protobuf parsing failed') ||
-    msg.includes('invalid protobuf')
+    msg.includes('invalid protobuf') ||
+    // transformers.js local-file-missing: the cache LOOKED complete to isModelCached
+    // but a referenced file (typically external weights, model.onnx_data) is absent —
+    // an interrupted download. Classifying it here routes to purge + one remote
+    // re-download instead of init retrying into the same wall.
+    msg.includes('not found locally') ||
+    msg.includes('local_files_only=true')
   );
 }
 

package/src/knowledge/embedder-utils.ts

@@ -73,6 +73,9 @@ export function isEmbedderUnreachable(err: unknown): boolean {
  * Matched signatures (observed in the wild):
  *   - onnxruntime-node:  "Cannot find module '.../bin/napi-v6/darwin/x64/onnxruntime_binding.node'"
  *   - @lancedb/lancedb:  "Cannot find native binding. npm has a bug related to optional dependencies"
+ *   - @huggingface/transformers (optional dep skipped at install time, #10): the typed
+ *                        TRANSFORMERS_UNAVAILABLE error from transformers-loader.ts, or its
+ *                        raw form "Cannot find package '@huggingface/transformers'"
  *   - jiti-masked module-eval failure of the above surfaces as:
  *                        "KnowledgeStoreService is not a constructor"
  */
@@ -89,8 +92,10 @@ export function isNativeStackUnavailableError(err: unknown): boolean {
   // `err` is already known truthy (guarded above), so no `err &&` here.
   const code = (typeof err === 'object' && 'code' in err) ? String((err as { code?: unknown }).code) : '';
   if (code === 'ERR_DLOPEN_FAILED') return true;
+  // The typed error from transformers-loader.ts — unambiguous by construction.
+  if (code === 'TRANSFORMERS_UNAVAILABLE') return true;
   if ((code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') &&
-      (msg.includes('onnxruntime') || msg.includes('lancedb'))) {
+      (msg.includes('onnxruntime') || msg.includes('lancedb') || msg.includes('@huggingface/transformers'))) {
     return true;
   }
 
@@ -99,6 +104,7 @@ export function isNativeStackUnavailableError(err: unknown): boolean {
     msg.includes('onnxruntime_binding.node') ||
     /cannot find module '[^']*onnxruntime/.test(msg) ||
     /cannot find module '[^']*lancedb/.test(msg) ||
+    /cannot find (?:package|module) ['"]@huggingface[/\\]transformers['"]/i.test(msg) ||
     msg.includes('knowledgestoreservice is not a constructor')
   );
 }

package/src/knowledge/store.ts

@@ -87,6 +87,14 @@ export class KnowledgeStore implements IKnowledgeStore {
   private manifestPath: string;
   private isClosing = false;
   private activeWrites = new Set<Promise<any>>();
+  // Last recorded model/schema migration (persisted in the store manifest).
+  // Compared against the incoming migration target to detect alternating-model
+  // thrash against a shared dbDir (see the alternation warn in openInternal).
+  private lastMigration: { model: string; ts: number } | null = null;
+  // The migration BEFORE lastMigration — detects a RETURN to an earlier model
+  // (A→B→A, the true ping-pong signature) while leaving a deliberate onward
+  // change (A→B→C) quiet. Persisted alongside lastMigration.
+  private prevMigration: { model: string; ts: number } | null = null;
   // LanceDB table version at the last successful FTS rebuild. rebuildFtsIndex() skips
   // when the version is unchanged: a research run that committed no new transactions
   // would otherwise create a fresh FTS index (and a new table version) on every cleanup,
@@ -141,6 +149,12 @@ export class KnowledgeStore implements IKnowledgeStore {
           this.tableName = manifest.activeTableName;
           logger.debug(`[store] Loaded active table name from manifest: ${this.tableName}`);
         }
+        if (manifest.lastMigration && typeof manifest.lastMigration.model === 'string') {
+          this.lastMigration = { model: manifest.lastMigration.model, ts: Number(manifest.lastMigration.ts) || 0 };
+        }
+        if (manifest.prevMigration && typeof manifest.prevMigration.model === 'string') {
+          this.prevMigration = { model: manifest.prevMigration.model, ts: Number(manifest.prevMigration.ts) || 0 };
+        }
       }
     } catch (err) {
       logger.warn('[store] Failed to load manifest, using default table name:', err);
@@ -151,7 +165,16 @@ export class KnowledgeStore implements IKnowledgeStore {
   private async saveManifest(): Promise<boolean> {
     const tempPath = `${this.manifestPath}.tmp`;
     try {
-      const content = JSON.stringify({ activeTableName: this.tableName }, null, 2);
+      const content = JSON.stringify({
+        activeTableName: this.tableName,
+        // Record of the two most recent model/schema migrations. Read back on open
+        // to detect ALTERNATION (two configurations sharing this dbDir each
+        // migrating the table back and forth) — previously that thrash was
+        // invisible outside a per-open WARN line, while every alternation
+        // served an empty store.
+        lastMigration: this.lastMigration,
+        prevMigration: this.prevMigration,
+      }, null, 2);
       await fsPromises.writeFile(tempPath, content, { encoding: 'utf-8', mode: 0o600 });
       await fsPromises.rename(tempPath, this.manifestPath);
       return true;
@@ -166,6 +189,14 @@ export class KnowledgeStore implements IKnowledgeStore {
 
   async open(): Promise<void> {
     if (this.db) return;
+    // close() is irreversible in this class (isClosing latches the operation
+    // no-op path), so an open() after it must not "succeed" and hand back a
+    // zombie whose every operation silently no-ops — the service layer always
+    // constructs FRESH components after dispose, and this makes any deviation
+    // fail loud at the call site instead of as mysterious empty results.
+    if (this.isClosing) {
+      throw new Error('KnowledgeStore.open() called after close() — construct a fresh store instead.');
+    }
 
     // Coalesce concurrent opens in-process. withLock (when provided) is a
     // cross-process FILE lock, not an in-process mutex — and when it's absent there
@@ -286,6 +317,42 @@ export class KnowledgeStore implements IKnowledgeStore {
                 throw new Error(errorMsg, { cause: err });
               }
             }
+
+            // Alternation detector: the PREVIOUS migration moved this shared dbDir
+            // to a model that is NOT the one being migrated to now — the A→B→A
+            // thrash signature of two configurations (EMBEDDING_MODEL is
+            // machine-scoped; one shell with an override is enough) fighting over
+            // one table. Each alternation serves an EMPTY store and leans on the
+            // newest backup for the other model's data; make that LOUD and
+            // countable instead of a per-open WARN nobody correlates.
+            const prev = this.lastMigration;
+            const twoAgo = this.prevMigration;
+            // Thrash = RETURN to the model from two migrations ago (A→B→A):
+            // the ping-pong of two configurations sharing this dbDir. A first
+            // migration (no history) and a deliberate onward change (A→B→C)
+            // stay quiet; with two configs fighting, every leg after the first
+            // round-trip IS a bounce-back, so the real case still fires on
+            // every subsequent leg. (The prev.model check is kept even though a
+            // real migration to a different target implies it — defense in
+            // depth against a hand-edited manifest.)
+            const isThrash =
+              prev !== null && prev.model !== this.options.modelName &&
+              twoAgo !== null && twoAgo.model === this.options.modelName;
+            if (isThrash) {
+              const ageHours = Math.max(0, Math.round((Date.now() - twoAgo!.ts) / 3_600_000));
+              logger.warn(
+                `[store] MODEL ALTERNATION on the shared table: '${this.options.modelName}' was already here ~${ageHours}h ago ` +
+                `(migrations: '${twoAgo!.model}' → '${prev!.model}' → back to '${this.options.modelName}'). ` +
+                `Two configurations sharing this dbDir are thrashing it — each open serves an empty store until re-ingest. ` +
+                `Fix the EMBEDDING_MODEL drift, or give each model its own dbDir.`,
+              );
+              metrics.increment('knowledge_store_model_migration_total', 1, { alternation: 'true' });
+            } else {
+              metrics.increment('knowledge_store_model_migration_total', 1, { alternation: 'false' });
+            }
+            this.prevMigration = prev;
+            this.lastMigration = { model: this.options.modelName, ts: Date.now() };
+            // Persisted by the saveManifest() later in openInternal.
           }
         } catch (schemaErr) {
           // A migration failure is fatal — re-throw so the caller learns the store

package/src/knowledge/transformers-loader.ts

@@ -18,14 +18,71 @@
  * (isNativeStackUnavailableError) and degrades the store to DISABLED. Help, version,
  * status, and browser-only research then work with no binding present.
  *
+ * The package itself is an OPTIONAL dependency (it can be skipped entirely at
+ * install time when its native chain cannot build — sharp's platform binary is
+ * the historic offender, #10). A genuinely absent module is therefore a SUPPORTED
+ * state, not a crash: getTransformers() reclassifies it as a typed
+ * TRANSFORMERS_UNAVAILABLE error carrying remediation, which the knowledge store's
+ * native-unavailable classifier memoizes as DISABLED instead of re-running the
+ * init + backoff storm on every store touch. A transformers-INTERNAL load failure
+ * (its own onnxruntime import, a corrupt install) is re-thrown untouched — that is
+ * the pre-existing native-stack classification's job.
+ *
  * Modules that need transformers *types* should keep `import type { … } from
  * '@huggingface/transformers'` (type imports are erased and never hoisted); only
  * runtime value access (pipeline, env, …) must go through getTransformers().
  */
 
+/** Error.code on the typed error thrown when the optional module is not installed. */
+export const TRANSFORMERS_UNAVAILABLE = 'TRANSFORMERS_UNAVAILABLE';
+
+/**
+ * True when `err` is Node's "the module itself is not installed" rejection for
+ * OUR specifier — i.e. the optional dependency was skipped at install time.
+ * Deliberately narrow: a transformers-INTERNAL missing module (onnxruntime
+ * binding, corrupt install) resolves to a DIFFERENT file path and must stay
+ * unclassified here so the native-stack classifier handles it instead.
+ */
+export function isTransformersMissingError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const code = 'code' in err ? String((err as { code?: unknown }).code) : '';
+  const msg = err instanceof Error ? err.message : String(err);
+  // Node's ESM form is "Cannot find package '@huggingface/transformers' imported
+  // from …"; the CJS/child-process form is "Cannot find module '…'".
+  return (
+    code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND'
+  ) && /@huggingface[/\\]transformers/.test(msg);
+}
+
+/**
+ * Build the typed, remediation-carrying error for an absent optional package.
+ * Exported for tests; the code is what isNativeStackUnavailableError() keys on.
+ */
+export function transformersUnavailableError(cause: unknown): Error {
+  const err = new Error(
+    "Optional dependency '@huggingface/transformers' is not installed, so local embeddings are unavailable. "
+    + 'npm skips this package when its native image chain cannot install (most often a failing sharp platform binary). '
+    + 'The knowledge store runs without embeddings until it is present — reinstall this package to re-resolve its '
+    + 'optional dependencies (pi install npm:@lincoln504/pi-research), or install it directly '
+    + '(npm install @huggingface/transformers).',
+    { cause },
+  );
+  (err as { code?: string }).code = TRANSFORMERS_UNAVAILABLE;
+  return err;
+}
+
 let _transformers: typeof import('@huggingface/transformers') | undefined;
 
 /** Resolve the transformers module, memoizing after the first load. */
 export async function getTransformers(): Promise<typeof import('@huggingface/transformers')> {
-  return (_transformers ??= await import('@huggingface/transformers'));
+  if (_transformers) return _transformers;
+  try {
+    _transformers = await import('@huggingface/transformers');
+  } catch (err) {
+    if (isTransformersMissingError(err)) {
+      throw transformersUnavailableError(err);
+    }
+    throw err;
+  }
+  return _transformers;
 }

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

@@ -158,7 +158,10 @@ export function createResearchObserver(
     },
 
     onPlanningSuccess: (plan) => {
-      updateSliceStatus(panelState, 'coord', 'ready', debouncedRefresh);
+      // A fallback plan means the model's planning output was unusable and the engine
+      // degraded to a single researcher — the user asked for deep research and got a
+      // shallow one. Say so in the status line instead of presenting it as 'ready'.
+      updateSliceStatus(panelState, 'coord', plan.fallback ? 'fallback — planning failed' : 'ready', debouncedRefresh);
       completeSlice(panelState, 'coord');
       const unitsPerResearcher = getUnitsPerResearcher(undefined, ctx.cachingActive);
       const count = plan.researchers?.length || 0;

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

@@ -17,7 +17,7 @@ import {
 import type {
   ResearchObserver,
 } from '../core/interfaces/observer-interfaces.ts';
-import { HeadlessObserver, makeSafeObserver, type HeadlessObserverOptions } from './headless-observer.ts';
+import { HeadlessObserver, makeSafeObserver, isHeadlessObserverBag, type HeadlessObserverOptions } from './headless-observer.ts';
 import {
   ServiceNames,
   type IResearchOrchestration,
@@ -63,7 +63,7 @@ export class DeepResearchOrchestrator {
     
     // Resolve observer: if options were provided instead of an instance, create the instance.
     // Either way, wrap it so a throwing observer callback can never fail the run.
-    if (options.observer && typeof (options.observer as any).onProgress === 'function' && !(options.observer instanceof HeadlessObserver)) {
+    if (options.observer && isHeadlessObserverBag(options.observer)) {
        this.observer = makeSafeObserver(new HeadlessObserver(options.observer as HeadlessObserverOptions));
     } else {
        this.observer = options.observer ? makeSafeObserver(options.observer as ResearchObserver) : undefined;
@@ -237,7 +237,7 @@ export class DeepResearchOrchestrator {
         // 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);
+          await orchestrationService.checkHealth(this.currentRound, researchId, ctx, signal);
         }
 
         // 1. Update/Generate Plan

package/src/orchestration/headless-observer.ts

@@ -75,6 +75,39 @@ export function makeSafeObserver<T extends object>(observer: T): T {
   }) as T;
 }
 
+/**
+ * True when `observer` is a HeadlessObserverOptions BAG — a bare
+ * `{ onProgress }` callback object — rather than a full ResearchObserver.
+ *
+ * Detection is by ABSENCE of a typed lifecycle method, not merely presence of
+ * onProgress: a full observer that ALSO exposes onProgress (a subclass, an
+ * EventEmitter-style adapter, a proxy) would otherwise be silently demoted to
+ * a bag, funnelling every event through onProgress and losing every typed
+ * callback. Any typed method (onStart/onRoundStart/onResearcherStart/…)
+ * marks the object a full observer; HeadlessObserver itself is exempt (it
+ * emits through onProgress but is already the wrapped form).
+ */
+export function isHeadlessObserverBag(observer: unknown): boolean {
+  if (!observer || typeof observer !== 'object') return false;
+  if (observer instanceof HeadlessObserver) return false;
+  const o = observer as Record<string, unknown>;
+  if (typeof o['onProgress'] !== 'function') return false;
+  // The full optional surface of ResearchObserver (observer-interfaces.ts).
+  // Anything typed marks the object a full observer; only a bare { onProgress }
+  // bag falls through to demotion.
+  const lifecycleMethods = [
+    'onStart', 'onRunQueued',
+    'onPlanningStart', 'onPlanningProgress', 'onPlanningTokens', 'onPlanningSuccess',
+    'onRoundStart',
+    'onSearchStart', 'onSearchProgress', 'onSearchComplete',
+    'onResearcherStart', 'onResearcherProgress', 'onResearcherTokensHint', 'onResearcherComplete', 'onResearcherFailure',
+    'onToolResult',
+    'onEvaluationStart', 'onEvaluationProgress', 'onEvaluationTokens', 'onEvaluationDecision',
+    'onSynthesisStart', 'onComplete', 'onError', 'onTokensConsumed',
+  ];
+  return !lifecycleMethods.some(m => typeof o[m] === 'function');
+}
+
 export class HeadlessObserver implements ResearchObserver {
   constructor(private options: HeadlessObserverOptions = {}) {}
 

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

@@ -21,8 +21,9 @@ import { ensureAssistantResponse, parseCitations, isAnalysisFreeSynthesis, synth
 import { getMaxScrapeBatches, resolveExcludedTools, QUICK_THIN_REPORT_NOTICE } 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 { HeadlessObserver, makeSafeObserver, isHeadlessObserverBag, type HeadlessObserverOptions } from './headless-observer.ts';
 import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
+import { raceWithSignal } from '../utils/cancellation.ts';
 import { ServiceNames, type IKnowledgeStoreService, type IResearchSynthesisService, type IResearchOrchestration } from '../core/service-interfaces.ts';
 import type { ResearchSessionService } from './research-session-service.ts';
 import { normalizeUrl, registerScrapedLinks, getCachedScrapedContent } from '../utils/shared-links.ts';
@@ -54,7 +55,7 @@ export class QuickResearchOrchestrator {
 
     // Resolve observer: if options were provided instead of an instance, create the instance.
     // Either way, wrap it so a throwing observer callback can never fail the run.
-    if (options.observer && typeof (options.observer as any).onProgress === 'function' && !(options.observer instanceof HeadlessObserver)) {
+    if (options.observer && isHeadlessObserverBag(options.observer)) {
        this.observer = makeSafeObserver(new HeadlessObserver(options.observer as HeadlessObserverOptions));
     } else {
        this.observer = options.observer ? makeSafeObserver(options.observer as ResearchObserver) : undefined;
@@ -86,7 +87,15 @@ export class QuickResearchOrchestrator {
           process.env['PI_RESEARCH_SKIP_HEALTHCHECK'] === 'true';
         const health = skipHealthcheck
           ? { success: true as boolean, error: undefined as string | undefined, components: [] as Array<{ component?: string; healthy?: boolean; error?: string }> }
-          : await runHealthCheck({ ctx });
+          // Abort-aware: without the race, a cancel landing inside the probe
+          // waits out the FULL healthcheck budget before the run notices.
+          // The abandoned probe drains in the background (its own timeouts
+          // bound it); the throw lands in the outer catch, which classifies
+          // via signal.aborted as a cancellation, not a fault.
+          : await raceWithSignal(runHealthCheck({ ctx }), signal);
+        if (health === undefined) {
+          throw new Error('Research aborted');
+        }
         if (skipHealthcheck) {
           logger.debug('[QuickOrchestrator] Pre-flight healthcheck skipped (PI_RESEARCH_SKIP_HEALTHCHECK); relying on per-task timeouts.');
         }
@@ -512,6 +521,11 @@ export class QuickResearchOrchestrator {
         // exactly once (the inner catch sets the flag for its own scope).
         if (!terminalCallbackFired) {
           const aborted = signal?.aborted === true;
+          // Audit L4: the early-throw path (healthcheck/session-registration) fired
+          // the terminal callbacks but recorded no run metric — the session counter
+          // under-counted exactly these failures. Mirrors the inner catch's labels.
+          metrics.observe('research_session_duration_ms', Date.now() - sessionStart, { mode: 'quick', complexity: '0', status: aborted ? 'cancelled' : 'error' });
+          metrics.increment('research_sessions_total', 1, { mode: 'quick', complexity: '0', status: aborted ? 'cancelled' : 'error' });
           if (!aborted) {
             observer?.onResearcherFailure?.('quick', error instanceof Error ? error.message : String(error));
           }

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

@@ -38,6 +38,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 { raceWithSignal } from '../utils/cancellation.ts';
 import { isAbortSentinel, boundSessionAbort } from './abort-utils.ts';
 import type { ResearchSessionService } from './research-session-service.ts';
 import { QuickResearchOrchestrator } from './quick-research-orchestrator.ts';
@@ -163,10 +164,18 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
           (observer as { onError?: (e: Error) => void } | undefined)?.onError?.(err as Error);
         } catch { /* observer isolation */ }
       }
-      if (err instanceof ResearchRunCapacityError) throw err; // capacity exhausted → fail fast
+      if (err instanceof ResearchRunCapacityError) {
+        // Audit L1: a capacity-refused run was invisible to run-level metrics —
+        // the rethrow happened before the success/error accounting ran.
+        metrics.increment('research_manager_requests_total', 1, { depth: String(depth), status: 'capacity_refused', source: 'extension' });
+        throw err; // capacity exhausted → fail fast
+      }
       // A cancel while queueing for a slot must stay cancelled. Fail-open here would
       // start the very run the user just aborted.
-      if (err instanceof Error && err.name === 'AbortError') throw err;
+      if (err instanceof Error && err.name === 'AbortError') {
+        metrics.increment('research_manager_requests_total', 1, { depth: String(depth), status: 'cancelled', source: 'extension' });
+        throw err;
+      }
       logger.warn(`[ResearchOrchestrationService] Run-cap unavailable, proceeding without it: ${err instanceof Error ? err.message : String(err)}`);
     }
 
@@ -682,7 +691,7 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
    * @param round - Current round number
    * @param ctx - Optional extension context for container isolation
    */
-  async checkHealth(round: number, _researchId?: string, ctx?: any): Promise<void> {
+  async checkHealth(round: number, _researchId?: string, ctx?: any, signal?: AbortSignal): Promise<void> {
     // Round 1 is skipped because there is nothing to diagnose yet — the pool was
     // built moments earlier and no work has run through it. A consequence worth
     // stating: a complexity-1 run has exactly ONE research round, so it now never
@@ -692,6 +701,10 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
     // does not use. This check is advisory logging; a quick run loses nothing but
     // that cost.
     if (round <= 1) return;
+    if (signal?.aborted) {
+      logger.debug(`[ResearchOrchestrationService] Health check at Round ${round} skipped (run already aborted).`);
+      return;
+    }
 
     try {
       const container = tryGetServiceContainerFromCtx(ctx);
@@ -702,7 +715,17 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
         registry = healthRegistry;
       }
 
-      const health = await registry.runAll();
+      // Abort-aware: a user cancel landing inside a probe previously waited out
+      // the FULL probe budget (105s observed) — the one await on this path that
+      // ignored the run signal. The abandoned probe keeps draining in the
+      // background (probes carry their own timeouts and are safe to leave
+      // running); its dropped result costs nothing because the next abort-aware
+      // await in the run loop raises the cancel anyway.
+      const health = await raceWithSignal(registry.runAll(), signal);
+      if (health === undefined) {
+        logger.debug(`[ResearchOrchestrationService] Health check at Round ${round} abandoned (run signal fired).`);
+        return;
+      }
 
       if (health.status === 'healthy') {
         logger.debug(`[ResearchOrchestrationService] Health status at Round ${round}: [OK] All systems operational`);