@lincoln504/pi-research 1.7.10 → 1.7.12

package/agent-skill/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.7.10", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.7.12", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli.mjs

@@ -16617,6 +16617,7 @@ init_metrics();
 init_config();
 import { dirname as dirname10, join as join14 } from "node:path";
 import { existsSync as existsSync9 } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { FixedClusterPool, WorkerChoiceStrategies } from "poolifier";
 
@@ -16922,6 +16923,30 @@ function setupMasterIpcErrorHandler() {
     const w = cluster.workers?.[id];
     if (w) guardClusterWorker(w);
   }
+  guardWorkerEmitReemit();
+}
+var workerEmitGuardPatched = false;
+var workerEmitOriginal = null;
+function guardWorkerEmitReemit() {
+  if (workerEmitGuardPatched || cluster.isWorker) return;
+  const Worker2 = cluster.Worker;
+  if (!Worker2 || !Worker2.prototype) return;
+  workerEmitGuardPatched = true;
+  const origEmit = Worker2.prototype.emit;
+  if (typeof origEmit !== "function") return;
+  workerEmitOriginal = origEmit;
+  Worker2.prototype.emit = function(event, ...args) {
+    if (event === "error" && typeof this.listenerCount === "function" && this.listenerCount("error") === 0) {
+      this.on("error", (err) => {
+        if (isBenignClusterIpcError(err)) {
+          logToDebugFile("DEBUG", `[Master] Last-resort guard swallowed listener-less IPC error: ${err?.code || err?.message}`);
+          return;
+        }
+        logToDebugFile("WARN", `[Master] Last-resort guard handled listener-less worker error: ${err?.stack || err?.message || err}`);
+      });
+    }
+    return origEmit.apply(this, [event, ...args]);
+  };
 }
 function guardClusterWorker(worker) {
   if (!worker || worker.__piIpcGuarded) return;
@@ -17020,6 +17045,34 @@ var WorkerPoolManager = class {
   // Handle for the schedulePoolReset() destroy timer, so shutdown() can cancel a pending
   // reset instead of letting it fire after teardown and clobber a freshly-rebuilt pool.
   _resetTimer = null;
+  // One in-flight destroy promise per pool instance. Both the auto-recovery timer
+  // and shutdown() can try to destroy the same pool (observed 2026-10-08 during a
+  // leader-handover storm: "Cannot destroy an already destroying pool"). A second
+  // destroy() racing the first wipes worker listeners (terminate →
+  // removeAllListeners) while the first is still sending kill messages — the fatal
+  // IPC re-emit window. Sharing one promise per pool makes that race impossible.
+  _destroyInFlight = /* @__PURE__ */ new Map();
+  /**
+   * Serialize pool destruction: the first caller wins; later callers await the
+   * same promise instead of racing a second destroy(). Rejections that merely
+   * report a concurrent/finished destroy are treated as success — the pool is
+   * gone either way, and re-throwing them would turn a benign race into a
+   * logged (and potentially escalated) failure.
+   */
+  destroyPoolOnce(deadPool) {
+    let p = this._destroyInFlight.get(deadPool);
+    if (!p) {
+      p = deadPool.destroy().catch((e) => {
+        if (e instanceof Error && /already (destroying|destroyed|starting)/i.test(e.message)) {
+          return;
+        }
+        throw new Error(`Worker pool destroy failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+      });
+      void p.then(() => this._destroyInFlight.delete(deadPool));
+      this._destroyInFlight.set(deadPool, p);
+    }
+    return p;
+  }
   /**
    * Ensure the pool is initialized with the current config.
    * Recreates the pool if the worker count has changed.
@@ -17054,7 +17107,7 @@ var WorkerPoolManager = class {
         if (this.pool && (this.currentWorkerCount !== maxWorkers || this.currentWorkerConcurrency !== workerConcurrency)) {
           logger.log(`[WorkerPoolManager] Pool shape changed (workers ${this.currentWorkerCount} -> ${maxWorkers}, concurrency ${this.currentWorkerConcurrency} -> ${workerConcurrency}), recreating pool...`);
           this.poolEpoch++;
-          await this.pool.destroy();
+          await this.destroyPoolOnce(this.pool);
           this.pool = null;
         }
         this.currentWorkerCount = maxWorkers;
@@ -17074,6 +17127,14 @@ var WorkerPoolManager = class {
             `Browser worker bundle is missing at ${workerPath}. It is produced by the build step; reinstall the extension (e.g. \`pi update --extensions\`) or run \`npm install\` in the extension directory so the prepare/build script regenerates it.`
           );
         }
+        try {
+          execFileSync(process.execPath, ["--check", workerPath], { stdio: "pipe" });
+        } catch (e) {
+          throw new Error(
+            `Browser worker bundle at ${workerPath} does not parse (${e instanceof Error ? e.message : String(e)}). Reinstall the extension (e.g. \`pi update --extensions\`) so the build step regenerates it.`,
+            { cause: e }
+          );
+        }
         const myEpoch = ++this.poolEpoch;
         this.pool = new FixedClusterPool(maxWorkers, workerPath, {
           env: browserEnv,
@@ -17103,7 +17164,7 @@ var WorkerPoolManager = class {
             }
           },
           exitHandler: (code) => {
-            if (code !== 0 && !this.isShuttingDown && this.poolEpoch === myEpoch) {
+            if (code !== 0 && !this.isShuttingDown && !process.env["PI_PROCESS_EXITING"] && this.poolEpoch === myEpoch) {
               logger.error(`[WorkerPoolManager] Worker exited with code ${code}`);
               this.consecutiveErrors++;
               if (this.consecutiveErrors >= 3) {
@@ -17235,7 +17296,7 @@ var WorkerPoolManager = class {
       try {
         if (this.isShuttingDown || this.generation !== myGen) return;
         this.poolEpoch++;
-        if (deadPool) await deadPool.destroy();
+        if (deadPool) await this.destroyPoolOnce(deadPool);
         logger.info("[WorkerPoolManager] Auto-recovery: old pool destroyed.");
       } catch (err) {
         logger.warn("[WorkerPoolManager] Auto-recovery: error destroying old pool:", err);
@@ -17276,7 +17337,7 @@ var WorkerPoolManager = class {
     if (this.pool) {
       try {
         this.poolEpoch++;
-        const destroyPromise = this.pool.destroy();
+        const destroyPromise = this.destroyPoolOnce(this.pool);
         destroyPromise.catch((err) => logger.debug(`[WorkerPoolManager] Background pool destroy rejection: ${err.message}`));
         await raceWithDeadline(destroyPromise, 5e3);
       } catch (e) {
@@ -18510,7 +18571,7 @@ init_logger();
 
 // src/healthcheck/index.ts
 init_config();
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 init_service_registry();
 init_service_interfaces();
 
@@ -18602,7 +18663,7 @@ async function checkBrowserCapability() {
   if (isBrowserAvailable() || mockMode) {
     if (!mockMode && resolveHeadlessMode() === "virtual") {
       try {
-        execFileSync("which", ["Xvfb"], { stdio: "ignore" });
+        execFileSync2("which", ["Xvfb"], { stdio: "ignore" });
       } catch {
         return {
           healthy: false,

package/dist/thread-worker.mjs

@@ -1958,12 +1958,22 @@ function setupIpcErrorHandler() {
     return;
   }
   cluster.worker.on("error", (err) => {
-    if (err && err.code === "ERR_IPC_CHANNEL_CLOSED") {
+    if (isBenignClusterIpcError(err)) {
       return;
     }
     throw err;
   });
 }
+var BENIGN_IPC_CODES = /* @__PURE__ */ new Set(["EPIPE", "ERR_IPC_CHANNEL_CLOSED", "ECONNRESET"]);
+function isBenignClusterIpcError(err) {
+  if (!err) return false;
+  if (typeof err.code === "string" && BENIGN_IPC_CODES.has(err.code)) return true;
+  const msg = String(err.message || err);
+  return /\b(EPIPE|ECONNRESET)\b/.test(msg) || /channel closed/i.test(msg);
+}
+function markWorkerBootstrap(id) {
+  logToDebugFile("WARN", `[Worker-${id}] Bootstrap complete (pid ${process2.pid})`);
+}
 function setupUncaughtExceptionHandler() {
   process2.on("uncaughtException", (err) => {
     if (err && err.message && err.message.includes("reading 'url'") && err.stack && err.stack.includes("coreBundle.js")) {
@@ -3232,6 +3242,7 @@ setBrowserCleanup(cleanupBrowser2);
 if (process3.env["GITHUB_ACTIONS"] !== "true") {
   setupOrphanProtection();
 }
+markWorkerBootstrap(workerId4);
 var FULL_MOCK_MODE = process3.env["PI_RESEARCH_MOCK_SEARCH"] === "true" && process3.env["PI_RESEARCH_MOCK_SCRAPE"] === "true";
 async function runTask(data) {
   if (!data) {

package/docs/ARCHITECTURE.md

@@ -387,8 +387,8 @@ warns on every startup when a host-provided package (`typebox`, `@sinclair/typeb
 loader and create a second live module instance (`resource-loader.js`,
 `collectExtensionPackageWarnings`; pi `docs/packages.md`). Under pi the host's own copy is used,
 so the two agree on `Value.Check`/`Convert` by construction. `@earendil-works/pi-ai` and
-`@earendil-works/pi-coding-agent` 1.0.0 through 1.1.0 all pin `1.3.27` (re-checked 2026-10-08 in
-the installed packages' `package.json`), which is why the devDependency, and so every test run and
+`@earendil-works/pi-coding-agent` 1.0.0 through 1.3.0 all pin `1.3.27` (re-checked 2026-10-17 in
+the installed 1.3.0 packages' `package.json`, previously 2026-10-08 in 1.1.0), which is why the devDependency, and so every test run and
 the type-check, stays on exactly that version: bump it in lockstep with the pi host, not
 independently. A standalone CLI/SDK install resolves the peer automatically on npm >= 7; the
 `pi-research` bin preflights it with the pi packages and exits 78 with the remedy when a

package/docs/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.12] - 2026-10-17
+
+### Changed
+
+- **The pi host dev dependencies move 1.1.0 → 1.3.0** (`@earendil-works/pi-ai`, `pi-coding-agent`, `pi-tui`, and the `pi-agent-core`/`pi-codemode`/`pi-mcp`/`pi-telemetry` they pull in; `@earendil-works/chord` drops out of the tree; the peer range stays `>=0.99.0 <2`). The 1.1.0 → 1.3.0 declaration diff (installed trees, 2026-10-17): `pi-coding-agent`'s extension surface file (`dist/core/extensions/types.d.ts`) changes in exactly four places — `BeforeAgentStartEvent` becomes a `messageType`-discriminated union (`BeforeAgentStartUserEvent` / `BeforeAgentStartCustomEvent`) because `before_agent_start` now also fires for idle `pi.sendMessage(..., { triggerTurn: true })` runs, `ToolNamespace` gains `aliases?`, `ToolDefinition` gains `reachesTools?`, and `ToolInfo` picks up `reachesTools`. `pi-ai` removes the `assistant-message-frame` module (`AssistantMessageFrame*`, `reduceAssistantMessageFrames`) — the only breaking removal across the two releases, and one this package never imports — and adds the OpenRouter routing schemas and `splitErrorToolResultImages`; its thinking-level types move to `providers/model-schema.d.ts` but are re-exported from the root unchanged. `pi-tui` adds the fake-cursor helpers. Nothing this package consumes is removed or re-signed: the four type-checks (TypeScript 6 and 7, src and tests) pass against 1.3.0, and `typebox` still pins `1.3.27` in `pi-ai` and `pi-coding-agent`, so the lockstep rule and the 0.99.0 floor are unchanged.
+- **`PI_TESTED_MAX_VERSION` moves to 1.3.0** (`src/core/pi-version.ts`), so a pi 1.2.x or 1.3.x host runs without the "newer than the tested ceiling" notice. pi-research never triggers the new firing path — all its `pi.sendMessage` calls are `customType` deliveries without `triggerTurn`, and both `pi.sendUserMessage` calls already pass `deliverAs` — and its `before_agent_start` handler reads only `systemPrompt`/`systemPromptOptions`, present on both union members.
+
+### Fixed
+
+- **Worker exits during a process-group teardown no longer trip the pool health counter.** `isShuttingDown` only covers the pool's own `shutdown()`, but a process-group signal (a cron wrapper's `timeout N`) SIGTERMs the workers in the same instant as the master, BEFORE the pool's shutdown begins, so those exits landed as unexpected deaths and could log the pool unhealthy on a process that was exiting anyway. The exit handler now also ignores non-zero exits while `PI_PROCESS_EXITING` is set — the flag the SDK signal handler sets synchronously as its first action. The `sdk.ts` teardown comment now says which deaths each teardown path covers. New unit tests pin both sides: flag set → three exits, counter 0, no auto-recovery destroy; flag unset → counted.
+- In-range lockfile refresh from the 1.3.0 install: nothing else moved.
+
+## [1.7.11] - 2026-10-10
+
+### Fixed
+
+- **The browser worker pool crash class observed on 2026-10-08 is closed at four layers.** On a pi host, an `ERR_IPC_CHANNEL_CLOSED` raised by a write to a worker's closed IPC channel reached a `cluster.Worker` with no `error` listener and threw inside `EventEmitter` → `uncaughtException` → the pi process exited mid-research. The full chain was reconstructed from the host's crash log: a storm of worker exits with code 1 (16+ in under a second, **zero worker-side log lines**) fed the 3-consecutive-error threshold, the auto-recovery 1 s timer fired into a leader-handover storm that tore down and rebuilt the pool three times in ten seconds with an explicit `Cannot destroy an already destroying pool` double-destroy, and the fatal `destroy()` → `sendKillMessageToWorker` → `Worker.send` hit the closed channel at 22:00:30.12. Fixes, in `src/infrastructure/browser/thread-worker-lifecycle.ts` and `worker-pool-manager.ts`:
+  - **The worker-side IPC handler now swallows the same benign set as the master side** (`EPIPE`, `ECONNRESET`, `ERR_IPC_CHANNEL_CLOSED`, `channel closed`, via the shared `isBenignClusterIpcError`). The old narrow check (`ERR_IPC_CHANNEL_CLOSED` only) re-threw `EPIPE`/`ECONNRESET` during teardown churn as an uncaught worker-side exception — a code-1 exit that fed the consecutive-error counter driving the storm. Non-benign errors still re-throw (the worker's uncaught handler logs and exits, by design).
+  - **Pool destruction is serialized.** The auto-recovery timer, `shutdown()`, and the shape-change re-init all destroy through one in-flight promise per pool (`destroyPoolOnce`), so a second `destroy()` can no longer race the first — the double-destroy that wiped worker listeners (`terminate` → `removeAllListeners`) while the first destroy was still sending kill messages, which opened the fatal re-emit window. Rejections that merely report a concurrent/finished destroy are swallowed as success.
+  - **A `cluster.Worker` prototype last-resort guard.** `setupMasterIpcErrorHandler` also patches `Worker.prototype.emit` so no Worker can ever emit `error` without a listener, whatever wipe path, timing, or pool generation is involved. The per-worker re-attach patch already survives poolifier's `removeAllListeners`; this makes the crash class unreachable rather than merely guarded. The listener it attaches can only be the first on a listener-less Worker (the exact state where `EventEmitter` throws), so it never shadows poolifier's own error accounting.
+  - **A corrupted worker bundle now fails loudly at pool init.** A bundle that exists but is truncated or overwritten fails with a bare `SyntaxError` in every forked worker — code-1 exits with no worker-side log, the same silent-churn signature the missing-bundle guard could not catch. `ensurePool` now runs `node --check` on `thread-worker.mjs` (~40 ms) and throws an actionable reinstall error on a parse failure. (Observed 2026-10-09 on a consumer git checkout that had also lost `src/cleanup/research-cleanup.ts`, breaking the research tool with `Cannot find module` — a partial-install corruption class, now loud for the bundle and diagnosable for the rest.)
+  - **Each worker writes a startup marker** (`[Worker-<id>] Bootstrap complete (pid …)`, WARN, always recorded). A non-zero exit with no marker means the worker died during top-level module evaluation, before its handlers were installed — the exact signature of the 2026-10-08 silent churn storm, now visible in post-mortems.
+- Tests: new `test/unit/infrastructure/browser/thread-worker-lifecycle.test.ts` (widened swallow, re-attach patch, prototype last-resort guard plus the no-patch control that throws, bootstrap marker) and destroy-serialization cases in `worker-pool-manager.test.ts` (auto-recovery timer vs concurrent `shutdown()` sharing one `destroy()` call; "already destroying" rejection swallowed; parse-guard failure). Full unit suite 3318, integration 103+57, lint, type-check (TypeScript 6 and 7), depcruise and `npm audit` (0) pass.
+
 ## [1.7.10] - 2026-10-08
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.10",
+  "version": "1.7.12",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
@@ -119,11 +119,11 @@
     "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
+    "@camoufox/camoufox": "^0.5.7",
     "@kreuzberg/html-to-markdown-node": "^3.7.2",
     "@lancedb/lancedb": "0.39.0",
     "apache-arrow": "21.1.0",
     "bgutils-js": "^4.0.3",
-    "@camoufox/camoufox": "^0.5.7",
     "esbuild": "^0.28.2",
     "impit": "0.14.5",
     "jsdom": "^30.1.0",

package/src/core/pi-version.ts

@@ -130,8 +130,25 @@ export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 99, patch: 0 };
  * and an optional `AuthProvider.agentName`; `@earendil-works/pi-tui` adds the OSC 7501
  * program-status helpers and `Text.setPaddingX`. `docs/extensions.md` is unchanged,
  * and nothing was removed or re-signed, so the 0.99.0 floor is unchanged too.
+ *
+ * 1.2.0 and 1.3.0 (2026-10-12 / 2026-10-15) were verified on 2026-10-17 by diffing
+ * the installed declaration trees of all three packages, 1.1.0 against 1.3.0:
+ * `@earendil-works/pi-coding-agent`'s extension surface file
+ * (`dist/core/extensions/types.d.ts`) changes in exactly four places: `BeforeAgentStartEvent`
+ * becomes a `messageType`-discriminated union (`BeforeAgentStartUserEvent` / `BeforeAgentStartCustomEvent`)
+ * because `before_agent_start` now also fires for idle `pi.sendMessage(..., { triggerTurn: true })`
+ * runs, `ToolNamespace` gains `aliases?`, `ToolDefinition` gains `reachesTools?`, and `ToolInfo`
+ * picks up `reachesTools`. `@earendil-works/pi-ai` removes the `assistant-message-frame`
+ * module (`AssistantMessageFrame*`, `reduceAssistantMessageFrames`) — a breaking removal this
+ * package never imports — and adds the OpenRouter routing schemas and
+ * `splitErrorToolResultImages`; its thinking-level types move to `providers/model-schema.d.ts`
+ * but are re-exported from the root unchanged. `@earendil-works/pi-tui` adds the fake-cursor
+ * helpers (`renderFakeCursor`, `FAKE_CURSOR_START/END`) and is otherwise unchanged.
+ * Nothing this package consumes is removed or re-signed; the four type-checks pass against
+ * 1.3.0 (TypeScript 6 and 7, src and tests), and `typebox` still pins 1.3.27 in `pi-ai`
+ * and `pi-coding-agent`, so the lockstep rule and the 0.99.0 floor are unchanged.
  */
-export const PI_TESTED_MAX_VERSION: SemverParts = { major: 1, minor: 1, patch: 0 };
+export const PI_TESTED_MAX_VERSION: SemverParts = { major: 1, minor: 3, patch: 0 };
 
 export type PiCompatibilityLevel = 'ok' | 'unparseable' | 'too-old' | 'untested';
 

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

@@ -20,14 +20,23 @@ export function setWorkerId(id: string): void {
 }
 
 /**
- * Handle ERR_IPC_CHANNEL_CLOSED when poolifier tries to send messages during shutdown
+ * Handle benign closed-channel IPC errors when poolifier tears down a worker's
+ * channel. Symmetric with the master-side classification (isBenignClusterIpcError):
+ * the write failed because the pipe is already gone, which is not a health signal.
+ *
+ * The old narrow check (ERR_IPC_CHANNEL_CLOSED only) re-threw EPIPE/ECONNRESET as an
+ * uncaught worker-side exception → exit code 1. A worker that dies that way during
+ * teardown churn feeds the master's consecutive-error counter and re-spawns — the
+ * self-sustaining worker storm behind the 2026-10-08 crash chain. Swallowing the
+ * same benign set here stops that feedback; genuinely non-benign errors still
+ * re-throw (the worker's uncaught handler logs and exits, as designed).
  */
 export function setupIpcErrorHandler(): void {
   if (!cluster.isWorker || !cluster.worker) {
     return;
   }
   cluster.worker.on('error', (err: any) => {
-    if (err && err.code === 'ERR_IPC_CHANNEL_CLOSED') {
+    if (isBenignClusterIpcError(err)) {
       return;
     }
     throw err;
@@ -92,6 +101,10 @@ export function setupMasterIpcErrorHandler(): void {
     const w = (cluster.workers as any)?.[id];
     if (w) guardClusterWorker(w);
   }
+
+  // Prototype-level backstop: no cluster.Worker can ever emit 'error' without
+  // a listener, whatever path wiped its per-instance listeners.
+  guardWorkerEmitReemit();
 }
 
 /** Reset for tests — re-arms the one-time install guard. */
@@ -99,6 +112,55 @@ export function __resetMasterIpcGuardForTests(): void {
   masterIpcGuardInstalled = false;
 }
 
+let workerEmitGuardPatched = false;
+let workerEmitOriginal: unknown = null;
+
+/**
+ * Last-resort defense against the crash class observed on 2026-10-08: an 'error'
+ * event emitted on a cluster.Worker with NO listeners throws inside EventEmitter
+ * (uncaughtException → the pi host exits). The per-worker guard above is re-armed
+ * after poolifier's removeAllListeners() by the re-attach patch in
+ * guardClusterWorker, but this patches the Worker PROTOTYPE so that no Worker can
+ * ever emit 'error' without a listener — whatever wipe path, re-emit timing, or
+ * pool generation is involved.
+ *
+ * The listener attached here can only be the first listener on a listener-less
+ * Worker (that is the exact state where EventEmitter would throw), so it can never
+ * shadow poolifier's own error accounting, which is always attached at fork time.
+ * Idempotent; master process only. Installed once by setupMasterIpcErrorHandler().
+ */
+export function guardWorkerEmitReemit(): void {
+  if (workerEmitGuardPatched || cluster.isWorker) return;
+  const Worker = (cluster as unknown as { Worker?: { prototype: { emit?: unknown } } }).Worker;
+  if (!Worker || !Worker.prototype) return;
+  workerEmitGuardPatched = true;
+  const origEmit = Worker.prototype.emit;
+  if (typeof origEmit !== 'function') return;
+  workerEmitOriginal = origEmit;
+  Worker.prototype.emit = function (this: any, event: string | symbol, ...args: unknown[]) {
+    if (event === 'error' && typeof this.listenerCount === 'function' && this.listenerCount('error') === 0) {
+      this.on('error', (err: any) => {
+        if (isBenignClusterIpcError(err)) {
+          logToDebugFile('DEBUG', `[Master] Last-resort guard swallowed listener-less IPC error: ${err?.code || err?.message}`);
+          return;
+        }
+        logToDebugFile('WARN', `[Master] Last-resort guard handled listener-less worker error: ${err?.stack || err?.message || err}`);
+      });
+    }
+    return origEmit.apply(this, [event, ...args]);
+  };
+}
+
+/** Reset for tests — restores the original prototype emit and re-arms the flag. */
+export function __resetWorkerEmitGuardForTests(): void {
+  if (workerEmitGuardPatched && workerEmitOriginal) {
+    const Worker = (cluster as unknown as { Worker?: { prototype: { emit?: unknown } } }).Worker;
+    if (Worker && Worker.prototype) Worker.prototype.emit = workerEmitOriginal;
+    workerEmitOriginal = null;
+  }
+  workerEmitGuardPatched = false;
+}
+
 function guardClusterWorker(worker: any): void {
   if (!worker || worker.__piIpcGuarded) return;
   worker.__piIpcGuarded = true;
@@ -137,6 +199,18 @@ function guardClusterWorker(worker: any): void {
   }
 }
 
+/**
+ * Worker bootstrap marker. WARN (always recorded; INFO/DEBUG are gated behind
+ * PI_RESEARCH_DEBUG). If a worker later exits non-zero WITHOUT this line in the
+ * log, it died during top-level module evaluation — before its error handlers
+ * were installed — and left no diagnostic behind. The 2026-10-08 churn storm
+ * had exactly that signature (a burst of code-1 exits with zero worker-side log
+ * lines); this marker makes that class visible in post-mortems.
+ */
+export function markWorkerBootstrap(id: string): void {
+  logToDebugFile('WARN', `[Worker-${id}] Bootstrap complete (pid ${process.pid})`);
+}
+
 /**
  * Handle Uncaught Exceptions in Worker
  */

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

@@ -1958,12 +1958,22 @@ function setupIpcErrorHandler() {
     return;
   }
   cluster.worker.on("error", (err) => {
-    if (err && err.code === "ERR_IPC_CHANNEL_CLOSED") {
+    if (isBenignClusterIpcError(err)) {
       return;
     }
     throw err;
   });
 }
+var BENIGN_IPC_CODES = /* @__PURE__ */ new Set(["EPIPE", "ERR_IPC_CHANNEL_CLOSED", "ECONNRESET"]);
+function isBenignClusterIpcError(err) {
+  if (!err) return false;
+  if (typeof err.code === "string" && BENIGN_IPC_CODES.has(err.code)) return true;
+  const msg = String(err.message || err);
+  return /\b(EPIPE|ECONNRESET)\b/.test(msg) || /channel closed/i.test(msg);
+}
+function markWorkerBootstrap(id) {
+  logToDebugFile("WARN", `[Worker-${id}] Bootstrap complete (pid ${process2.pid})`);
+}
 function setupUncaughtExceptionHandler() {
   process2.on("uncaughtException", (err) => {
     if (err && err.message && err.message.includes("reading 'url'") && err.stack && err.stack.includes("coreBundle.js")) {
@@ -3232,6 +3242,7 @@ setBrowserCleanup(cleanupBrowser2);
 if (process3.env["GITHUB_ACTIONS"] !== "true") {
   setupOrphanProtection();
 }
+markWorkerBootstrap(workerId4);
 var FULL_MOCK_MODE = process3.env["PI_RESEARCH_MOCK_SEARCH"] === "true" && process3.env["PI_RESEARCH_MOCK_SCRAPE"] === "true";
 async function runTask(data) {
   if (!data) {

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

@@ -19,6 +19,7 @@ import {
   setupOrphanProtection,
   createKillHandler,
   setBrowserCleanup,
+  markWorkerBootstrap,
 } from './thread-worker-lifecycle.ts';
 import {
   setWorkerId,
@@ -60,6 +61,11 @@ if (process.env['GITHUB_ACTIONS'] !== 'true') {
   setupOrphanProtection();
 }
 
+// Startup marker (always recorded). A non-zero exit with no marker in the log
+// means the worker died during top-level module evaluation, before the handlers
+// above were installed — the silent churn signature of the 2026-10-08 crash chain.
+markWorkerBootstrap(workerId);
+
 // When both search and scrape are mocked, skip Firefox entirely in task handlers
 // and in the eager warm-up below. Firefox startup in cluster workers takes 60-90s
 // on constrained CI runners; mocked tasks don't need a real browser at all.

package/src/infrastructure/browser/worker-pool-manager.ts

@@ -7,6 +7,7 @@
 
 import { dirname, join } from 'node:path';
 import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { FixedClusterPool, WorkerChoiceStrategies } from 'poolifier';
 import { logger } from '../../logger.ts';
@@ -110,6 +111,35 @@ export class WorkerPoolManager implements IService {
     // Handle for the schedulePoolReset() destroy timer, so shutdown() can cancel a pending
     // reset instead of letting it fire after teardown and clobber a freshly-rebuilt pool.
     private _resetTimer: ReturnType<typeof setTimeout> | null = null;
+    // One in-flight destroy promise per pool instance. Both the auto-recovery timer
+    // and shutdown() can try to destroy the same pool (observed 2026-10-08 during a
+    // leader-handover storm: "Cannot destroy an already destroying pool"). A second
+    // destroy() racing the first wipes worker listeners (terminate →
+    // removeAllListeners) while the first is still sending kill messages — the fatal
+    // IPC re-emit window. Sharing one promise per pool makes that race impossible.
+    private _destroyInFlight: Map<object, Promise<void>> = new Map();
+
+    /**
+     * Serialize pool destruction: the first caller wins; later callers await the
+     * same promise instead of racing a second destroy(). Rejections that merely
+     * report a concurrent/finished destroy are treated as success — the pool is
+     * gone either way, and re-throwing them would turn a benign race into a
+     * logged (and potentially escalated) failure.
+     */
+    private destroyPoolOnce(deadPool: object): Promise<void> {
+        let p = this._destroyInFlight.get(deadPool);
+        if (!p) {
+            p = (deadPool as { destroy: () => Promise<void> }).destroy().catch((e: unknown) => {
+                if (e instanceof Error && /already (destroying|destroyed|starting)/i.test(e.message)) {
+                    return;
+                }
+                throw new Error(`Worker pool destroy failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+            });
+            void p.then(() => this._destroyInFlight.delete(deadPool));
+            this._destroyInFlight.set(deadPool, p);
+        }
+        return p;
+    }
 
     constructor(
         private readonly onPoolError?: (error: Error, consecutiveErrors: number) => void
@@ -169,7 +199,7 @@ export class WorkerPoolManager implements IService {
                 if (this.pool && (this.currentWorkerCount !== maxWorkers || this.currentWorkerConcurrency !== workerConcurrency)) {
                     logger.log(`[WorkerPoolManager] Pool shape changed (workers ${this.currentWorkerCount} -> ${maxWorkers}, concurrency ${this.currentWorkerConcurrency} -> ${workerConcurrency}), recreating pool...`);
                     this.poolEpoch++; // intentional destroy: silence the dying pool's exit events
-                    await this.pool.destroy();
+                    await this.destroyPoolOnce(this.pool);
                     this.pool = null;
                 }
 
@@ -237,6 +267,23 @@ export class WorkerPoolManager implements IService {
                     );
                 }
 
+                // A bundle that EXISTS but is corrupted (truncated or partially overwritten
+                // file — observed 2026-10-08: a git checkout missing files) fails with a bare
+                // SyntaxError in every forked worker — code-1 exits with no worker-side log,
+                // the same silent churn signature as a missing bundle. Parse (not execute)
+                // the source here so a corrupted bundle fails loudly at pool init instead of
+                // masking as worker churn. `node --check` parses .mjs as ESM (~40 ms).
+                try {
+                    execFileSync(process.execPath, ['--check', workerPath], { stdio: 'pipe' });
+                } catch (e) {
+                    throw new Error(
+                        `Browser worker bundle at ${workerPath} does not parse ` +
+                        `(${e instanceof Error ? e.message : String(e)}). ` +
+                        `Reinstall the extension (e.g. \`pi update --extensions\`) so the build step regenerates it.`,
+                        { cause: e },
+                    );
+                }
+
                 // Identity token for THIS pool instance. The handlers below compare it against
                 // the live `this.poolEpoch` so a superseded pool's trailing events are ignored.
                 const myEpoch = ++this.poolEpoch;
@@ -293,7 +340,17 @@ export class WorkerPoolManager implements IService {
                         // the 2026-09-01/02 logs coincided with SDK SIGTERM shutdown, tripping
                         // "3 consecutive exits → pool unhealthy" once per dying session. Not a
                         // queue-capacity or OOM problem: zero exits occurred during live research.
-                        if (code !== 0 && !this.isShuttingDown && this.poolEpoch === myEpoch) {
+                        //
+                        // The mid-shutdown flag alone does NOT cover process-GROUP signals: a cron
+                        // wrapper like `timeout N` SIGTERMs the whole process group, so the
+                        // workers die in the same instant as the master — BEFORE the pool's own
+                        // shutdown() runs and sets isShuttingDown (the scheduler reaches
+                        // workerPoolManager.shutdown() only after service lookups, a state read
+                        // and server.stop()). The SDK signal handler sets PI_PROCESS_EXITING
+                        // synchronously as its first action (sdk.ts _onSignal), before any
+                        // teardown await, so any exit arriving after that flag is teardown
+                        // noise on a dying process, not a health fault.
+                        if (code !== 0 && !this.isShuttingDown && !process.env['PI_PROCESS_EXITING'] && this.poolEpoch === myEpoch) {
                             logger.error(`[WorkerPoolManager] Worker exited with code ${code}`);
                             this.consecutiveErrors++;
                             if (this.consecutiveErrors >= 3) {
@@ -472,7 +529,7 @@ export class WorkerPoolManager implements IService {
                 // and nulling shared state would clobber a pool rebuilt after the shutdown.
                 if (this.isShuttingDown || this.generation !== myGen) return;
                 this.poolEpoch++; // intentional destroy: silence the dying pool's exit events
-                if (deadPool) await deadPool.destroy();
+                if (deadPool) await this.destroyPoolOnce(deadPool);
                 logger.info('[WorkerPoolManager] Auto-recovery: old pool destroyed.');
             } catch (err) {
                 logger.warn('[WorkerPoolManager] Auto-recovery: error destroying old pool:', err);
@@ -535,7 +592,10 @@ export class WorkerPoolManager implements IService {
                 // in their killHandler (context.close / browser.close via Playwright), so
                 // allow enough time for those to complete before the IPC channel closes.
                 this.poolEpoch++; // intentional destroy: silence the dying pool's exit events
-                const destroyPromise = this.pool.destroy();
+                // Shared promise: if the auto-recovery timer is already destroying this pool
+                // (it fired before shutdown cleared the handle), await that destroy instead of
+                // racing a second one — the double-destroy race of the 2026-10-08 crash chain.
+                const destroyPromise = this.destroyPoolOnce(this.pool);
                 destroyPromise.catch((err: Error) => logger.debug(`[WorkerPoolManager] Background pool destroy rejection: ${err.message}`));
                 await raceWithDeadline(destroyPromise, 5000);
             } catch (e) {

package/src/sdk.ts

@@ -365,8 +365,14 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
     // sdk_shutdown cleanup list is empty ("No cleanup tasks registered"), and the scheduler's cluster workers died mid-DAG-disposal —
     // with code null — while the worker pool was still live, which the pool's
     // exitHandler counted as unexpected deaths ("3 consecutive exits → pool
-    // unhealthy") on a process that was exiting anyway. Shutting down here puts
-    // those deaths inside the pool's intentional-destroy window instead. Both
+    // unhealthy") on a process that was exiting anyway. For a signal received
+    // by the master only, shutting down here puts those deaths inside the
+    // pool's intentional-destroy window. A process-GROUP signal (e.g. `timeout
+    // N` from a cron wrapper) SIGTERMs the workers in the same instant the
+    // master runs its handler, so those deaths land BEFORE this task starts —
+    // they are silenced instead by the PI_PROCESS_EXITING flag the handler
+    // sets synchronously as its first action (see the exitHandler in
+    // worker-pool-manager.ts). Both
     // teardown paths are idempotent (the later DAG dispose no-ops), and the task
     // is bounded well inside the 15s signal force-exit deadline. Registered per
     // init: runCleanup detaches the task set after running, so re-init gets a