@lincoln504/pi-research 1.6.5 → 1.6.6

package/src/core/planning-service.ts

@@ -23,12 +23,12 @@ import { recordLlmUsage } from '../utils/llm-usage.ts';
 import { normalizeCitations } from '../utils/citation-utils.ts';
 import { lastCitedLinksHeader } from '../utils/text-utils.ts';
 import { repairJsonWithLlm } from './llm/agentic-repair.ts';
-import { buildSafeOptions, validateAndExtractText } from './llm/llm-utils.ts';
+import { buildSafeOptions, validateAndExtractText, buildConstrainedSubmitTool, completeSimpleStructured } from './llm/llm-utils.ts';
 import { safeGetApiKeyAndHeaders } from './llm/model-registry-factory.ts';
 import { withTimeout } from './llm/llm-timeout.ts';
 import { retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
 import { getConfig, type Config } from '../config.ts';
-import type { Model } from '@earendil-works/pi-ai';
+import type { Model, Tool } from '@earendil-works/pi-ai';
 import { DEFAULT_MODEL_CONTEXT_WINDOW } from '../constants.ts';
 import { deriveCoverageDigest, formatDigestsForRouter } from '../utils/coverage-digest.ts';
 import {
@@ -182,8 +182,11 @@ export function partitionCorpus<T>(
  * leave the prior (still-running) stream orphaned and billed, and would multiply a multi-minute
  * wait. A timeout instead degrades straight to the fallback plan (see the catch blocks, which
  * treat "timed out" as degradable). A deliberate cancellation is never retried — detected by
- * AbortSignal state / AbortError name, not by the message (withTimeout emits the same "cancelled
- * or timed out" wording for a user-abort and a real timeout, and abortableDelay is the backstop).
+ * AbortSignal state / AbortError name, not by the message: the withTimeout imported here is
+ * llm-timeout's, whose timeout rejection reads "LLM call timed out after Nms (label)" while a
+ * user abort surfaces as the underlying fetch's AbortError — two DIFFERENT shapes, unlike the
+ * same-named withTimeout in web-research/retry-utils.ts (whose wording this comment used to
+ * describe). Rename candidate if these two helpers ever converge.
  *
  * Exported for direct unit testing of the abort/timeout guards.
  */
@@ -419,6 +422,18 @@ export class PlanningService implements IPlanningService {
 
     const userMessage = `Generate the initial research plan for: "${query}"`;
 
+    // Structured-output path: offer a schema-constrained submit tool (pi-ai
+    // constrainedSampling, strict 'prefer'). Where the provider supports strict
+    // json_schema the plan arrives schema-exact with no parse/repair round-trip;
+    // everywhere else it degrades to a plain tool call, and a text answer flows
+    // into the existing parse/repair pipeline unchanged — never worse than today.
+    const submitPlanTool = buildConstrainedSubmitTool(
+      'submit_plan',
+      'Submit the complete research plan as structured arguments.',
+      PlanningResponseSchemaAsTSchema,
+    );
+    const toolInstruction = `\n\nRespond by calling the ${submitPlanTool.name} tool with the plan as its arguments.`;
+
     try {
       const authResult = await safeGetApiKeyAndHeaders(modelRegistry, model);
       if (!authResult.ok) {
@@ -434,21 +449,27 @@ export class PlanningService implements IPlanningService {
       // malformed JSON (a different failure) and would otherwise be re-paid on every attempt.
       const { response, responseText } = await retryWithBackoff(
         async () => {
-          const response = await withTimeout(
-            completeSimple(model, {
+          const structured = await withTimeout(
+            completeSimpleStructured(model, {
               systemPrompt: populatedPrompt,
               messages: [
-                { role: 'user', content: [{ type: 'text', text: userMessage }], timestamp: Date.now() },
+                { role: 'user', content: [{ type: 'text', text: userMessage + toolInstruction }], timestamp: Date.now() },
               ],
-            }, buildSafeOptions(model, {
+            }, submitPlanTool, buildSafeOptions(model, {
               apiKey: authResult.apiKey || '',
               headers: authResult.headers,
               signal,
               sessionId,
-            }, config.PLANNING_MAX_TOKENS, config.LLM_THINKING_LEVEL)),
+            }, config.PLANNING_MAX_TOKENS, config.LLM_THINKING_LEVEL), 'Coordinator'),
             llmTimeout, 'coordinator-generatePlan',
           );
-          const responseText = validateAndExtractText(response, 'Coordinator');
+          const response = structured.response;
+          // A tool call's arguments are already an object: re-serialize so they
+          // flow through the SAME parse → coerce → validate (→ repair) pipeline;
+          // on a text answer this is byte-identical to the previous behavior.
+          const responseText = structured.kind === 'toolCall'
+            ? JSON.stringify(structured.args)
+            : structured.text;
           return { response, responseText };
         },
         {
@@ -464,12 +485,30 @@ export class PlanningService implements IPlanningService {
       // Track usage once, on the successful attempt (failed attempts throw before here).
       recordLlmUsage(model, (response as any).usage, { component: 'coordinator', complexity, observer });
 
+      // Truncation is the #1 cause of a malformed plan: a response that hit the
+      // output-token cap ends mid-JSON no matter how well it started. Log the cap
+      // hit here so the malformed-JSON warning below is diagnosable from the log
+      // (stopReason 'length' is otherwise dropped — validateAndExtractText only
+      // inspects 'error').
+      if (response.stopReason === 'length') {
+        logger.warn(
+          `[PlanningService] Plan response hit the output-token cap (stopReason 'length', maxTokens ${config.PLANNING_MAX_TOKENS}); output is likely truncated mid-JSON`
+        );
+      }
+
       // Extract and validate JSON
       let plan: ResearchPlan | null = null;
       try {
         plan = this.parseJsonPlan(responseText);
-      } catch {
-        logger.warn('[PlanningService] Initial plan JSON malformed, attempting agentic repair');
+      } catch (err) {
+        // The thrown error carries the parse/validation detail and a head preview;
+        // stopReason + the response TAIL are the missing forensics — truncation leaves
+        // the JSON dangling at the END of the text, which no head preview shows.
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.warn(
+          `[PlanningService] Initial plan JSON malformed (stopReason '${response.stopReason}'), attempting agentic repair. ` +
+          `Parse error: ${reason}. Response tail: ${JSON.stringify(responseText.slice(-160))}`
+        );
         const repaired = await repairJsonWithLlm<ResearchPlan>(
             responseText,
             completeSimple,
@@ -483,6 +522,7 @@ export class PlanningService implements IPlanningService {
                 sessionId,
                 maxTokens: config.PLANNING_MAX_TOKENS,
                 thinkingLevel: config.LLM_THINKING_LEVEL,
+                timeoutMs: config.LLM_TIMEOUT_MS,
                 onUsage: (rawUsage) => recordLlmUsage(model, rawUsage, { component: 'coordinator', complexity, observer }),
             }
         );
@@ -733,6 +773,17 @@ export class PlanningService implements IPlanningService {
       const responseText = isRouter
         ? await (() => {
             const routerMessage = buildRouterMessage(...this.buildRouterEvidence(options, round), runContext);
+            // Same structured-output pattern as generatePlan: the router's output
+            // is a structured JSON delegate plan (validated by the same
+            // parseJsonPlan), so offer the constrained submit tool and fall back
+            // to the text pipeline when the model answers in prose.
+            const submitRoutingTool = buildConstrainedSubmitTool(
+              'submit_routing_decision',
+              // Audit LOW: this description is offered verbatim on EVERY delegation
+              // round — the hard-coded "round-2" misdescribed rounds 3, 4, … N.
+              `Submit the updated round-${round} routing plan as structured arguments.`,
+              PlanningResponseSchemaAsTSchema,
+            );
             // The router carries no reduce mechanism the way synthesizeCorpus does — a
             // routing decision made from PARTITIONED evidence isn't naturally mergeable
             // the way synthesis prose is, and this call's output is a structured JSON
@@ -757,10 +808,11 @@ export class PlanningService implements IPlanningService {
             return this.callLead({
               ...callOptions,
               systemPrompt: populate(''),
-              userMessage: routerMessage,
+              userMessage: routerMessage + `\n\nRespond by calling the ${submitRoutingTool.name} tool with the updated plan as its arguments.`,
               maxTokens: ROUTER_MAX_TOKENS,
               component: 'router',
               label: 'router-updatePlanForRound',
+              submitTool: submitRoutingTool,
             });
           })()
         : await this.synthesizeCorpus({ ...callOptions, reports, runContext, populate });
@@ -769,8 +821,15 @@ export class PlanningService implements IPlanningService {
       let plan: ResearchPlan | null = null;
       try {
           plan = this.parseJsonPlan(responseText);
-      } catch {
-        logger.warn(`[PlanningService] ${role} JSON malformed, attempting agentic repair`);
+      } catch (err) {
+        // Same forensics as the initial-plan site; the response object itself is not
+        // in scope here (callLead/synthesizeCorpus return text only), but callLead
+        // already warned if that call hit its output-token cap.
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.warn(
+          `[PlanningService] ${role} JSON malformed, attempting agentic repair. ` +
+          `Parse error: ${reason}. Response tail: ${JSON.stringify(responseText.slice(-160))}`
+        );
         const repaired = await repairJsonWithLlm<ResearchPlan>(
             responseText,
             completeSimple,
@@ -784,6 +843,7 @@ export class PlanningService implements IPlanningService {
                 sessionId,
                 maxTokens: isRouter ? ROUTER_MAX_TOKENS : config.SYNTHESIS_MAX_TOKENS,
                 thinkingLevel: config.LLM_THINKING_LEVEL,
+                timeoutMs: config.LLM_TIMEOUT_MS,
                 onUsage: (rawUsage) => recordLlmUsage(model, rawUsage, { component: role, complexity, observer }),
             }
         );
@@ -1024,11 +1084,40 @@ export class PlanningService implements IPlanningService {
     maxTokens: number;
     component: string;
     label: string;
+    /** Optional structured-output tool; when set the call offers it and stringifies tool-call args as the text. */
+    submitTool?: Tool;
   }): Promise<string> {
     const { model, signal, config, complexity, observer, label } = args;
 
     const { response, responseText } = await retryWithBackoff(
       async () => {
+        // Structured path: offer the caller's submit tool (constrained where the
+        // provider supports it) and unify both outcomes into the text contract
+        // this method has always had — tool-call args re-serialized through the
+        // SAME downstream parse/validate/repair, text passed through untouched.
+        if (args.submitTool) {
+          const structured = await withTimeout(
+            completeSimpleStructured(model, {
+              systemPrompt: args.systemPrompt,
+              messages: [
+                { role: 'user', content: [{ type: 'text', text: args.userMessage }], timestamp: Date.now() },
+              ],
+            }, args.submitTool, buildSafeOptions(model, {
+              apiKey: args.apiKey,
+              headers: args.headers,
+              signal,
+              sessionId: args.sessionId,
+            }, args.maxTokens, config.LLM_THINKING_LEVEL), label),
+            config.LLM_TIMEOUT_MS, label,
+          );
+          const responseText = structured.kind === 'toolCall'
+            ? JSON.stringify(structured.args)
+            : structured.text;
+          if (structured.response.stopReason === 'length') {
+            logger.warn(`[PlanningService] ${label} response hit the output-token cap (stopReason 'length', maxTokens ${args.maxTokens}); output is likely truncated`);
+          }
+          return { response: structured.response, responseText };
+        }
         const response = await withTimeout(
           completeSimple(model, {
             systemPrompt: args.systemPrompt,
@@ -1044,6 +1133,12 @@ export class PlanningService implements IPlanningService {
           config.LLM_TIMEOUT_MS, label,
         );
         const responseText = validateAndExtractText(response, label);
+        // A cap hit here means the router decision / synthesis pass was cut mid-output
+        // (often mid-JSON) — surface it so a downstream malformed-JSON warning has its
+        // cause in the log instead of a silent stopReason drop.
+        if (response.stopReason === 'length') {
+          logger.warn(`[PlanningService] ${label} response hit the output-token cap (stopReason 'length', maxTokens ${args.maxTokens}); output is likely truncated`);
+        }
         return { response, responseText };
       },
       {

package/src/core/planning-utils.ts

@@ -214,6 +214,9 @@ export function buildFallbackCoordinatorPlan(serviceName: string, _rawText: stri
   logger.warn(`[${serviceName}] Coordinator fallback: single researcher for "${query.slice(0, 80)}"`);
   return {
     action: 'delegate',
+    // Marks this as engine-generated after unusable model output, so UI surfaces can
+    // say "degraded" instead of presenting one researcher as the model's considered plan.
+    fallback: true,
     researchers: [{ id: '1', name: 'General Researcher', goal: `Research the following query comprehensively: ${query}`, queries }],
     allQueries: queries,
   };

package/src/core/service-registry.ts

@@ -114,9 +114,9 @@ export class ServiceContainer {
   private services: Map<string, ServiceRegistration<any>> = new Map();
   private dependencies: Map<string, Set<string>> = new Map();
   public isDisposing: boolean = false;
-  // The single in-flight disposeAll() run, so concurrent disposeAll()/reset() calls
-  // coalesce onto (and AWAIT) it rather than a second caller observing "disposed" while
-  // teardown is still running, or reset() throwing mid-disposal.
+  // The single in-flight disposeAll() run. Only reset() JOINS it (awaiting teardown
+  // rather than throwing mid-disposal — the Windows CI teardown fix); a concurrent
+  // second disposeAll() returns immediately without awaiting (see disposeAll).
   private _disposalPromise: Promise<void> | null = null;
   public isReady: boolean = false;
   public cwd: string = process.cwd();
@@ -489,9 +489,11 @@ export class ServiceContainer {
   async disposeAll(): Promise<void> {
     // Synchronous re-entrancy guard: isDisposing is set as _runDisposeAll's first
     // statement (before any await), so a service whose dispose() re-enters disposeAll()
-    // gets a safe no-op instead of recursing. Also publish the in-flight run as
-    // _disposalPromise so reset() (a separate, non-re-entrant caller) can AWAIT the
-    // teardown instead of throwing on the race — the Windows CI teardown fix.
+    // gets a safe no-op instead of recursing OR deadlocking (awaiting its own teardown).
+    // CONTRACT (verbatim, matches the code): a concurrent SECOND disposeAll() caller
+    // also returns immediately WITHOUT awaiting the in-flight teardown — only reset()
+    // joins it via _disposalPromise. Any caller that must observe "teardown complete"
+    // before acting should call reset(), or await container._disposalPromise explicitly.
     if (this.isDisposing) return;
     this._disposalPromise = this._runDisposeAll().finally(() => { this._disposalPromise = null; });
     return this._disposalPromise;

package/src/index.ts

@@ -12,6 +12,7 @@ import { createResearchTool, createHealthTool } from './tool.ts';
 import { createResearchKnowledgeSearchTool } from './tools/research-knowledge-search.ts';
 import { logger } from './logger.ts';
 import { checkPiCompatibility } from './core/pi-version.ts';
+import { checkPiAiSkew } from './core/pi-ai-skew.ts';
 import { randomUUID } from 'node:crypto';
 import { shutdownManager } from './utils/shutdown-manager.ts';
 import { healthRegistry } from './healthcheck/index.ts';
@@ -114,6 +115,19 @@ export default async function (pi: ExtensionAPI) {
     logger.warn(compat.message);
   }
 
+  // The gate above classifies the HOST version but cannot see the copies THIS
+  // extension resolves from its own node_modules — the 2026-08-30 incident
+  // (host 0.84.4 vs extension-resolved pi-ai 0.84.2) passed it as 'ok' while
+  // every researcher died at provider load. Detect that skew here and refuse
+  // to start with the actual remediation instead.
+  const skew = checkPiAiSkew();
+  if (skew.fatal) {
+    throw new Error(skew.message ?? '[pi-research] pi-ai version skew.');
+  }
+  if (skew.message) {
+    logger.warn(skew.message);
+  }
+
   // Re-register the beforeExit safety net (deactivate() strips event listeners during reload).
   // This ensures the ONNX pipeline is disposed even after extension reloads.
   registerBeforeExitSafetyNet();

package/src/infrastructure/browser/config.ts

@@ -44,13 +44,12 @@ function getWindowsCamoufoxDir(): string {
  * camoufox-js (getBrowserEnv, scripts/setup.cjs) so that install and lookup
  * cannot disagree.
  *
- * CAVEAT, deliberate: the pinned camoufox-js (0.10.x — see
- * thread-worker-browser.ts for why it cannot move yet) hardcodes
- * `userCacheDir("camoufox")` and honours NEITHER variable, so on the shipped
- * pin a custom location still only relocates lookup and the underlying bug
- * remains. This plumbing is correct and inert rather than wrong: it starts
- * working the moment the pin can advance, and costs nothing until then. Until
- * that happens, treat a custom browser directory as unsupported.
+ * HISTORY: camoufox-js <0.12.0 hardcoded `userCacheDir("camoufox")` and
+ * honoured NEITHER variable, which made this plumbing deliberately inert for
+ * two pin cycles. The 0.12.0 refresh (2026-08-30) honours CAMOUFOX_INSTALL_DIR
+ * again, so a custom location now relocates the install itself, not just our
+ * lookup — the two can no longer disagree via version skew, but keep the dual
+ * export (install + lookup) so they can never drift apart in future.
  */
 function getCustomCamoufoxDir(): string | undefined {
     return process.env['CAMOUFOX_INSTALL_DIR'] || process.env['PLAYWRIGHT_BROWSERS_PATH'] || undefined;

package/src/infrastructure/browser/ensure-browser.ts

@@ -27,12 +27,19 @@ import { tmpdir } from 'node:os';
 import { logger } from '../../logger.ts';
 import { getCamoufoxBinaryPath } from './config.ts';
 
-/** Bound the ~100MB download so a stalled network fails fast instead of hanging forever. */
-const FETCH_TIMEOUT_MS = 15 * 60 * 1000;
-/** A lock older than this is considered stale (crashed mid-fetch) and may be stolen. */
-const STALE_LOCK_MS = 20 * 60 * 1000;
-/** When another process holds the fetch lock, poll this long for the browser to appear. */
-const WAIT_FOR_PEER_MS = 16 * 60 * 1000;
+/** Bound the ~500MB camoufox-js 0.12 browser download (measured 484MB; the
+ *  0.10 pin was ~100MB and the old bound assumed that) so a stalled network
+ *  fails eventually instead of hanging forever, while a slow-but-working link
+ *  can actually finish. */
+const FETCH_TIMEOUT_MS = 45 * 60 * 1000;
+/** A lock older than this is considered stale (crashed mid-fetch) and may be stolen.
+ *  Must exceed FETCH_TIMEOUT_MS: stealing a LIVE fetcher's lock mid-download would
+ *  start a second 500MB download beside the first. */
+const STALE_LOCK_MS = 55 * 60 * 1000;
+/** When another process holds the fetch lock, poll this long for the browser to appear.
+ *  Spans a full FETCH_TIMEOUT_MS fetch, so a legitimate slow peer is waited out rather
+ *  than duplicated. */
+const WAIT_FOR_PEER_MS = 50 * 60 * 1000;
 const POLL_INTERVAL_MS = 2000;
 
 /** In-process dedupe: concurrent pool inits / scrapers share one fetch. */
@@ -78,7 +85,7 @@ function runFetch(): Promise<void> {
   return new Promise<void>((resolve, reject) => {
     const bin = resolveCamoufoxBin();
     const [cmd, args] = bin ? [bin, ['fetch']] : ['npx', ['camoufox-js', 'fetch']];
-    logger.info(`[ensure-browser] Camoufox not found; fetching the browser (this runs once, ~100MB): ${cmd} ${args.join(' ')}`);
+    logger.info(`[ensure-browser] Camoufox not found; fetching the browser (this runs once, ~500MB): ${cmd} ${args.join(' ')}`);
 
     // Windows needs shell:true to run the .cmd shim (Node CVE-2024-27980 fix makes a
     // shell-less spawn of .cmd throw EINVAL), but shell:true performs NO quoting, so a

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/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/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;