@lincoln504/pi-research 1.1.0 → 1.2.0

package/dist/cli.mjs

@@ -1017,11 +1017,12 @@ function disposeAllServices(container = globalServiceContainer) {
 function resetServiceContainer(container = globalServiceContainer) {
   return container.reset();
 }
-var initializationContext, ServiceContainer, globalServiceContainer;
+var DISPOSE_INFLIGHT_INIT_TIMEOUT_MS, initializationContext, ServiceContainer, globalServiceContainer;
 var init_service_registry = __esm({
   "src/core/service-registry.ts"() {
     "use strict";
     init_logger();
+    DISPOSE_INFLIGHT_INIT_TIMEOUT_MS = 5e3;
     initializationContext = new AsyncLocalStorage4();
     ServiceContainer = class {
       services = /* @__PURE__ */ new Map();
@@ -1113,11 +1114,26 @@ var init_service_registry = __esm({
           throw new Error(`Service '${name}' is not registered`);
         }
         if (registration.instance) {
+          if (registration.initializationPromise && caller === void 0) {
+            await registration.initializationPromise.catch(() => {
+            });
+            if (!registration.instance) {
+              return this.get(name, ctx);
+            }
+          }
           if (ctx && registration.instance.initialize) {
-            return initializationContext.run(name, async () => {
+            const reinit = initializationContext.run(name, async () => {
               await registration.instance.initialize(ctx);
               return registration.instance;
             });
+            registration.initializationPromise = reinit;
+            const clearIfCurrent = () => {
+              if (registration.initializationPromise === reinit) {
+                registration.initializationPromise = null;
+              }
+            };
+            reinit.then(clearIfCurrent, clearIfCurrent);
+            return reinit;
           }
           return registration.instance;
         }
@@ -1137,7 +1153,21 @@ var init_service_registry = __esm({
         }
       }
       /**
-       * Get a service instance synchronously (returns null if not initialized)
+       * Get a service instance synchronously (returns null if not registered or not
+       * yet constructed).
+       *
+       * Deliberately returns instances in NON-settled lifecycles too. This is a
+       * lifecycle *inspector* as much as an accessor: the health check resolves the
+       * knowledge store through it precisely so it can report `initializing` /
+       * `disabled` / `disposed (not running)` WITHOUT forcing initialization (forcing
+       * it was a past cause of 45 s CI stalls). Filtering those states out here would
+       * make every one of them indistinguishable from "absent".
+       *
+       * The trade-off: because `_initializeService` publishes the instance before
+       * awaiting its `initialize()` (to break dependency cycles), a caller that
+       * immediately *uses* the result can catch a half-built service. Callers that
+       * need a ready service must use the async `get()`, which waits — see the note
+       * there. Callers that only inspect `lifecycle` are safe by construction.
        */
       tryGet(name) {
         if (this.isDisposing) {
@@ -1171,6 +1201,10 @@ var init_service_registry = __esm({
         if (!registration) {
           throw new Error(`Service '${name}' is not registered`);
         }
+        if (registration.initializationPromise) {
+          await registration.initializationPromise.catch(() => {
+          });
+        }
         if (registration.instance && registration.instance.dispose) {
           await registration.instance.dispose().catch((err) => {
             logger.warn(`[ServiceContainer] Error disposing service '${name}':`, err);
@@ -1190,6 +1224,10 @@ var init_service_registry = __esm({
         if (!registration) {
           throw new Error(`Service '${name}' is not registered`);
         }
+        if (registration.initializationPromise) {
+          await registration.initializationPromise.catch(() => {
+          });
+        }
         if (registration.instance && registration.instance.dispose) {
           await registration.instance.dispose().catch((err) => {
             logger.warn(`[ServiceContainer] Error disposing old service '${name}':`, err);
@@ -1219,6 +1257,24 @@ var init_service_registry = __esm({
           logger.log("[ServiceContainer] Disposing all services (DAG-ordered teardown)...");
         }
         try {
+          const inFlight2 = Array.from(this.services.values()).map((r) => r.initializationPromise).filter((p) => p != null);
+          if (inFlight2.length > 0) {
+            if (this.defaultOptions.enableLogging) {
+              logger.debug(`[ServiceContainer] Waiting for ${inFlight2.length} in-flight initialization(s) before teardown`);
+            }
+            let settleTimer;
+            await Promise.race([
+              Promise.allSettled(inFlight2),
+              new Promise((resolve8) => {
+                settleTimer = setTimeout(() => {
+                  logger.warn("[ServiceContainer] Timed out waiting for in-flight service initialization; proceeding with teardown");
+                  resolve8();
+                }, DISPOSE_INFLIGHT_INIT_TIMEOUT_MS);
+                settleTimer.unref?.();
+              })
+            ]);
+            if (settleTimer) clearTimeout(settleTimer);
+          }
           const activeServices = Array.from(this.services.keys()).filter(
             (name) => this.services.get(name)?.instance !== null
           );
@@ -1294,12 +1350,12 @@ var init_service_registry = __esm({
         if (!registration) {
           return null;
         }
-        if (registration.instance) {
-          return "initialized" /* INITIALIZED */;
-        }
         if (registration.initializationPromise) {
           return "initializing" /* INITIALIZING */;
         }
+        if (registration.instance) {
+          return "initialized" /* INITIALIZED */;
+        }
         return "uninitialized" /* UNINITIALIZED */;
       }
       /**
@@ -1709,9 +1765,23 @@ var init_metrics = __esm({
 });
 
 // src/utils/llm-usage.ts
+function warnIfUnpriced(model, tokens, cost) {
+  if (tokens <= 0 || cost > 0) return;
+  const m = model;
+  const key = `${m.provider ?? "unknown"}/${m.id ?? "unknown"}`;
+  if (unpricedModelsWarned.has(key)) return;
+  const table = m.cost;
+  const allZero = !table || Object.values(table).every((v) => typeof v !== "number" || v === 0);
+  if (!allZero) return;
+  unpricedModelsWarned.add(key);
+  logger.warn(
+    `[LlmUsage] Model "${key}" consumed ${tokens} tokens but reports $0.00 \u2014 its price table is all zeros. Expected for flat-rate plans and local servers. Otherwise the price data is missing: a hand-written "models" entry in ~/.pi/agent/models.json replaces pi's catalog entry (and its pricing) for the same model id \u2014 remove it and let pi's catalog supply the model, or use "modelOverrides", which merges.`
+  );
+}
 function recordLlmUsage(model, rawUsage, opts) {
   if (!rawUsage) return { tokens: 0, cost: 0 };
   const { tokens, cost } = extractUsage(model, rawUsage);
+  warnIfUnpriced(model, tokens, cost);
   if (tokens > 0 || cost > 0) {
     const labels = { component: opts.component };
     if (opts.complexity !== void 0) labels["complexity"] = String(opts.complexity);
@@ -1721,11 +1791,14 @@ function recordLlmUsage(model, rawUsage, opts) {
   }
   return { tokens, cost };
 }
+var unpricedModelsWarned;
 var init_llm_usage = __esm({
   "src/utils/llm-usage.ts"() {
     "use strict";
     init_llm();
+    init_logger();
     init_metrics();
+    unpricedModelsWarned = /* @__PURE__ */ new Set();
   }
 });
 
@@ -1739,11 +1812,11 @@ function stripTrailingLlmPunctuation(input) {
       continue;
     }
     if (last === ")" || last === "]" || last === "}") {
-      const open4 = last === ")" ? "(" : last === "]" ? "[" : "{";
+      const open5 = last === ")" ? "(" : last === "]" ? "[" : "{";
       let opens = 0;
       let closes = 0;
       for (const ch of s) {
-        if (ch === open4) opens++;
+        if (ch === open5) opens++;
         else if (ch === last) closes++;
       }
       if (closes > opens) {
@@ -2026,8 +2099,69 @@ var init_host_config = __esm({
   }
 });
 
+// src/utils/atomic-replace.ts
+import * as fs4 from "node:fs/promises";
+import * as fsSync from "node:fs";
+function isRetryable(err) {
+  const code = err?.code;
+  return code !== void 0 && RETRYABLE_CODES.has(code);
+}
+async function replaceFile(tmpPath, destPath) {
+  let lastError;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      await fs4.rename(tmpPath, destPath);
+      return "renamed";
+    } catch (err) {
+      lastError = err;
+      if (process.platform !== "win32" || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        await new Promise((r) => setTimeout(r, RENAME_RETRY_DELAY_MS * (attempt + 1)));
+      }
+    }
+  }
+  try {
+    await fs4.copyFile(tmpPath, destPath);
+    return "copied";
+  } catch {
+    throw lastError;
+  }
+}
+function replaceFileSync(tmpPath, destPath) {
+  let lastError;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      fsSync.renameSync(tmpPath, destPath);
+      return "renamed";
+    } catch (err) {
+      lastError = err;
+      if (process.platform !== "win32" || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        const until = Date.now() + RENAME_RETRY_DELAY_MS * (attempt + 1);
+        while (Date.now() < until) {
+        }
+      }
+    }
+  }
+  try {
+    fsSync.copyFileSync(tmpPath, destPath);
+    return "copied";
+  } catch {
+    throw lastError;
+  }
+}
+var RETRYABLE_CODES, MAX_RENAME_ATTEMPTS, RENAME_RETRY_DELAY_MS;
+var init_atomic_replace = __esm({
+  "src/utils/atomic-replace.ts"() {
+    "use strict";
+    RETRYABLE_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES"]);
+    MAX_RENAME_ATTEMPTS = 5;
+    RENAME_RETRY_DELAY_MS = 25;
+  }
+});
+
 // src/config.ts
-import * as fs4 from "node:fs";
+import * as fs5 from "node:fs";
 import * as path5 from "node:path";
 import * as os2 from "node:os";
 import { Type } from "typebox";
@@ -2042,8 +2176,8 @@ function getProjectSettingsRegistryPath() {
 function loadProjectSettingsRegistry() {
   const registryPath = getProjectSettingsRegistryPath();
   try {
-    if (fs4.existsSync(registryPath)) {
-      const content = fs4.readFileSync(registryPath, "utf-8");
+    if (fs5.existsSync(registryPath)) {
+      const content = fs5.readFileSync(registryPath, "utf-8");
       return JSON.parse(content);
     }
   } catch (err) {
@@ -2064,8 +2198,8 @@ function sleepSync(ms) {
 function updateProjectSettingsRegistry(mutate) {
   const registryPath = getProjectSettingsRegistryPath();
   const dir = path5.dirname(registryPath);
-  if (!fs4.existsSync(dir)) {
-    fs4.mkdirSync(dir, { recursive: true, mode: 448 });
+  if (!fs5.existsSync(dir)) {
+    fs5.mkdirSync(dir, { recursive: true, mode: 448 });
   }
   const lockPath = `${registryPath}.lock`;
   let lockFd = null;
@@ -2073,14 +2207,14 @@ function updateProjectSettingsRegistry(mutate) {
   try {
     for (let i = 0; i < maxRetries; i++) {
       try {
-        lockFd = fs4.openSync(lockPath, "wx", 384);
+        lockFd = fs5.openSync(lockPath, "wx", 384);
         break;
       } catch (err) {
         if (err.code === "EEXIST") {
           try {
-            const stats = fs4.statSync(lockPath);
+            const stats = fs5.statSync(lockPath);
             if (Date.now() - stats.mtimeMs > 3e4) {
-              fs4.unlinkSync(lockPath);
+              fs5.unlinkSync(lockPath);
               continue;
             }
           } catch {
@@ -2095,9 +2229,9 @@ function updateProjectSettingsRegistry(mutate) {
       throw new Error(`Failed to acquire lock for project settings registry after ${maxRetries} retries. Aborting to prevent data corruption.`);
     }
     let registry = {};
-    if (fs4.existsSync(registryPath)) {
+    if (fs5.existsSync(registryPath)) {
       try {
-        registry = JSON.parse(fs4.readFileSync(registryPath, "utf-8"));
+        registry = JSON.parse(fs5.readFileSync(registryPath, "utf-8"));
       } catch (readErr) {
         if (readErr?.code === "ENOENT") {
           registry = {};
@@ -2112,15 +2246,15 @@ function updateProjectSettingsRegistry(mutate) {
     mutate(registry);
     const tmpPath = `${registryPath}.tmp.${process.pid}.${Date.now()}`;
     try {
-      fs4.writeFileSync(tmpPath, JSON.stringify(registry, null, 2), { encoding: "utf-8", mode: 384 });
-      fs4.renameSync(tmpPath, registryPath);
+      fs5.writeFileSync(tmpPath, JSON.stringify(registry, null, 2), { encoding: "utf-8", mode: 384 });
+      fs5.renameSync(tmpPath, registryPath);
       try {
-        fs4.chmodSync(registryPath, 384);
+        fs5.chmodSync(registryPath, 384);
       } catch {
       }
     } catch (writeErr) {
       try {
-        fs4.unlinkSync(tmpPath);
+        fs5.unlinkSync(tmpPath);
       } catch {
       }
       throw writeErr;
@@ -2131,11 +2265,11 @@ function updateProjectSettingsRegistry(mutate) {
   } finally {
     if (lockFd !== null) {
       try {
-        fs4.closeSync(lockFd);
+        fs5.closeSync(lockFd);
       } catch {
       }
       try {
-        fs4.unlinkSync(lockPath);
+        fs5.unlinkSync(lockPath);
       } catch {
       }
     }
@@ -2165,7 +2299,7 @@ function describeKnowledgeStoreMode(cwd = process.cwd(), iface) {
   const KEY = "PI_RESEARCH_KNOWLEDGE_STORE_MODE";
   const fileHasKey = (p) => {
     try {
-      return fs4.existsSync(p) && parseDotEnv(fs4.readFileSync(p, "utf-8"))[KEY] !== void 0;
+      return fs5.existsSync(p) && parseDotEnv(fs5.readFileSync(p, "utf-8"))[KEY] !== void 0;
     } catch {
       return false;
     }
@@ -2177,7 +2311,7 @@ function describeKnowledgeStoreMode(cwd = process.cwd(), iface) {
     let registryHasKey = false;
     try {
       const registry = loadProjectSettingsRegistry();
-      registryHasKey = registry[normalizeWorkspacePath(cwd)]?.[KEY] !== void 0;
+      registryHasKey = findRegistryEntry(registry, normalizeWorkspacePath(cwd))?.[KEY] !== void 0;
     } catch {
     }
     if (registryHasKey) origin = "this directory (project settings)";
@@ -2203,14 +2337,27 @@ function parseDotEnv(content) {
   }
   return out;
 }
+function findRegistryKey(registry, normalizedCwd) {
+  if (registry[normalizedCwd] !== void 0) return normalizedCwd;
+  if (process.platform !== "win32" && process.platform !== "darwin") return void 0;
+  const lowered = normalizedCwd.toLowerCase();
+  for (const key of Object.keys(registry)) {
+    if (key.toLowerCase() === lowered) return key;
+  }
+  return void 0;
+}
+function findRegistryEntry(registry, normalizedCwd) {
+  const key = findRegistryKey(registry, normalizedCwd);
+  return key === void 0 ? void 0 : registry[key];
+}
 function loadEnvFiles(cwd, iface) {
   const merged = {};
   const globalPath = getGlobalEnvFilePath();
   const registry = loadProjectSettingsRegistry();
   const normalizedCwd = normalizeWorkspacePath(cwd);
-  const homeRegistry = registry[normalizeWorkspacePath(os2.homedir())];
+  const homeRegistry = findRegistryEntry(registry, normalizeWorkspacePath(os2.homedir()));
   try {
-    if (!fs4.existsSync(globalPath) && homeRegistry && Object.keys(homeRegistry).length > 0) {
+    if (!fs5.existsSync(globalPath) && homeRegistry && Object.keys(homeRegistry).length > 0) {
       logger.info("[config] config.env missing. Initializing from user settings in central registry...");
       const migrated = {};
       for (const key of USER_MIGRATION_KEYS) {
@@ -2225,8 +2372,8 @@ function loadEnvFiles(cwd, iface) {
     logger.warn("[config] Failed one-time config.env migration:", err);
   }
   try {
-    if (fs4.existsSync(globalPath)) {
-      Object.assign(merged, parseDotEnv(fs4.readFileSync(globalPath, "utf-8")));
+    if (fs5.existsSync(globalPath)) {
+      Object.assign(merged, parseDotEnv(fs5.readFileSync(globalPath, "utf-8")));
     }
   } catch (err) {
     logger.warn("[config] Failed to read global env file:", err);
@@ -2234,8 +2381,8 @@ function loadEnvFiles(cwd, iface) {
   if (iface) {
     const ifacePath = getInterfaceEnvFilePath(iface);
     try {
-      if (fs4.existsSync(ifacePath)) {
-        Object.assign(merged, parseDotEnv(fs4.readFileSync(ifacePath, "utf-8")));
+      if (fs5.existsSync(ifacePath)) {
+        Object.assign(merged, parseDotEnv(fs5.readFileSync(ifacePath, "utf-8")));
       }
     } catch (err) {
       logger.warn(`[config] Failed to read interface config ${ifacePath}:`, err);
@@ -2243,30 +2390,33 @@ function loadEnvFiles(cwd, iface) {
   }
   const legacyPath = getLocalEnvFilePath(cwd);
   let legacyEnv = {};
-  if (fs4.existsSync(legacyPath)) {
+  if (fs5.existsSync(legacyPath)) {
     try {
       logger.warn(`[config] WARNING: .pi-research.env files are deprecated. Settings will be auto-migrated to the centralized registry. Remove ${legacyPath} after migration.`);
-      legacyEnv = parseDotEnv(fs4.readFileSync(legacyPath, "utf-8"));
+      legacyEnv = parseDotEnv(fs5.readFileSync(legacyPath, "utf-8"));
       Object.assign(merged, legacyEnv);
       const legacyLocal = Object.fromEntries(
         Object.entries(legacyEnv).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
       const existingLocal = Object.fromEntries(
-        Object.entries(registry[normalizedCwd] ?? {}).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
+        Object.entries(findRegistryEntry(registry, normalizedCwd) ?? {}).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
       if (Object.keys(legacyLocal).length > 0 && JSON.stringify(existingLocal) !== JSON.stringify(legacyLocal)) {
         logger.info(`[config] Migrating legacy .pi-research.env settings from ${cwd} to central registry...`);
-        registry[normalizedCwd] = { ...registry[normalizedCwd], ...legacyLocal };
+        const mergeKey = findRegistryKey(registry, normalizedCwd) ?? normalizedCwd;
+        registry[mergeKey] = { ...registry[mergeKey], ...legacyLocal };
         updateProjectSettingsRegistry((disk) => {
-          disk[normalizedCwd] = { ...disk[normalizedCwd], ...legacyLocal };
+          const diskKey = findRegistryKey(disk, normalizedCwd) ?? normalizedCwd;
+          disk[diskKey] = { ...disk[diskKey], ...legacyLocal };
         });
       }
     } catch (err) {
       logger.warn(`[config] Failed to load legacy settings for ${cwd}:`, err);
     }
   }
-  if (registry[normalizedCwd]) {
-    for (const [key, val] of Object.entries(registry[normalizedCwd])) {
+  const cwdEntry = findRegistryEntry(registry, normalizedCwd);
+  if (cwdEntry) {
+    for (const [key, val] of Object.entries(cwdEntry)) {
       if (LOCAL_SCOPE_KEYS.has(key)) {
         if (legacyEnv[key] !== void 0 && legacyEnv[key] !== val) {
           logger.warn(`[config] Config divergence for ${key} in ${cwd}: registry value differs from legacy .pi-research.env. Registry wins.`);
@@ -2276,7 +2426,7 @@ function loadEnvFiles(cwd, iface) {
         logger.warn(`[config] Ignoring stale user-scoped ${key} in the project registry (config.env wins). Re-save your user settings to drop it.`);
       }
     }
-  } else if (Object.keys(merged).length === 0 && !fs4.existsSync(legacyPath) && !fs4.existsSync(globalPath)) {
+  } else if (Object.keys(merged).length === 0 && !fs5.existsSync(legacyPath) && !fs5.existsSync(globalPath)) {
     logger.warn(`[config] No configuration found for workspace: ${cwd}. Using code defaults. Run /research-config to configure.`);
   }
   warnLegacyEnvVarsOnce(merged);
@@ -2340,7 +2490,8 @@ function saveConfig(config, scope = "local", cwd = process.cwd(), changedKeys) {
   if (scope === "local") {
     const normalizedCwd = normalizeWorkspacePath(cwd);
     updateProjectSettingsRegistry((registry) => {
-      registry[normalizedCwd] = { ...registry[normalizedCwd] ?? {}, ...newValues };
+      const key = findRegistryKey(registry, normalizedCwd) ?? normalizedCwd;
+      registry[key] = { ...registry[key] ?? {}, ...newValues };
     });
     logger.debug(`[config] Saved project settings for ${normalizedCwd} to central registry.`);
     return;
@@ -2348,22 +2499,22 @@ function saveConfig(config, scope = "local", cwd = process.cwd(), changedKeys) {
   const p = getGlobalEnvFilePath();
   const lockPath = `${p}.lock`;
   const dir = path5.dirname(p);
-  if (!fs4.existsSync(dir)) {
-    fs4.mkdirSync(dir, { recursive: true, mode: 448 });
+  if (!fs5.existsSync(dir)) {
+    fs5.mkdirSync(dir, { recursive: true, mode: 448 });
   }
   let lockFd = null;
   const lockRetryDelay = 50;
   const lockMaxRetries = 100;
   for (let i = 0; i < lockMaxRetries; i++) {
     try {
-      lockFd = fs4.openSync(lockPath, "wx", 384);
+      lockFd = fs5.openSync(lockPath, "wx", 384);
       break;
     } catch (err) {
       if (err.code === "EEXIST") {
         try {
-          const stats = fs4.statSync(lockPath);
+          const stats = fs5.statSync(lockPath);
           if (Date.now() - stats.mtimeMs > 3e4) {
-            fs4.unlinkSync(lockPath);
+            fs5.unlinkSync(lockPath);
             continue;
           }
         } catch {
@@ -2380,8 +2531,8 @@ function saveConfig(config, scope = "local", cwd = process.cwd(), changedKeys) {
   }
   try {
     let lines = [];
-    if (fs4.existsSync(p)) {
-      lines = fs4.readFileSync(p, "utf-8").split("\n");
+    if (fs5.existsSync(p)) {
+      lines = fs5.readFileSync(p, "utf-8").split("\n");
     } else {
       lines = [
         `# pi-research global configuration`,
@@ -2420,35 +2571,32 @@ function saveConfig(config, scope = "local", cwd = process.cwd(), changedKeys) {
       }
     }
     const tmpPath = `${p}.tmp.${process.pid}.${Date.now()}`;
-    fs4.writeFileSync(tmpPath, outLines.join("\n"), { encoding: "utf-8", mode: 384 });
+    fs5.writeFileSync(tmpPath, outLines.join("\n"), { encoding: "utf-8", mode: 384 });
     try {
-      fs4.renameSync(tmpPath, p);
-    } catch (renameErr) {
-      if (process.platform === "win32") {
-        fs4.copyFileSync(tmpPath, p);
+      if (replaceFileSync(tmpPath, p) === "copied") {
         try {
-          fs4.unlinkSync(tmpPath);
+          fs5.unlinkSync(tmpPath);
         } catch {
         }
-      } else {
-        try {
-          fs4.unlinkSync(tmpPath);
-        } catch {
-        }
-        throw renameErr;
       }
+    } catch (renameErr) {
+      try {
+        fs5.unlinkSync(tmpPath);
+      } catch {
+      }
+      throw renameErr;
     }
     try {
-      fs4.chmodSync(p, 384);
+      fs5.chmodSync(p, 384);
     } catch {
     }
   } catch (err) {
     logger.error(`[config] Failed to write config to ${p}:`, err);
     throw err;
   } finally {
-    fs4.closeSync(lockFd);
+    fs5.closeSync(lockFd);
     try {
-      fs4.unlinkSync(lockPath);
+      fs5.unlinkSync(lockPath);
     } catch {
     }
   }
@@ -2575,6 +2723,7 @@ var init_config = __esm({
     init_logger();
     init_host_config();
     init_text_utils();
+    init_atomic_replace();
     ConfigSchema = Type.Object({
       /** Per-researcher timeout in milliseconds (default: 300000, range: 3-30 min) */
       RESEARCHER_TIMEOUT_MS: Type.Number({ minimum: 18e4, maximum: 18e5, default: 3e5 }),
@@ -2794,7 +2943,11 @@ function getMaxScrapeBatches(config) {
     return 2;
   }
 }
-var REQUEST_DELAY_MS_NVD, REQUEST_DELAY_MS_OTHER, MAX_GATHERING_CALLS, MAX_GREP_CALLS, MAX_SCRAPE_URLS, MAX_TEAM_SIZE_LEVEL_1, MAX_TEAM_SIZE_LEVEL_2, MAX_TEAM_SIZE_LEVEL_3, MAX_ROUNDS_LEVEL_1, MAX_ROUNDS_LEVEL_2, MAX_ROUNDS_LEVEL_3, MAX_EXTRA_ROUNDS_WITH_STEERING, OSV_TIMEOUT_MS, WEBGPU_PROBE_TIMEOUT_MS, MAX_QUERY_LENGTH, MAX_FILENAME_QUERY_LENGTH, MIN_QUERY_LENGTH, MAX_EXPORT_RETRIES, DEFAULT_MAX_RETRIES, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_MODEL_CONTEXT_WINDOW, BATCH_2_DEFAULT_CONCURRENCY, MAX_SCRAPE_CONTENT_CHARS_PER_DOC, RESEARCHER_LAUNCH_DELAY_MS, MAX_QUERIES_PER_RESEARCHER_LEVEL_1, MAX_QUERIES_PER_RESEARCHER_LEVEL_2, MAX_QUERIES_PER_RESEARCHER_LEVEL_3;
+function resolveExcludedTools(callerExclusions, configDisabled = []) {
+  const base = callerExclusions && callerExclusions.length > 0 ? callerExclusions : DEFAULT_EXCLUDED_TOOLS;
+  return [.../* @__PURE__ */ new Set([...base, ...configDisabled])];
+}
+var REQUEST_DELAY_MS_NVD, REQUEST_DELAY_MS_OTHER, MAX_GATHERING_CALLS, MAX_GREP_CALLS, MAX_SCRAPE_URLS, MAX_TEAM_SIZE_LEVEL_1, MAX_TEAM_SIZE_LEVEL_2, MAX_TEAM_SIZE_LEVEL_3, MAX_ROUNDS_LEVEL_1, MAX_ROUNDS_LEVEL_2, MAX_ROUNDS_LEVEL_3, MAX_EXTRA_ROUNDS_WITH_STEERING, OSV_TIMEOUT_MS, WEBGPU_PROBE_TIMEOUT_MS, MAX_QUERY_LENGTH, MAX_FILENAME_QUERY_LENGTH, MIN_QUERY_LENGTH, MAX_EXPORT_RETRIES, DEFAULT_MAX_RETRIES, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_MODEL_CONTEXT_WINDOW, BATCH_2_DEFAULT_CONCURRENCY, MAX_SCRAPE_CONTENT_CHARS_PER_DOC, RESEARCHER_LAUNCH_DELAY_MS, MAX_QUERIES_PER_RESEARCHER_LEVEL_1, MAX_QUERIES_PER_RESEARCHER_LEVEL_2, MAX_QUERIES_PER_RESEARCHER_LEVEL_3, DEFAULT_EXCLUDED_TOOLS;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -2827,6 +2980,7 @@ var init_constants = __esm({
     MAX_QUERIES_PER_RESEARCHER_LEVEL_1 = 10;
     MAX_QUERIES_PER_RESEARCHER_LEVEL_2 = 15;
     MAX_QUERIES_PER_RESEARCHER_LEVEL_3 = 20;
+    DEFAULT_EXCLUDED_TOOLS = ["grep"];
   }
 });
 
@@ -2853,8 +3007,8 @@ function findMatchingBracket(text, start) {
   let depth = 0;
   let inString = false;
   let escaped = false;
-  const open4 = text[start];
-  const close = open4 === "{" ? "}" : "]";
+  const open5 = text[start];
+  const close = open5 === "{" ? "}" : "]";
   for (let i = start; i < text.length; i++) {
     const ch = text[i];
     if (escaped) {
@@ -2870,7 +3024,7 @@ function findMatchingBracket(text, start) {
       continue;
     }
     if (inString) continue;
-    if (ch === open4) depth++;
+    if (ch === open5) depth++;
     else if (ch === close) {
       depth--;
       if (depth === 0) return { index: i, inString: false };
@@ -3210,7 +3364,7 @@ var init_agentic_repair = __esm({
 import { ModelRegistry, ModelRuntime, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import * as path6 from "node:path";
-import * as fs5 from "node:fs";
+import * as fs6 from "node:fs";
 function safeGetAll(registry) {
   if (registry && typeof registry.getAll === "function") {
     try {
@@ -3254,8 +3408,8 @@ async function buildModelRegistry(apiKey, provider) {
   const agentDir = getAgentDir();
   const modelsJsonPath = path6.join(agentDir, "models.json");
   const authPath = path6.join(agentDir, "auth.json");
-  const hasModels = fs5.existsSync(modelsJsonPath);
-  const hasAuth = fs5.existsSync(authPath);
+  const hasModels = fs6.existsSync(modelsJsonPath);
+  const hasAuth = fs6.existsSync(authPath);
   const runtime = await ModelRuntime.create({
     authPath: hasAuth ? authPath : void 0,
     credentials: hasAuth ? void 0 : new InMemoryCredentialStore(),
@@ -3292,6 +3446,13 @@ function constructMinimalModel(provider, modelId, _apiKey) {
     // Provider-specific base URLs are handled by pi-ai internal registry
     reasoning: false,
     input: ["text"],
+    // No catalog is available on this path, so there is no price data and no real
+    // context/output ceiling to read. The zeros below are "unknown", NOT "free":
+    // cost reporting for this model will read $0.00 (see warnIfUnpriced in
+    // utils/llm-usage.ts), and the window figures are conservative guesses, not the
+    // model's true limits — so docs/CONFIGURATION.md's "clamped to the model's real
+    // ceiling" guarantee does not hold here. Anyone relying on accurate cost or the
+    // full context window should give pi a credential so it can fetch the real catalog.
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128e3,
     maxTokens: 32768,
@@ -3309,7 +3470,7 @@ function resolveModel(registry, modelSpec, provider, apiKey) {
       if (apiKey && provider) {
         return constructMinimalModel(prov, modelId, apiKey);
       }
-      throw new Error(`Model "${modelSpec}" not found in pi's configured model registry. Check ${path6.join(getAgentDir(), "models.json")}.`);
+      throw new Error(buildModelNotFoundMessage(modelSpec));
     }
     const allModels = safeGetAll(registry);
     const sameId = allModels.filter((m) => m.id === modelSpec);
@@ -3340,15 +3501,29 @@ function resolveModel(registry, modelSpec, provider, apiKey) {
     }
     return constructMinimalModel(provider, modelSpec, apiKey);
   }
-  throw new Error(
-    `No LLM model available. Please configure your model registry (${path6.join(getAgentDir(), "models.json")}) or provide an explicit apiKey.`
-  );
+  throw new Error(buildNoModelAvailableMessage());
+}
+function credentialGuidance() {
+  const agentDir = getAgentDir();
+  return `  \u2022 Provider pi supports built-in (openrouter, anthropic, openai, \u2026): add a credential \u2014 run \`pi\` and use /login, set the provider's API-key environment variable, or add it to ${path6.join(agentDir, "auth.json")}. pi then fetches that provider's model catalog automatically.
+  \u2022 Custom or self-hosted provider (Ollama, vLLM, a proxy): declare it in ${path6.join(agentDir, "models.json")}.
+    Note: a models.json entry REPLACES pi's catalog entry for the same model id, discarding its pricing and
+    context/output limits. To adjust a single field of a built-in model, use "modelOverrides" instead \u2014 it merges.`;
+}
+function buildModelNotFoundMessage(modelSpec) {
+  return `Model "${modelSpec}" not found in pi's model registry.
+${credentialGuidance()}`;
+}
+function buildNoModelAvailableMessage() {
+  return `No LLM model available.
+${credentialGuidance()}
+  \u2022 Or pass an explicit apiKey.`;
 }
 function readModelsJsonProviderOrder() {
   const modelsJsonPath = path6.join(getAgentDir(), "models.json");
-  if (!fs5.existsSync(modelsJsonPath)) return [];
+  if (!fs6.existsSync(modelsJsonPath)) return [];
   try {
-    const raw = JSON.parse(fs5.readFileSync(modelsJsonPath, "utf-8"));
+    const raw = JSON.parse(fs6.readFileSync(modelsJsonPath, "utf-8"));
     return Object.keys(raw?.providers ?? {});
   } catch (err) {
     logger.warn(`[ModelRegistry] Could not read provider order from models.json: ${err}`);
@@ -3428,6 +3603,7 @@ function withTimeout2(promise, timeoutMs, label, signal) {
   logger.debug(`[withTimeout] Starting ${timeoutMs}ms timeout guard (external signal: ${signal?.aborted ?? "no signal"})`);
   return new Promise((resolve8, reject) => {
     if (combinedSignal.aborted) {
+      void promise.catch(() => void 0);
       logger.debug(`[withTimeout] ${label} already aborted at start (external cancellation)`);
       return reject(new Error(`${label} cancelled or timed out`));
     }
@@ -3533,7 +3709,7 @@ async function retryWithBackoff(fn, options = {}) {
       metrics.observe("retry_backoff_delay_ms", delay2, { attempt: String(attempt), label: opts.label });
       logger.warn(`[Retry] ${opts.label} failed (attempt ${attempt + 1}/${opts.maxRetries + 1}), retrying in ${Math.round(delay2)}ms: ${lastError.message}`);
       try {
-        await abortableDelay(delay2, opts.signal);
+        await abortableDelay(delay2, opts.signal, true);
       } catch {
         metrics.increment("retry_aborted_total", 1, { label: opts.label });
         throw lastError;
@@ -3553,11 +3729,11 @@ var init_retry_utils = __esm({
 });
 
 // src/infrastructure/file-lock-service.ts
-import * as fs6 from "node:fs/promises";
+import * as fs7 from "node:fs/promises";
 import * as crypto from "node:crypto";
 import * as pathmod from "node:path";
 import { AsyncLocalStorage as AsyncLocalStorage6 } from "node:async_hooks";
-var lockContext, FileLockService;
+var lockContext, CLEANUP_DRAIN_TIMEOUT_MS, TRASH_SWEEP_AGE_MS, FileLockService;
 var init_file_lock_service = __esm({
   "src/infrastructure/file-lock-service.ts"() {
     "use strict";
@@ -3566,6 +3742,8 @@ var init_file_lock_service = __esm({
     init_service_registry();
     init_service_names();
     lockContext = new AsyncLocalStorage6();
+    CLEANUP_DRAIN_TIMEOUT_MS = 5e3;
+    TRASH_SWEEP_AGE_MS = 10 * 6e4;
     FileLockService = class {
       name = ServiceNames.FILE_LOCK_SERVICE;
       lifecycle = "uninitialized" /* UNINITIALIZED */;
@@ -3588,6 +3766,9 @@ var init_file_lock_service = __esm({
       // PID reuse. Null when unavailable (no processLifecycle, or lookup failed) —
       // then lock content omits startTime and readers treat us as a legacy owner.
       ownStartTime = null;
+      // Set by cleanup(). A retired instance no longer manages the lock file, so
+      // acquiring through it would hand out exclusivity it cannot honour.
+      _retired = false;
       constructor(options) {
         this.lockFilePath = options.lockFilePath;
         this.lockTimeout = options.lockTimeout ?? 2e4;
@@ -3635,7 +3816,7 @@ var init_file_lock_service = __esm({
         this.lifecycle = "initializing" /* INITIALIZING */;
         try {
           const lockDir = pathmod.dirname(this.lockFilePath);
-          await fs6.mkdir(lockDir, { recursive: true, mode: 448 });
+          await fs7.mkdir(lockDir, { recursive: true, mode: 448 });
         } catch (err) {
           logger.warn(`[FileLockService] Failed to create lock directory: ${err instanceof Error ? err.message : String(err)}`);
         }
@@ -3655,15 +3836,104 @@ var init_file_lock_service = __esm({
         await this.cleanup();
         this.lifecycle = "disposed" /* DISPOSED */;
       }
+      /**
+       * Put a lock file back after a trash-and-verify decided not to reclaim it.
+       *
+       * The old form linked it back inside a swallowing catch and then unlinked the
+       * trash copy unconditionally — so any link failure other than "a peer already
+       * re-created it" DESTROYED the lock this branch exists to preserve. Distinguish
+       * the two: if the path is occupied again the peer's lock wins and ours is dropped;
+       * otherwise move ours back rather than deleting it.
+       */
+      async _restoreLockFile(trashPath) {
+        try {
+          await fs7.link(trashPath, this.lockFilePath);
+          await fs7.unlink(trashPath).catch(() => {
+          });
+          return;
+        } catch {
+        }
+        const peerHoldsIt = await fs7.access(this.lockFilePath).then(() => true).catch(() => false);
+        if (peerHoldsIt) {
+          await fs7.unlink(trashPath).catch(() => {
+          });
+          return;
+        }
+        try {
+          const content = await fs7.readFile(trashPath, "utf-8");
+          const handle = await fs7.open(this.lockFilePath, "wx", 384);
+          try {
+            await handle.write(content);
+            await handle.sync();
+          } finally {
+            await handle.close().catch(() => {
+            });
+          }
+          await fs7.unlink(trashPath).catch(() => {
+          });
+        } catch {
+          const occupied = await fs7.access(this.lockFilePath).then(() => true).catch(() => false);
+          if (occupied) await fs7.unlink(trashPath).catch(() => {
+          });
+        }
+      }
+      /**
+       * Hand our turn back to the next caller in the FIFO queue.
+       *
+       * Every path that stops holding the lock must run this, including the ones that
+       * find the handle already gone. `acquireLock` parks on `await previous` with no
+       * timeout of its own — the lockTimeout only starts counting once the turn has
+       * been granted — so a turn that is never resolved is not a slow acquire, it is a
+       * permanent one.
+       */
+      _releaseTurn() {
+        const resolve8 = this.resolveTurn;
+        this.resolveTurn = null;
+        if (resolve8) resolve8();
+      }
+      /**
+       * Wait, bounded, for an in-flight critical section to finish.
+       *
+       * Yanking a held lock is not a clean teardown: unlinking the file while the
+       * holder is still mid read-modify-write drops cross-process exclusion, and a peer
+       * that acquires in that window loses the holder's update — precisely the hazard
+       * the lock exists to prevent. Since every caller of {@link cleanup} is a shutdown
+       * path, waiting briefly for a normal release is both safe and correct.
+       *
+       * Bounded because shutdown must make progress regardless: if the holder is wedged
+       * (or is itself the caller, which would otherwise deadlock), we give up and force
+       * the teardown, which is the pre-existing behaviour.
+       */
+      async _drainHeldLock(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (this.lockHandle !== null && Date.now() < deadline) {
+          await this.sleep(Math.min(25, this.lockRetryDelay));
+        }
+        return this.lockHandle === null;
+      }
       /**
        * Clean up any stale lock files on initialization.
        * This handles cases where locks weren't released due to crashes.
        */
       async cleanupStaleLocksOnStartup() {
         try {
-          const rawContent = await fs6.readFile(this.lockFilePath, "utf-8").catch(() => null);
+          const dir = pathmod.dirname(this.lockFilePath);
+          const prefix = `${pathmod.basename(this.lockFilePath)}.trash.`;
+          for (const name of await fs7.readdir(dir)) {
+            if (!name.startsWith(prefix)) continue;
+            const p = pathmod.join(dir, name);
+            const st = await fs7.stat(p).catch(() => null);
+            if (st && Date.now() - st.mtimeMs > TRASH_SWEEP_AGE_MS) {
+              await fs7.unlink(p).catch(() => {
+              });
+            }
+          }
+        } catch {
+        }
+        try {
+          const rawContent = await fs7.readFile(this.lockFilePath, "utf-8").catch(() => null);
           if (rawContent === null) return;
-          const stats = await fs6.stat(this.lockFilePath);
+          const stats = await fs7.stat(this.lockFilePath);
           const lockAge = Date.now() - stats.mtimeMs;
           const parsed = this._parseLockContent(rawContent);
           const memo = /* @__PURE__ */ new Map();
@@ -3674,21 +3944,21 @@ var init_file_lock_service = __esm({
             );
             const expectedUuid = parsed?.uuid ?? "";
             const trashPath = `${this.lockFilePath}.trash.${crypto.randomBytes(8).toString("hex")}`;
+            let renamed = false;
             try {
-              await fs6.rename(this.lockFilePath, trashPath);
-              const trashContent = await fs6.readFile(trashPath, "utf-8");
+              await fs7.rename(this.lockFilePath, trashPath);
+              renamed = true;
+              const trashContent = await fs7.readFile(trashPath, "utf-8");
               const trashParsed = this._parseLockContent(trashContent);
               if ((trashParsed?.uuid ?? "") !== expectedUuid) {
-                try {
-                  await fs6.link(trashPath, this.lockFilePath);
-                } catch {
-                }
-                await fs6.unlink(trashPath);
+                await this._restoreLockFile(trashPath);
                 return;
               }
-              await fs6.unlink(trashPath);
+              await fs7.unlink(trashPath).catch(() => {
+              });
               logger.log("[FileLockService] Stale lock removed");
             } catch {
+              if (renamed) await this._restoreLockFile(trashPath);
             }
           }
         } catch (error) {
@@ -3706,6 +3976,9 @@ var init_file_lock_service = __esm({
        * @throws Error if unable to acquire lock within timeout
        */
       async acquireLock() {
+        if (this._retired) {
+          throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service has been disposed`);
+        }
         const heldLocks = lockContext.getStore();
         const lockKey = `${this.lockFilePath}:${this.lockUuid}`;
         if (heldLocks?.has(lockKey)) {
@@ -3729,17 +4002,27 @@ var init_file_lock_service = __esm({
           if (myResolve) myResolve();
           return;
         }
+        if (this._retired) {
+          myResolve();
+          throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service was disposed while queued`);
+        }
         this.resolveTurn = myResolve;
         const startTime = Date.now();
         let contentionCount = 0;
         const contendedOwnerAliveMemo = /* @__PURE__ */ new Map();
         try {
           for (let _attempt = 0; _attempt < this.lockRetries; _attempt++) {
+            if (this._retired) {
+              throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service was disposed during acquisition`);
+            }
             let handle = null;
             try {
-              handle = await fs6.open(this.lockFilePath, "wx", 384);
+              handle = await fs7.open(this.lockFilePath, "wx", 384);
               await handle.write(this._makeLockContent());
               await handle.sync();
+              if (this._retired) {
+                throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service was disposed during acquisition`);
+              }
               this.lockHandle = handle;
               this.lockCount = 1;
               if (heldLocks) {
@@ -3761,7 +4044,7 @@ var init_file_lock_service = __esm({
                 } catch {
                 }
                 try {
-                  await fs6.unlink(this.lockFilePath);
+                  await fs7.unlink(this.lockFilePath);
                 } catch {
                 }
               }
@@ -3770,45 +4053,44 @@ var init_file_lock_service = __esm({
                 if (errnoError.code === "EEXIST") {
                   contentionCount++;
                   try {
-                    const rawContent = await fs6.readFile(this.lockFilePath, "utf-8");
+                    const rawContent = await fs7.readFile(this.lockFilePath, "utf-8");
                     const parsed = this._parseLockContent(rawContent);
                     const lockUuid = parsed?.uuid ?? "";
-                    const stats = await fs6.stat(this.lockFilePath);
+                    const stats = await fs7.stat(this.lockFilePath);
                     const lockAge = Date.now() - stats.mtimeMs;
                     if (lockUuid === this.lockUuid) {
                       try {
-                        await fs6.unlink(this.lockFilePath);
+                        await fs7.unlink(this.lockFilePath);
                       } catch {
                       }
                       continue;
                     }
                     if (await this._shouldReclaim(parsed?.pid ?? null, parsed?.startTime ?? null, lockAge, contendedOwnerAliveMemo)) {
                       const trashPath = `${this.lockFilePath}.trash.${crypto.randomBytes(8).toString("hex")}`;
+                      let renamed = false;
                       try {
-                        await fs6.rename(this.lockFilePath, trashPath);
-                        const trashContent = await fs6.readFile(trashPath, "utf-8");
+                        await fs7.rename(this.lockFilePath, trashPath);
+                        renamed = true;
+                        const trashContent = await fs7.readFile(trashPath, "utf-8");
                         const trashParsed = this._parseLockContent(trashContent);
                         if ((trashParsed?.uuid ?? "") !== lockUuid) {
-                          try {
-                            await fs6.link(trashPath, this.lockFilePath);
-                          } catch {
-                          }
-                          await fs6.unlink(trashPath);
+                          await this._restoreLockFile(trashPath);
                           continue;
                         }
-                        await fs6.unlink(trashPath);
+                        await fs7.unlink(trashPath).catch(() => {
+                        });
                       } catch {
+                        if (renamed) await this._restoreLockFile(trashPath);
                       }
                       continue;
                     }
-                  } catch (_statError) {
-                    const trashPath = `${this.lockFilePath}.trash.${crypto.randomBytes(8).toString("hex")}`;
-                    try {
-                      await fs6.rename(this.lockFilePath, trashPath);
-                      await fs6.unlink(trashPath);
-                      continue;
-                    } catch {
-                    }
+                  } catch (inspectError) {
+                    const code = inspectError?.code;
+                    if (code === "ENOENT") continue;
+                    logger.warn(
+                      `[FileLockService] Could not inspect contended lock at ${this.lockFilePath} (${code ?? "unknown"}); backing off rather than reclaiming it.`
+                    );
+                    metrics.increment("state_lock_inspect_failed_total", 1, { code: code ?? "unknown" });
                   }
                   if (Date.now() - startTime >= this.lockTimeout) {
                     const duration = Date.now() - startTime;
@@ -3829,10 +4111,7 @@ var init_file_lock_service = __esm({
           metrics.increment("state_lock_acquire_total", 1, { status: "failed" });
           throw new Error(`Failed to acquire lock after ${this.lockRetries} retries`);
         } catch (err) {
-          if (this.resolveTurn) {
-            this.resolveTurn();
-            this.resolveTurn = null;
-          }
+          this._releaseTurn();
           throw err;
         }
       }
@@ -3841,6 +4120,7 @@ var init_file_lock_service = __esm({
        */
       async releaseLock() {
         if (this.lockHandle === null) {
+          this._releaseTurn();
           return;
         }
         this.lockCount--;
@@ -3848,10 +4128,10 @@ var init_file_lock_service = __esm({
           return;
         }
         try {
-          const content = await fs6.readFile(this.lockFilePath, "utf8").catch(() => "");
+          const content = await fs7.readFile(this.lockFilePath, "utf8").catch(() => "");
           const parsed = this._parseLockContent(content);
           if (parsed?.uuid === this.lockUuid) {
-            await fs6.unlink(this.lockFilePath).catch(() => {
+            await fs7.unlink(this.lockFilePath).catch(() => {
             });
           }
           await this.lockHandle.close().catch(() => {
@@ -3864,19 +4144,20 @@ var init_file_lock_service = __esm({
           }
           metrics.setGauge("state_lock_held", 0);
         } finally {
-          const resolve8 = this.resolveTurn;
-          this.resolveTurn = null;
-          if (resolve8) {
-            resolve8();
-          }
+          this._releaseTurn();
         }
       }
       /**
        * Execute a function within the scope of a filesystem lock.
        * This is the preferred way to use the lock service.
        * Safe re-entrancy is supported within the same async flow.
+       *
+       * The acquire timeout is the one given to the constructor (`lockTimeout`). This
+       * used to take a second `_timeout` argument that was accepted and then ignored
+       * entirely — a caller passing 5000 silently got the constructed 20000 — so it is
+       * gone rather than left to mislead. No caller was passing it.
        */
-      async withLock(callback, _timeout = 3e4) {
+      async withLock(callback) {
         const heldLocks = lockContext.getStore();
         const lockKey = `${this.lockFilePath}:${this.lockUuid}`;
         if (heldLocks?.has(lockKey)) {
@@ -3892,15 +4173,29 @@ var init_file_lock_service = __esm({
         });
       }
       /**
-       * Force clean up any lock files owned by this instance.
+       * Clean up any lock file owned by this instance, and retire the instance.
+       *
+       * Called only from shutdown paths (`dispose`, `StateManager.cleanup`). It first
+       * gives an in-flight critical section a bounded chance to release normally, then
+       * forces the teardown if it has not. After this the instance is retired:
+       * `acquireLock` fails fast rather than blocking on a queue nothing will ever
+       * drain, which is what makes forcing the teardown safe to do at all.
        */
       async cleanup() {
+        const drained = await this._drainHeldLock(CLEANUP_DRAIN_TIMEOUT_MS);
+        if (!drained) {
+          logger.warn(
+            `[FileLockService] Lock at ${this.lockFilePath} still held after ${CLEANUP_DRAIN_TIMEOUT_MS}ms; forcing teardown. A concurrent writer in another process may observe the lock as free.`
+          );
+          metrics.increment("state_lock_forced_teardown_total", 1);
+        }
+        this._retired = true;
         if (this.lockHandle) {
           try {
-            const content = await fs6.readFile(this.lockFilePath, "utf8").catch(() => "");
+            const content = await fs7.readFile(this.lockFilePath, "utf8").catch(() => "");
             const parsed = this._parseLockContent(content);
             if (parsed?.uuid === this.lockUuid) {
-              await fs6.unlink(this.lockFilePath).catch(() => {
+              await fs7.unlink(this.lockFilePath).catch(() => {
               });
             }
           } catch {
@@ -3912,6 +4207,7 @@ var init_file_lock_service = __esm({
           this.lockHandle = null;
         }
         this.lockCount = 0;
+        this._releaseTurn();
       }
       /**
        * Check if the current instance holds the lock
@@ -3996,6 +4292,93 @@ var init_file_lock_service = __esm({
   }
 });
 
+// src/utils/http-body.ts
+async function readBodyCapped(response, maxBytes) {
+  const body = response.body;
+  if (!body || typeof body.getReader !== "function") {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        total += value.byteLength;
+        if (total > maxBytes) throw new BodyTooLargeError(total, maxBytes);
+        chunks.push(value);
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+    }
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+function hasStreamBody(response) {
+  const body = response.body;
+  return !!body && typeof body.getReader === "function";
+}
+async function readTextCapped(response, maxBytes = MAX_JSON_BODY_BYTES) {
+  if (hasStreamBody(response)) {
+    return new TextDecoder("utf-8").decode(await readBodyCapped(response, maxBytes));
+  }
+  if (typeof response.arrayBuffer === "function") {
+    return new TextDecoder("utf-8").decode(new Uint8Array(await response.arrayBuffer()));
+  }
+  return response.text();
+}
+async function readJsonCapped(response, maxBytes = MAX_JSON_BODY_BYTES) {
+  if (hasStreamBody(response) || typeof response.arrayBuffer === "function" || typeof response.text === "function") {
+    return JSON.parse(await readTextCapped(response, maxBytes));
+  }
+  return response.json();
+}
+var BodyTooLargeError, MAX_JSON_BODY_BYTES, MAX_BULK_JSON_BODY_BYTES, Utf8Body;
+var init_http_body = __esm({
+  "src/utils/http-body.ts"() {
+    "use strict";
+    BodyTooLargeError = class extends Error {
+      constructor(bytesRead, maxBytes) {
+        super(`Response body exceeded ${maxBytes} byte cap`);
+        this.bytesRead = bytesRead;
+        this.maxBytes = maxBytes;
+        this.name = "BodyTooLargeError";
+      }
+      bytesRead;
+      maxBytes;
+    };
+    MAX_JSON_BODY_BYTES = 32 * 1024 * 1024;
+    MAX_BULK_JSON_BODY_BYTES = 96 * 1024 * 1024;
+    Utf8Body = class {
+      chunks = [];
+      bytes = 0;
+      /** Total bytes accumulated so far. */
+      get byteLength() {
+        return this.bytes;
+      }
+      push(chunk) {
+        this.chunks.push(chunk);
+        this.bytes += chunk.byteLength;
+      }
+      /** Concatenate and decode. Safe to call once the stream has ended. */
+      toString() {
+        return Buffer.concat(this.chunks).toString("utf8");
+      }
+    };
+  }
+});
+
 // src/utils/circuit-breaker.ts
 var CircuitBreaker;
 var init_circuit_breaker = __esm({
@@ -4052,6 +4435,11 @@ var init_circuit_breaker = __esm({
           metrics.observe("circuit_breaker_call_duration_ms", duration, { breaker: this.options.name, status: "error" });
           if (this.options.isTransientError(error)) {
             this.onFailure(error);
+          } else if (admittedAsProbe && this.state === "HALF_OPEN") {
+            logger.warn(
+              `[CircuitBreaker] '${this.options.name}' HALF_OPEN probe failed with a non-counted error; treating as inconclusive and re-opening: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.transitionTo("OPEN");
           }
           throw error;
         } finally {
@@ -4555,7 +4943,7 @@ var init_embedder_utils = __esm({
 });
 
 // src/knowledge/store.ts
-import * as fs12 from "node:fs";
+import * as fs13 from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as path13 from "node:path";
 function isLanceCommitConflict(err) {
@@ -4629,7 +5017,7 @@ var init_store = __esm({
       }
       async loadManifest() {
         try {
-          if (fs12.existsSync(this.manifestPath)) {
+          if (fs13.existsSync(this.manifestPath)) {
             const content = await fsPromises.readFile(this.manifestPath, "utf-8");
             const manifest = JSON.parse(content);
             if (manifest.activeTableName) {
@@ -4651,7 +5039,7 @@ var init_store = __esm({
           return true;
         } catch (err) {
           logger.warn("[store] Failed to save manifest:", err);
-          if (fs12.existsSync(tempPath)) {
+          if (fs13.existsSync(tempPath)) {
             try {
               await fsPromises.unlink(tempPath);
             } catch {
@@ -4679,8 +5067,8 @@ var init_store = __esm({
       async openInternal() {
         if (this.db) return;
         try {
-          if (!fs12.existsSync(this.options.dbDir)) {
-            fs12.mkdirSync(this.options.dbDir, { recursive: true });
+          if (!fs13.existsSync(this.options.dbDir)) {
+            fs13.mkdirSync(this.options.dbDir, { recursive: true });
           }
           this.db = await (await getLancedb()).connect(this.options.dbDir);
           const tableNames = await this.db.tableNames();
@@ -4783,7 +5171,7 @@ var init_store = __esm({
         const oldDir = path13.join(this.options.dbDir, `${this.tableName}.lance`);
         const backupDir = path13.join(this.options.dbDir, `${backupTableName}.lance`);
         try {
-          if (fs12.existsSync(oldDir)) {
+          if (fs13.existsSync(oldDir)) {
             await fsPromises.rename(oldDir, backupDir);
             logger.info(`[store] Successfully backed up database directory to ${backupDir}`);
           }
@@ -5067,10 +5455,22 @@ var init_store = __esm({
           }
         }
       }
-      async deleteByUrlAndType(url, ingestionType) {
-        return this.trackOperation("deleteByUrlAndType", void 0, () => this.deleteByUrlAndTypeInner(url, ingestionType));
+      /**
+       * @param olderThan When set, only rows with `timestamp < olderThan` are removed.
+       *   This is what lets a refresh write the replacement chunks FIRST and prune the
+       *   superseded ones after, instead of deleting first and losing the entry
+       *   outright if the insert then fails. `timestamp` is used as the discriminator
+       *   because it is a real (indexed) column — `contentHash` lives inside the
+       *   JSON-encoded `metadata` blob and cannot be filtered on.
+       */
+      async deleteByUrlAndType(url, ingestionType, olderThan) {
+        if (this.isClosing) {
+          logger.warn(`[store] Prune of ${ingestionType} chunks for ${url} skipped \u2014 store is closing; superseded duplicates remain until the next refresh.`);
+          metrics.increment("knowledge_store_delete_total", 1, { operation: "by_url_and_type", status: "skipped_closing" });
+        }
+        return this.trackOperation("deleteByUrlAndType", void 0, () => this.deleteByUrlAndTypeInner(url, ingestionType, olderThan));
       }
-      async deleteByUrlAndTypeInner(url, ingestionType) {
+      async deleteByUrlAndTypeInner(url, ingestionType, olderThan) {
         let retryCount = 0;
         const MAX_RETRIES = 5;
         const BASE_DELAY = 100;
@@ -5081,11 +5481,12 @@ var init_store = __esm({
           try {
             const escapedUrl = url.replace(/'/g, "''");
             const escapedType = ingestionType.replace(/'/g, "''");
-            await table.delete(`url = '${escapedUrl}' AND ingestion_type = '${escapedType}' AND (${scopeFilter})`);
+            const ageClause = Number.isFinite(olderThan) ? ` AND timestamp < ${Math.floor(olderThan)}` : "";
+            await table.delete(`url = '${escapedUrl}' AND ingestion_type = '${escapedType}' AND (${scopeFilter})${ageClause}`);
             const duration = Date.now() - startTime;
             metrics.observe("knowledge_store_delete_duration_ms", duration, { operation: "by_url_and_type" });
             metrics.increment("knowledge_store_delete_total", 1, { operation: "by_url_and_type", status: "success" });
-            logger.log(`[store] Deleted ${ingestionType} chunks for ${url} (scoped)`);
+            logger.log(`[store] Deleted ${ingestionType} chunks for ${url} (scoped)${ageClause ? " older than the replacement" : ""}`);
             return;
           } catch (err) {
             if (isLanceCommitConflict(err)) {
@@ -5138,8 +5539,8 @@ var init_store = __esm({
           });
           try {
             const dir = path13.dirname(outputPath);
-            await fs12.promises.mkdir(dir, { recursive: true });
-            await fs12.promises.writeFile(outputPath, JSON.stringify(exportData), "utf-8");
+            await fs13.promises.mkdir(dir, { recursive: true });
+            await fs13.promises.writeFile(outputPath, JSON.stringify(exportData), "utf-8");
             logger.info(`[store] Successfully exported ${exportData.length} entries to ${outputPath}`);
           } catch (err) {
             logger.error(`[store] Failed to export knowledge store for web:`, err);
@@ -5156,7 +5557,7 @@ var init_store = __esm({
           const scopeFilter = this.getScopeFilter();
           const startTime = Date.now();
           const escapedUrl = url.replace(/'/g, "''");
-          const results = await table.query().where(`url = '${escapedUrl}' AND ingestion_type = 'synthesis-description' AND (${scopeFilter})`).limit(1).toArray();
+          const results = await table.query().where(`url = '${escapedUrl}' AND ingestion_type = 'synthesis-description' AND (${scopeFilter})`).limit(16).toArray();
           const duration = Date.now() - startTime;
           metrics.observe("knowledge_store_query_duration_ms", duration, { operation: "rebuild_document" });
           metrics.increment("knowledge_store_query_total", 1, { operation: "rebuild_document" });
@@ -5164,6 +5565,7 @@ var init_store = __esm({
             metrics.increment("knowledge_store_cache_hits_total", 1, { status: "miss" });
             return null;
           }
+          results.sort((a, b) => Number(b.timestamp) - Number(a.timestamp));
           const r = results[0];
           const rawAgeMs = Date.now() - Number(r.timestamp);
           const hasAge = Number.isFinite(rawAgeMs);
@@ -5319,14 +5721,14 @@ var init_store = __esm({
           for (const name of migrationDirs) {
             const fullPath = path13.join(this.options.dbDir, name);
             logger.info(`[store] Removing orphaned migration temp directory: ${name}`);
-            await fsPromises.rm(fullPath, { recursive: true, force: true });
+            await fsPromises.rm(fullPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
           }
           if (backupDirs.length > 1) {
             backupDirs.sort();
             for (const name of backupDirs.slice(0, -1)) {
               const fullPath = path13.join(this.options.dbDir, name);
               logger.info(`[store] Removing superseded backup directory: ${name}`);
-              await fsPromises.rm(fullPath, { recursive: true, force: true });
+              await fsPromises.rm(fullPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
             }
           }
         } catch (err) {
@@ -5508,44 +5910,47 @@ var init_writer_queue = __esm({
       async process() {
         if (this.processing) return;
         this.processing = true;
-        while (this.queue.length > 0) {
-          const item = this.queue.shift();
-          try {
-            const urlKey = normalizeUrl(item.url);
-            const prev = this.inflightByUrl.get(urlKey) ?? Promise.resolve();
-            const inflight = prev.then(() => this._ingestInner(item));
-            this.inflightByUrl.set(urlKey, inflight);
+        try {
+          while (this.queue.length > 0) {
+            const item = this.queue.shift();
             try {
-              await inflight;
-            } finally {
-              if (this.inflightByUrl.get(urlKey) === inflight) {
-                this.inflightByUrl.delete(urlKey);
-              }
-            }
-          } catch (err) {
-            if (isEmbedderUnreachable(err)) {
-              logger.warn(`[writer-queue] Embedder unreachable for ${item.url}, retrying once after 2s...`);
-              await new Promise((r) => setTimeout(r, 2e3));
+              const urlKey = normalizeUrl(item.url);
+              const prev = this.inflightByUrl.get(urlKey) ?? Promise.resolve();
+              const inflight = prev.then(() => this._ingestInner(item));
+              this.inflightByUrl.set(urlKey, inflight);
               try {
-                await this.ingest(item);
-              } catch (retryErr) {
-                logger.error(`[writer-queue] Retry failed for ${item.url}, dropping:`, retryErr);
-                metrics.increment("knowledge_ingest_dropped_total", 1, { reason: "embedder_unreachable" });
+                await inflight;
+              } finally {
+                if (this.inflightByUrl.get(urlKey) === inflight) {
+                  this.inflightByUrl.delete(urlKey);
+                }
+              }
+            } catch (err) {
+              if (isEmbedderUnreachable(err)) {
+                logger.warn(`[writer-queue] Embedder unreachable for ${item.url}, retrying once after 2s...`);
+                await new Promise((r) => setTimeout(r, 2e3));
+                try {
+                  await this.ingest(item);
+                } catch (retryErr) {
+                  logger.error(`[writer-queue] Retry failed for ${item.url}, dropping:`, retryErr);
+                  metrics.increment("knowledge_ingest_dropped_total", 1, { reason: "embedder_unreachable" });
+                }
+              } else if (isNoSpace(err)) {
+                logger.error(`[writer-queue] ENOSPC: disk full \u2014 dropping ${item.url}. Free up disk space to resume knowledge ingestion.`);
+                metrics.increment("knowledge_ingest_dropped_total", 1, { reason: "enospc" });
+              } else {
+                logger.error(`[writer-queue] Failed to ingest ${item.url}:`, err);
+                metrics.increment("knowledge_ingest_dropped_total", 1, { reason: "ingest_error" });
               }
-            } else if (isNoSpace(err)) {
-              logger.error(`[writer-queue] ENOSPC: disk full \u2014 dropping ${item.url}. Free up disk space to resume knowledge ingestion.`);
-              metrics.increment("knowledge_ingest_dropped_total", 1, { reason: "enospc" });
-            } else {
-              logger.error(`[writer-queue] Failed to ingest ${item.url}:`, err);
-              metrics.increment("knowledge_ingest_dropped_total", 1, { reason: "ingest_error" });
             }
           }
-        }
-        this.processing = false;
-        const resolvers = [...this.drainResolvers];
-        this.drainResolvers = [];
-        for (const resolve8 of resolvers) {
-          resolve8();
+        } finally {
+          this.processing = false;
+          const resolvers = [...this.drainResolvers];
+          this.drainResolvers = [];
+          for (const resolve8 of resolvers) {
+            resolve8();
+          }
         }
       }
       async ingest(item) {
@@ -5586,15 +5991,23 @@ var init_writer_queue = __esm({
         };
         const existing = await this.options.store.findByUrl(normalizedUrl);
         const sameType = existing.filter((c) => c.metadata["ingestionType"] === incomingType);
-        if (sameType.length > 0 && sameType[0].metadata["contentHash"] === hash) {
-          logger.log(`[writer-queue] Skipping ${normalizedUrl} (${incomingType}) \u2014 content unchanged.`);
-          return;
-        }
         if (sameType.length > 0) {
-          await this.options.store.deleteByUrlAndType(normalizedUrl, incomingType);
+          const newestTs = Math.max(...sameType.map((d) => Number(d.timestamp) || 0));
+          const newest = sameType.find((d) => (Number(d.timestamp) || 0) === newestTs);
+          if (newest.metadata["contentHash"] === hash) {
+            if (sameType.some((d) => (Number(d.timestamp) || 0) < newestTs)) {
+              await this.options.store.deleteByUrlAndType(normalizedUrl, incomingType, newestTs).catch((err) => {
+                logger.warn(`[writer-queue] Sweeping superseded duplicates for ${normalizedUrl} (${incomingType}) failed:`, err);
+                metrics.increment("knowledge_ingest_stale_prune_failed_total", 1);
+              });
+            }
+            logger.log(`[writer-queue] Skipping ${normalizedUrl} (${incomingType}) \u2014 content unchanged.`);
+            return;
+          }
         }
         const rawChunks = this.options.chunker ? this.options.chunker.chunk(item.markdown) : [{ text: item.markdown, actual_overlap: 0 }];
         if (rawChunks.length === 0) return;
+        const insertedAt = Date.now();
         const docs = rawChunks.map((chunk, i) => ({
           url: normalizedUrl,
           text: chunk.text,
@@ -5609,9 +6022,15 @@ var init_writer_queue = __esm({
             chunkIndex: i,
             totalChunks: rawChunks.length
           },
-          timestamp: Date.now()
+          timestamp: insertedAt
         }));
         await this.options.store.addDocuments(docs);
+        if (sameType.length > 0) {
+          await this.options.store.deleteByUrlAndType(normalizedUrl, incomingType, insertedAt).catch((err) => {
+            logger.warn(`[writer-queue] Replacement for ${normalizedUrl} (${incomingType}) is stored, but pruning the superseded chunks failed; duplicates remain until the next refresh:`, err);
+            metrics.increment("knowledge_ingest_stale_prune_failed_total", 1);
+          });
+        }
       }
       async drain(timeoutMs) {
         return new Promise((resolve8) => {
@@ -5879,7 +6298,7 @@ var init_model_config = __esm({
 });
 
 // src/knowledge/index.ts
-import * as fs13 from "node:fs";
+import * as fs14 from "node:fs";
 function getMigrationStrategy(config) {
   const strategy = config.MIGRATION_STRATEGY;
   if (!strategy) return void 0;
@@ -5941,10 +6360,10 @@ async function createKnowledgeStoreComponents(embedderFactory, reconnectFactory,
 }
 async function forceDeleteKnowledgeStore(config, workspace) {
   const dbDir = getDbDir(config, workspace);
-  if (fs13.existsSync(dbDir)) {
+  if (fs14.existsSync(dbDir)) {
     try {
-      fs13.rmSync(dbDir, { recursive: true, force: true });
-      fs13.mkdirSync(dbDir, { recursive: true });
+      fs14.rmSync(dbDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+      fs14.mkdirSync(dbDir, { recursive: true });
       logger.info(`[knowledge] Knowledge store at ${dbDir} forcefully deleted and recreated.`);
     } catch (err) {
       logger.error(`[knowledge] Failed to forcefully delete directory ${dbDir}:`, err);
@@ -6079,11 +6498,11 @@ async function isModelCached(model) {
     const env = await getHFEnv();
     const cacheDir = env.cacheDir;
     if (!cacheDir) return false;
-    const { access: access2, readdir: readdir5, readFile: readFile7, stat: stat5, rm: rm3 } = await import("node:fs/promises");
+    const { access: access3, readdir: readdir6, readFile: readFile7, stat: stat5, rm: rm3 } = await import("node:fs/promises");
     const path19 = await import("node:path");
     const modelDir = path19.default.join(cacheDir, model);
     const onnxDir = path19.default.join(modelDir, "onnx");
-    await access2(path19.default.join(onnxDir, "model.onnx"));
+    await access3(path19.default.join(onnxDir, "model.onnx"));
     try {
       const cfgRaw = await readFile7(path19.default.join(modelDir, "config.json"), "utf-8");
       JSON.parse(cfgRaw);
@@ -6100,7 +6519,7 @@ async function isModelCached(model) {
       }
     }
     if (!hasTokenizer) return false;
-    const entries = await readdir5(onnxDir).catch(() => []);
+    const entries = await readdir6(onnxDir).catch(() => []);
     const hasExternalWeights = entries.includes("model.onnx_data");
     if (hasExternalWeights) {
       const dataStat = await stat5(path19.default.join(onnxDir, "model.onnx_data")).catch(() => null);
@@ -6141,7 +6560,7 @@ async function purgeModelCache(model) {
       logger.warn(`[embedder] Refusing to purge unsafe model-cache path for model id ${JSON.stringify(model)}`);
       return;
     }
-    await rm3(modelDir, { recursive: true, force: true });
+    await rm3(modelDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
     logger.warn(`[embedder] Purged corrupt model cache at ${modelDir}`);
   } catch (err) {
     logger.warn("[embedder] Failed to purge model cache:", err);
@@ -6341,19 +6760,21 @@ function runProbe(model, cacheDir, timeoutMs) {
       finish(false);
     }, timeoutMs);
     if (typeof timer.unref === "function") timer.unref();
-    let stdout = "";
-    let stderr = "";
+    const stdoutChunks = [];
+    const stderrChunks = [];
     child.stdout?.on("data", (d) => {
-      stdout += String(d);
+      stdoutChunks.push(Buffer.from(d));
     });
     child.stderr?.on("data", (d) => {
-      stderr += String(d);
+      stderrChunks.push(Buffer.from(d));
     });
     child.on("error", (err) => {
       logger.warn("[embedder] WebGPU probe process error \u2014 defaulting to CPU:", err);
       finish(false);
     });
     child.on("close", (code, signal) => {
+      const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+      const stderr = Buffer.concat(stderrChunks).toString("utf8");
       if (stdout.includes("PROBE_OK")) {
         finish(true);
         return;
@@ -6446,6 +6867,14 @@ var init_embedder = __esm({
       idleTimer = null;
       IDLE_TIMEOUT_MS = 60 * 1e3;
       activeEmbeddings = 0;
+      /**
+       * Why the in-flight dispose was started. An IDLE dispose is a memory-reclaim
+       * pause that a later embed is expected to undo, so initialize() waits it out and
+       * re-initializes. A TERMINAL dispose (shutdown, config change, explicit
+       * disposal) must never be undone — re-initializing there would resurrect the
+       * ONNX pipeline during teardown. Only meaningful while state === 'disposing'.
+       */
+      disposeReason = "terminal";
       constructor(options) {
         this.model = options.model;
         this.poolingMode = options.pooling ?? "mean";
@@ -6479,7 +6908,7 @@ var init_embedder = __esm({
           }
           if (this.state === "ready") {
             logger.info(`[embedder] Idle timeout reached (${this.IDLE_TIMEOUT_MS}ms), releasing GPU memory...`);
-            this.dispose().catch((err) => logger.warn("[embedder] Failed to dispose on idle:", err));
+            this.dispose("idle").catch((err) => logger.warn("[embedder] Failed to dispose on idle:", err));
           }
         }, this.IDLE_TIMEOUT_MS);
         if (this.idleTimer) safeUnref(this.idleTimer);
@@ -6493,7 +6922,20 @@ var init_embedder = __esm({
       async initialize() {
         if (this.state === "ready") return;
         if (this.state === "disposing") {
-          throw new Error("Cannot initialize while disposing");
+          if (this.disposeReason === "idle") {
+            logger.debug("[embedder] initialize() raced an idle dispose \u2014 waiting for it to finish, then re-initializing.");
+            await this.disposePromise?.catch(() => {
+            });
+            if (this.state === "ready") return;
+            if (this.disposeReason === "terminal") {
+              throw new Error("Cannot initialize while disposing");
+            }
+            if (this.state === "disposing") {
+              throw new Error("Cannot initialize while disposing");
+            }
+          } else {
+            throw new Error("Cannot initialize while disposing");
+          }
         }
         if (this.initializingPromise) {
           return this.initializingPromise;
@@ -6815,12 +7257,21 @@ var init_embedder = __esm({
           this.recoveryPromise = null;
         }
       }
-      async dispose() {
+      /**
+       * @param reason `'idle'` for the memory-reclaim pause driven by the idle timer —
+       *   a later embed is allowed to revive the embedder. Anything else is terminal
+       *   (shutdown, config change, explicit disposal) and must never be revived, so
+       *   the default is deliberately the safe one: callers that do not opt in get
+       *   terminal semantics.
+       */
+      async dispose(reason = "terminal") {
         if (this.state === "idle") return;
         this.stopIdleTimer();
         if (this.state === "disposing" && this.disposePromise) {
+          if (reason === "terminal") this.disposeReason = "terminal";
           return this.disposePromise;
         }
+        this.disposeReason = reason;
         this.state = "disposing";
         this.disposePromise = (async () => {
           const maxWaitMs = 5e3;
@@ -6865,8 +7316,21 @@ var init_embedder = __esm({
 
 // src/infrastructure/embedding/embedding-server.ts
 import * as http4 from "node:http";
+import * as crypto7 from "node:crypto";
 import * as path15 from "node:path";
-var SerialQueue, EmbeddingServer;
+function getEmbeddingServerAuthSecret() {
+  if (!_embeddingAuthSecret) {
+    _embeddingAuthSecret = crypto7.randomBytes(32).toString("hex");
+  }
+  return _embeddingAuthSecret;
+}
+function isAuthorized(presented) {
+  const header = Array.isArray(presented) ? presented[0] : presented;
+  const expected = Buffer.from(getEmbeddingServerAuthSecret(), "utf8");
+  const actual = Buffer.from(header ?? "", "utf8");
+  return actual.length === expected.length && crypto7.timingSafeEqual(actual, expected);
+}
+var _embeddingAuthSecret, SerialQueue, EmbeddingServer;
 var init_embedding_server = __esm({
   "src/infrastructure/embedding/embedding-server.ts"() {
     "use strict";
@@ -6874,6 +7338,8 @@ var init_embedding_server = __esm({
     init_stdio_capture();
     init_log_utils();
     init_disk_space_checker();
+    init_http_body();
+    _embeddingAuthSecret = null;
     SerialQueue = class {
       running = false;
       tasks = [];
@@ -7176,12 +7642,18 @@ var init_embedding_server = __esm({
       }
       // ---- HTTP request handler ----
       async handleRequest(req, res) {
+        if (!isAuthorized(req.headers["x-embedding-auth"])) {
+          res.writeHead(403, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Unauthorized" }));
+          req.resume();
+          return;
+        }
         const MAX_BODY_SIZE = 50 * 1024 * 1024;
-        let body = "";
+        const collected = new Utf8Body();
         let oversized = false;
         req.on("data", (chunk) => {
-          body += chunk;
-          if (body.length > MAX_BODY_SIZE) {
+          collected.push(chunk);
+          if (collected.byteLength > MAX_BODY_SIZE) {
             oversized = true;
             req.destroy(new Error("Payload too large"));
           }
@@ -7205,6 +7677,7 @@ var init_embedding_server = __esm({
             }
             finish();
           });
+          req.on("close", finish);
           req.on("end", async () => {
             try {
               if (req.method === "GET" && req.url === "/health") {
@@ -7224,7 +7697,7 @@ var init_embedding_server = __esm({
                 finish();
                 return;
               }
-              const data = JSON.parse(body);
+              const data = JSON.parse(collected.toString());
               switch (req.url) {
                 case "/embed": {
                   this.assertServing();
@@ -7274,17 +7747,24 @@ var init_embedding_client = __esm({
   "src/infrastructure/embedding/embedding-client.ts"() {
     "use strict";
     init_logger();
+    init_http_body();
     EmbeddingClient = class {
-      constructor(port, _device = "unknown") {
+      constructor(port, _device = "unknown", authSecret) {
         this.port = port;
         this._device = _device;
+        this.authSecret = authSecret;
         logger.log(`[EmbeddingClient] Connecting to embedding server at http://127.0.0.1:${port}`);
       }
       port;
       _device;
+      authSecret;
       // Public so store.ts can set the dimension from existing table schema
       // before the embedder has been fully warmed up (see Embedder.setDimension).
       dimension = null;
+      /** Auth header for the leader, or nothing when connecting to a pre-auth leader. */
+      authHeaders() {
+        return this.authSecret ? { "x-embedding-auth": this.authSecret } : {};
+      }
       // ---- IEmbedder ----
       getDevice() {
         return this._device;
@@ -7338,26 +7818,27 @@ var init_embedding_client = __esm({
               hostname: "127.0.0.1",
               port: this.port,
               path: path19,
-              method: "GET"
+              method: "GET",
+              headers: this.authHeaders()
             },
             (res) => {
-              let body = "";
+              const collected = new Utf8Body();
               res.on("data", (chunk) => {
-                body += chunk;
+                collected.push(chunk);
               });
               res.on("end", () => {
                 if (resolved) return;
                 resolved = true;
                 clearTimeout(timer);
                 try {
-                  const parsed = JSON.parse(body);
+                  const parsed = JSON.parse(collected.toString());
                   if (res.statusCode !== 200) {
                     reject(new Error(`[EmbeddingClient] GET ${path19} returned HTTP ${res.statusCode}`));
                   } else {
                     resolve8(parsed);
                   }
                 } catch (_e) {
-                  reject(new Error(`[EmbeddingClient] Failed to parse GET ${path19} response: ${body}`));
+                  reject(new Error(`[EmbeddingClient] Failed to parse GET ${path19} response: ${collected.toString()}`));
                 }
               });
               res.on("error", (err) => {
@@ -7399,20 +7880,21 @@ var init_embedding_client = __esm({
               method: "POST",
               headers: {
                 "Content-Type": "application/json",
-                "Content-Length": Buffer.byteLength(body)
+                "Content-Length": Buffer.byteLength(body),
+                ...this.authHeaders()
               }
             },
             (res) => {
-              let responseBody = "";
+              const collected = new Utf8Body();
               res.on("data", (chunk) => {
-                responseBody += chunk;
+                collected.push(chunk);
               });
               res.on("end", () => {
                 if (resolved) return;
                 resolved = true;
                 clearTimeout(timer);
                 try {
-                  const parsed = JSON.parse(responseBody);
+                  const parsed = JSON.parse(collected.toString());
                   if (res.statusCode !== 200) {
                     const msg2 = parsed?.["error"];
                     reject(new Error(typeof msg2 === "string" ? msg2 : `HTTP ${res.statusCode}`));
@@ -7420,7 +7902,7 @@ var init_embedding_client = __esm({
                     resolve8(parsed);
                   }
                 } catch (_e) {
-                  reject(new Error(`[EmbeddingClient] Failed to parse POST ${path19} response: ${responseBody}`));
+                  reject(new Error(`[EmbeddingClient] Failed to parse POST ${path19} response: ${collected.toString()}`));
                 }
               });
               res.on("error", (err) => {
@@ -7446,7 +7928,7 @@ var init_embedding_client = __esm({
 });
 
 // src/infrastructure/embedding/embedding-factory.ts
-import * as crypto7 from "node:crypto";
+import * as crypto8 from "node:crypto";
 import * as net2 from "node:net";
 async function isPortListening2(port, timeoutMs = 2e3) {
   return new Promise((resolve8) => {
@@ -7491,13 +7973,14 @@ async function getEmbedder(config, _attempt = 0) {
       return _embeddingInstance;
     }
     logger.info(`[EmbeddingFactory] Configuration change detected (${_cachedModel} on ${_cachedDevice} -> ${cfg.EMBEDDING_MODEL} on ${cfg.EMBEDDING_DEVICE}). Disposing stale instance.`);
-    await _embeddingInstance.dispose?.();
+    const stale = _embeddingInstance;
     _embeddingInstance = null;
+    await stale.dispose?.();
   }
-  if (_embeddingInitPromise) return _embeddingInitPromise;
+  if (_embeddingInitPromise && _attempt === 0) return _embeddingInitPromise;
   let p;
   const init = async () => {
-    const serverId = crypto7.randomUUID();
+    const serverId = crypto8.randomUUID();
     const stateManager = await getService(ServiceNames.STATE_MANAGER);
     const processLifecycle = await getService(ServiceNames.PROCESS_LIFECYCLE);
     const myStartTime = await processLifecycle.getCurrentProcessStartTime();
@@ -7519,6 +8002,9 @@ async function getEmbedder(config, _attempt = 0) {
         pid: process.pid,
         serverId,
         model: cfg.EMBEDDING_MODEL,
+        // Published with the claim, not with the port, so a follower that adopts
+        // this leader always has the secret available whenever the port is.
+        authSecret: getEmbeddingServerAuthSecret(),
         ...myStartTime !== null ? { startTime: myStartTime } : {}
       };
       iAmCandidate = true;
@@ -7559,7 +8045,7 @@ async function getEmbedder(config, _attempt = 0) {
           const portOk = await isPortListening2(info.port);
           if (portOk) {
             logger.info(`[EmbeddingFactory] Connecting to embedding server on port ${info.port}`);
-            const client = new EmbeddingClient(info.port);
+            const client = new EmbeddingClient(info.port, cfg.EMBEDDING_DEVICE, info.authSecret);
             await client.fetchHealth();
             _embeddingInstance = client;
             _cachedModel = cfg.EMBEDDING_MODEL;
@@ -7575,7 +8061,6 @@ async function getEmbedder(config, _attempt = 0) {
           }
         }
       }
-      _embeddingInitPromise = null;
       if (_attempt + 1 >= MAX_LEADER_WAIT_RETRIES) {
         throw new Error(
           `[EmbeddingFactory] Could not obtain an embedding server after ${MAX_LEADER_WAIT_RETRIES} attempts (no process became leader; model init may be failing repeatedly).`
@@ -7610,11 +8095,10 @@ async function getEmbedder(config, _attempt = 0) {
   };
   p = init();
   _embeddingInitPromise = p;
-  p.then(() => {
-    _embeddingInitPromise = null;
-  }).catch(() => {
-    _embeddingInitPromise = null;
-  });
+  const clearIfCurrent = () => {
+    if (_embeddingInitPromise === p) _embeddingInitPromise = null;
+  };
+  p.then(clearIfCurrent).catch(clearIfCurrent);
   return p;
 }
 async function clearEmbeddingInstance() {
@@ -8039,7 +8523,7 @@ function resolveResearchModel(options) {
   if (anyModel.length > 0) {
     return pickPreferredAvailable(anyModel, readModelsJsonProviderOrder());
   }
-  throw new Error("No LLM model available for research. Please configure your model registry (~/.pi/agent/models.json).");
+  throw new Error(buildNoModelAvailableMessage());
 }
 var init_research_model_resolver = __esm({
   "src/core/llm/research-model-resolver.ts"() {
@@ -8341,7 +8825,7 @@ async function runBackgroundExtraction(model, auth, conversationHistory, queries
       const delay2 = KNOWLEDGE_SYNTHESIS_RETRY_BASE_MS * attempt;
       metrics.increment("research_knowledge_search_synthesis_retries_total", 1);
       logger.warn(`[research-knowledge-search] Synthesis attempt ${attempt}/${KNOWLEDGE_SYNTHESIS_MAX_ATTEMPTS} failed transiently (${msg2}); retrying in ${delay2}ms`);
-      await abortableDelay(delay2, signal);
+      await abortableDelay(delay2, signal, true);
     }
   }
   const extracted = extractJson(responseText, "object");
@@ -8429,7 +8913,7 @@ ${desc}`;
       const delay2 = KNOWLEDGE_SYNTHESIS_RETRY_BASE_MS * attempt;
       metrics.increment("research_knowledge_search_triage_retries_total", 1);
       logger.warn(`[research-knowledge-search] Triage attempt ${attempt}/${KNOWLEDGE_SYNTHESIS_MAX_ATTEMPTS} failed transiently (${msg2}); retrying in ${delay2}ms`);
-      await abortableDelay(delay2, signal);
+      await abortableDelay(delay2, signal, true);
     }
   }
   const extracted = extractJson(responseText, "object");
@@ -8642,6 +9126,13 @@ function createResearchKnowledgeSearchTool(iface) {
         return buildSteeringResult(result, urls);
       } catch (error) {
         const durationMs = Date.now() - startTime;
+        const msg2 = error instanceof Error ? error.message : String(error);
+        if (signal?.aborted || error instanceof Error && error.name === "AbortError" || /^(aborted|research (aborted|cancelled))$/i.test(msg2)) {
+          metrics.observe("research_knowledge_search_duration_ms", durationMs, { status: "cancelled" });
+          metrics.increment("research_knowledge_search_total", 1, { status: "cancelled" });
+          logger.debug("[research-knowledge-search] Cancelled mid-search \u2014 propagating rather than reporting an empty store.");
+          throw error;
+        }
         metrics.observe("research_knowledge_search_duration_ms", durationMs, { status: "error" });
         metrics.increment("research_knowledge_search_total", 1, { status: "error" });
         logger.error("[research-knowledge-search] Tool execution failed:", error);
@@ -8712,10 +9203,19 @@ __export(skill_installer_exports, {
   skillUninstallCandidates: () => skillUninstallCandidates,
   uninstallSkill: () => uninstallSkill
 });
-import * as fs15 from "node:fs";
+import * as crypto10 from "node:crypto";
+import * as fs16 from "node:fs";
 import * as os6 from "node:os";
 import * as path17 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
+function readSkillVersion(sourceDir) {
+  try {
+    const md = fs16.readFileSync(path17.join(sourceDir, "SKILL.md"), "utf-8");
+    return /"version"\s*:\s*"([^"]+)"/.exec(md)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
 function homeDir(opts) {
   return opts?.home ?? os6.homedir();
 }
@@ -8742,7 +9242,7 @@ function resolveSkillSourceDir(explicit) {
   }
   for (const c of candidates) {
     try {
-      if (fs15.existsSync(path17.join(c, "SKILL.md"))) return path17.resolve(c);
+      if (fs16.existsSync(path17.join(c, "SKILL.md"))) return path17.resolve(c);
     } catch {
     }
   }
@@ -8754,8 +9254,8 @@ function getManifestPath(opts) {
 function readManifest(opts) {
   const p = getManifestPath(opts);
   try {
-    if (fs15.existsSync(p)) {
-      const parsed = JSON.parse(fs15.readFileSync(p, "utf-8"));
+    if (fs16.existsSync(p)) {
+      const parsed = JSON.parse(fs16.readFileSync(p, "utf-8"));
       if (parsed && Array.isArray(parsed.entries)) {
         return { version: 1, package: PACKAGE_NAME, entries: parsed.entries };
       }
@@ -8766,10 +9266,10 @@ function readManifest(opts) {
 }
 function writeManifest(manifest, opts) {
   const p = getManifestPath(opts);
-  fs15.mkdirSync(path17.dirname(p), { recursive: true });
+  fs16.mkdirSync(path17.dirname(p), { recursive: true });
   const tmp = `${p}.tmp`;
-  fs15.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
-  fs15.renameSync(tmp, p);
+  fs16.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+  fs16.renameSync(tmp, p);
 }
 function upsertEntry(manifest, entry) {
   const idx = manifest.entries.findIndex((e) => e.path === entry.path);
@@ -8778,9 +9278,9 @@ function upsertEntry(manifest, entry) {
 }
 function isOwnedSymlink(targetPath, expectedSource) {
   try {
-    const st = fs15.lstatSync(targetPath);
+    const st = fs16.lstatSync(targetPath);
     if (!st.isSymbolicLink()) return false;
-    const dest = path17.resolve(path17.dirname(targetPath), fs15.readlinkSync(targetPath));
+    const dest = path17.resolve(path17.dirname(targetPath), fs16.readlinkSync(targetPath));
     if (expectedSource && path17.resolve(expectedSource) === dest) return true;
     return /[/\\]pi-research[/\\]skills[/\\]pi-research$/.test(dest);
   } catch {
@@ -8789,7 +9289,7 @@ function isOwnedSymlink(targetPath, expectedSource) {
 }
 function isOwnedCopy(targetPath) {
   try {
-    const md = fs15.readFileSync(path17.join(targetPath, "SKILL.md"), "utf-8");
+    const md = fs16.readFileSync(path17.join(targetPath, "SKILL.md"), "utf-8");
     return md.includes(PACKAGE_NAME);
   } catch {
     return false;
@@ -8802,12 +9302,12 @@ function detectHarnesses(opts) {
     const absSkillPath = path17.join(absSkillsDir, SKILL_NAME);
     let present = false;
     try {
-      present = fs15.existsSync(path17.join(home, h.baseDir));
+      present = fs16.existsSync(path17.join(home, h.baseDir));
     } catch {
     }
     let installed = "none";
     try {
-      if (fs15.existsSync(absSkillPath) || isSymlinkPresent(absSkillPath)) {
+      if (fs16.existsSync(absSkillPath) || isSymlinkPresent(absSkillPath)) {
         if (isOwnedSymlink(absSkillPath)) installed = "owned-symlink";
         else if (isOwnedCopy(absSkillPath)) installed = "owned-copy";
         else installed = "foreign";
@@ -8819,7 +9319,7 @@ function detectHarnesses(opts) {
 }
 function isSymlinkPresent(p) {
   try {
-    return fs15.lstatSync(p).isSymbolicLink();
+    return fs16.lstatSync(p).isSymbolicLink();
   } catch {
     return false;
   }
@@ -8836,6 +9336,7 @@ function installSkill(toolIds, opts = {}) {
   const manifest = readManifest(opts);
   const results = [];
   const now = (/* @__PURE__ */ new Date()).toISOString();
+  const skillVersion = readSkillVersion(source);
   for (const id of toolIds) {
     const def = HARNESSES.find((h) => h.id === id);
     if (!def) {
@@ -8847,13 +9348,17 @@ function installSkill(toolIds, opts = {}) {
     const type = opts.copy ? "copy" : "symlink";
     if (isOwnedSymlink(absSkillPath, source) || isOwnedCopy(absSkillPath)) {
       try {
-        const lst = fs15.lstatSync(absSkillPath);
+        const lst = fs16.lstatSync(absSkillPath);
         if (lst.isSymbolicLink()) {
-          const dest = path17.resolve(path17.dirname(absSkillPath), fs15.readlinkSync(absSkillPath));
+          const dest = path17.resolve(path17.dirname(absSkillPath), fs16.readlinkSync(absSkillPath));
           if (dest !== path17.resolve(source)) {
-            fs15.unlinkSync(absSkillPath);
-            fs15.symlinkSync(source, absSkillPath, process.platform === "win32" ? "junction" : "dir");
-            upsertEntry(manifest, { tool: id, path: absSkillPath, type: "symlink", source, createdAt: now });
+            if (opts.dryRun) {
+              results.push({ tool: id, path: absSkillPath, type: "symlink", status: "planned", message: "would re-point stale symlink to current source" });
+              continue;
+            }
+            fs16.unlinkSync(absSkillPath);
+            fs16.symlinkSync(source, absSkillPath, process.platform === "win32" ? "junction" : "dir");
+            upsertEntry(manifest, { tool: id, path: absSkillPath, type: "symlink", source, createdAt: now, ...skillVersion ? { version: skillVersion } : {} });
             results.push({ tool: id, path: absSkillPath, type: "symlink", status: "installed", message: "re-pointed stale symlink to current source" });
             continue;
           }
@@ -8861,10 +9366,10 @@ function installSkill(toolIds, opts = {}) {
       } catch {
       }
       results.push({ tool: id, path: absSkillPath, type, status: "already-installed" });
-      upsertEntry(manifest, { tool: id, path: absSkillPath, type: isSymlinkPresent(absSkillPath) ? "symlink" : "copy", source, createdAt: now });
+      upsertEntry(manifest, { tool: id, path: absSkillPath, type: isSymlinkPresent(absSkillPath) ? "symlink" : "copy", source, createdAt: now, ...skillVersion ? { version: skillVersion } : {} });
       continue;
     }
-    if (fs15.existsSync(absSkillPath) || isSymlinkPresent(absSkillPath)) {
+    if (fs16.existsSync(absSkillPath) || isSymlinkPresent(absSkillPath)) {
       results.push({ tool: id, path: absSkillPath, type, status: "skipped-foreign", message: 'a non-pi-research "research" skill already exists here; left untouched' });
       continue;
     }
@@ -8873,20 +9378,20 @@ function installSkill(toolIds, opts = {}) {
       continue;
     }
     try {
-      fs15.mkdirSync(absSkillsDir, { recursive: true });
+      fs16.mkdirSync(absSkillsDir, { recursive: true });
       if (type === "symlink") {
         try {
-          fs15.symlinkSync(source, absSkillPath, process.platform === "win32" ? "junction" : "dir");
+          fs16.symlinkSync(source, absSkillPath, process.platform === "win32" ? "junction" : "dir");
         } catch (err) {
           copyDir(source, absSkillPath);
-          upsertEntry(manifest, { tool: id, path: absSkillPath, type: "copy", source, createdAt: now });
+          upsertEntry(manifest, { tool: id, path: absSkillPath, type: "copy", source, createdAt: now, ...skillVersion ? { version: skillVersion } : {} });
           results.push({ tool: id, path: absSkillPath, type: "copy", status: "installed", message: `symlink unavailable (${err?.code ?? err?.message}); copied instead` });
           continue;
         }
       } else {
         copyDir(source, absSkillPath);
       }
-      upsertEntry(manifest, { tool: id, path: absSkillPath, type, source, createdAt: now });
+      upsertEntry(manifest, { tool: id, path: absSkillPath, type, source, createdAt: now, ...skillVersion ? { version: skillVersion } : {} });
       results.push({ tool: id, path: absSkillPath, type, status: "installed" });
     } catch (err) {
       results.push({ tool: id, path: absSkillPath, type, status: "error", message: err?.message ?? String(err) });
@@ -8913,7 +9418,7 @@ function uninstallSkill(toolIds, opts = {}) {
       continue;
     }
     const owned = isOwnedSymlink(skillPath) || isOwnedCopy(skillPath);
-    const present = fs15.existsSync(skillPath) || isSymlinkPresent(skillPath);
+    const present = fs16.existsSync(skillPath) || isSymlinkPresent(skillPath);
     if (!present) {
       results.push({ tool, path: skillPath, status: "not-present" });
       continue;
@@ -8931,8 +9436,8 @@ function uninstallSkill(toolIds, opts = {}) {
       continue;
     }
     try {
-      if (isSymlinkPresent(skillPath)) fs15.unlinkSync(skillPath);
-      else fs15.rmSync(skillPath, { recursive: true, force: true });
+      if (isSymlinkPresent(skillPath)) fs16.unlinkSync(skillPath);
+      else fs16.rmSync(skillPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
       results.push({ tool, path: skillPath, status: "removed" });
     } catch (err) {
       results.push({ tool, path: skillPath, status: "error", message: err?.message ?? String(err) });
@@ -8945,7 +9450,7 @@ function uninstallSkill(toolIds, opts = {}) {
       writeManifest({ version: 1, package: PACKAGE_NAME, entries: keep }, opts);
     } else {
       try {
-        fs15.rmSync(getManifestPath(opts));
+        fs16.rmSync(getManifestPath(opts));
       } catch {
       }
     }
@@ -8953,7 +9458,7 @@ function uninstallSkill(toolIds, opts = {}) {
   return results;
 }
 function reconcileSkillInstalls(opts = {}) {
-  const result = { pruned: [], repointed: [] };
+  const result = { pruned: [], repointed: [], refreshed: [] };
   const manifest = readManifest(opts);
   if (manifest.entries.length === 0) return result;
   let source;
@@ -8962,10 +9467,68 @@ function reconcileSkillInstalls(opts = {}) {
   } catch {
     source = null;
   }
+  const currentVersion = source !== null ? readSkillVersion(source) : null;
   const keep = [];
   for (const e of manifest.entries) {
     if (e.type !== "symlink") {
-      keep.push(e);
+      const stale2 = currentVersion !== null && e.version !== currentVersion;
+      if (stale2 && source !== null && fs16.existsSync(e.path) && isOwnedCopy(e.path)) {
+        const dir = path17.dirname(e.path);
+        const base = path17.basename(e.path);
+        try {
+          for (const name of fs16.readdirSync(dir)) {
+            if (name.startsWith(`.${base}.new-`) || name.startsWith(`.${base}.old-`)) {
+              fs16.rmSync(path17.join(dir, name), { recursive: true, force: true });
+            }
+          }
+        } catch {
+        }
+        const suffix = crypto10.randomBytes(4).toString("hex");
+        const fresh = path17.join(dir, `.${base}.new-${suffix}`);
+        const retired = path17.join(dir, `.${base}.old-${suffix}`);
+        try {
+          copyDir(source, fresh);
+        } catch {
+          try {
+            fs16.rmSync(fresh, { recursive: true, force: true });
+          } catch {
+          }
+          keep.push(e);
+          continue;
+        }
+        try {
+          fs16.renameSync(e.path, retired);
+        } catch {
+          try {
+            fs16.rmSync(fresh, { recursive: true, force: true });
+          } catch {
+          }
+          keep.push(e);
+          continue;
+        }
+        try {
+          fs16.renameSync(fresh, e.path);
+        } catch {
+          try {
+            fs16.renameSync(retired, e.path);
+          } catch {
+          }
+          try {
+            fs16.rmSync(fresh, { recursive: true, force: true });
+          } catch {
+          }
+          keep.push(e);
+          continue;
+        }
+        try {
+          fs16.rmSync(retired, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+        } catch {
+        }
+        keep.push({ ...e, source, version: currentVersion });
+        result.refreshed.push(e.path);
+      } else {
+        keep.push(e);
+      }
       continue;
     }
     if (!isSymlinkPresent(e.path)) {
@@ -8976,18 +9539,18 @@ function reconcileSkillInstalls(opts = {}) {
       keep.push(e);
       continue;
     }
-    const targetLive = fs15.existsSync(e.path);
+    const targetLive = fs16.existsSync(e.path);
     let dest = null;
     try {
-      dest = path17.resolve(path17.dirname(e.path), fs15.readlinkSync(e.path));
+      dest = path17.resolve(path17.dirname(e.path), fs16.readlinkSync(e.path));
     } catch {
     }
     const stale = source !== null && dest !== null && dest !== path17.resolve(source);
     if (!targetLive || stale) {
       if (source !== null) {
         try {
-          fs15.unlinkSync(e.path);
-          fs15.symlinkSync(source, e.path, process.platform === "win32" ? "junction" : "dir");
+          fs16.unlinkSync(e.path);
+          fs16.symlinkSync(source, e.path, process.platform === "win32" ? "junction" : "dir");
           keep.push({ ...e, type: "symlink", source });
           result.repointed.push(e.path);
         } catch {
@@ -8995,7 +9558,7 @@ function reconcileSkillInstalls(opts = {}) {
         }
       } else if (!targetLive) {
         try {
-          fs15.unlinkSync(e.path);
+          fs16.unlinkSync(e.path);
           result.pruned.push(e.path);
         } catch {
           keep.push(e);
@@ -9010,14 +9573,22 @@ function reconcileSkillInstalls(opts = {}) {
   if (keep.length > 0) writeManifest({ version: 1, package: PACKAGE_NAME, entries: keep }, opts);
   else {
     try {
-      fs15.rmSync(getManifestPath(opts));
+      fs16.rmSync(getManifestPath(opts));
     } catch {
     }
   }
   return result;
 }
 function copyDir(src, dest) {
-  fs15.cpSync(src, dest, { recursive: true, dereference: true });
+  const st = fs16.statSync(src);
+  if (st.isDirectory()) {
+    fs16.mkdirSync(dest, { recursive: true });
+    for (const name of fs16.readdirSync(src)) {
+      copyDir(path17.join(src, name), path17.join(dest, name));
+    }
+  } else {
+    fs16.copyFileSync(src, dest);
+  }
 }
 var HARNESSES, SKILL_NAME, PACKAGE_NAME, SKILL_AGENT_TARGETS, isTarget;
 var init_skill_installer = __esm({
@@ -9039,7 +9610,8 @@ var init_skill_installer = __esm({
 });
 
 // src/cli.ts
-import * as fs16 from "node:fs";
+import * as fs17 from "node:fs";
+import * as os7 from "node:os";
 import * as path18 from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 
@@ -9554,27 +10126,63 @@ function normalizeCitations(reports) {
         const localKey = cit.number ?? index + 1;
         localToGlobal.set(localKey, globalId);
       }
-    });
-    const headerIdx = lastCitedLinksHeaderIndex(report);
-    let content = headerIdx >= 0 ? report.slice(0, headerIdx) : report;
-    content = content.replace(/\[(\d+)\]/g, (match, p1) => {
-      const localId = parseInt(p1, 10);
-      const globalId = localToGlobal.get(localId);
-      return globalId !== void 0 ? `[${globalId}]` : match;
-    });
-    normalizedReports.set(id, content.trim());
+    });
+    const headerIdx = lastCitedLinksHeaderIndex(report);
+    let content = headerIdx >= 0 ? report.slice(0, headerIdx) : report;
+    content = rewriteCitationMarkers(
+      content,
+      localToGlobal,
+      (n) => !localToGlobal.has(n)
+    );
+    normalizedReports.set(id, content.trim());
+  }
+  return { normalizedReports, globalCitations };
+}
+function formatCitedLinks(citations) {
+  if (citations.length === 0) return "";
+  const links = citations.map((cit) => {
+    const sourcePart = cit.source ? ` [Source: ${cit.source}]` : "";
+    const descPart = cit.description ? ` \u2014 ${cit.description}` : "";
+    return `[${cit.id}] ${cit.url}${sourcePart}${descPart}`;
+  });
+  return `CITED LINKS
+${links.join("\n")}`;
+}
+var MAX_PLAUSIBLE_CITATION_MARKER = 200;
+function rewriteCitationMarkers(text, remap, isDangling) {
+  const inFence = fencedCodeMask(text);
+  return text.replace(/([ \t]*)\[(\d+)\]/g, (match, pad, digits, offset) => {
+    const n = parseInt(digits, 10);
+    const mapped = remap.get(n);
+    if (mapped !== void 0) return `${pad}[${mapped}]`;
+    if (n < 1 || n > MAX_PLAUSIBLE_CITATION_MARKER || !isDangling(n)) return match;
+    if (inFence(offset) || inInlineCodeSpan(text, offset)) return match;
+    const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
+    return text.slice(lineStart, offset).trim() === "" ? pad : "";
+  });
+}
+function fencedCodeMask(text) {
+  const ranges = [];
+  let open5 = -1;
+  let pos = 0;
+  for (const line of text.split("\n")) {
+    if (/^\s{0,3}(```|~~~)/.test(line)) {
+      if (open5 < 0) open5 = pos;
+      else {
+        ranges.push([open5, pos + line.length]);
+        open5 = -1;
+      }
+    }
+    pos += line.length + 1;
   }
-  return { normalizedReports, globalCitations };
+  if (open5 >= 0) ranges.push([open5, text.length]);
+  return (offset) => ranges.some(([start, end]) => offset >= start && offset < end);
 }
-function formatCitedLinks(citations) {
-  if (citations.length === 0) return "";
-  const links = citations.map((cit) => {
-    const sourcePart = cit.source ? ` [Source: ${cit.source}]` : "";
-    const descPart = cit.description ? ` \u2014 ${cit.description}` : "";
-    return `[${cit.id}] ${cit.url}${sourcePart}${descPart}`;
-  });
-  return `CITED LINKS
-${links.join("\n")}`;
+function inInlineCodeSpan(text, offset) {
+  const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
+  let ticks = 0;
+  for (let i = lineStart; i < offset; i++) if (text[i] === "`") ticks++;
+  return ticks % 2 === 1;
 }
 
 // src/core/planning-service.ts
@@ -10463,11 +11071,11 @@ import * as path7 from "node:path";
 init_config();
 init_logger();
 import * as crypto2 from "node:crypto";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 import { existsSync as existsSync5, mkdirSync as mkdirSync3 } from "node:fs";
 import { platform, homedir as homedir2 } from "node:os";
 function getWindowsCamoufoxDir() {
-  return join6(homedir2(), "AppData", "Local", "camoufox", "camoufox", "Cache");
+  return join7(homedir2(), "AppData", "Local", "camoufox", "camoufox", "Cache");
 }
 function getBrowserCacheDir() {
   if (process.env["PLAYWRIGHT_BROWSERS_PATH"]) {
@@ -10477,10 +11085,10 @@ function getBrowserCacheDir() {
   if (osPlatform === "win32") {
     return getWindowsCamoufoxDir();
   } else if (osPlatform === "darwin") {
-    return join6(homedir2(), "Library", "Caches", "camoufox");
+    return join7(homedir2(), "Library", "Caches", "camoufox");
   } else {
-    const cacheHome = process.env["XDG_CACHE_HOME"] || join6(homedir2(), ".cache");
-    return join6(cacheHome, "camoufox");
+    const cacheHome = process.env["XDG_CACHE_HOME"] || join7(homedir2(), ".cache");
+    return join7(cacheHome, "camoufox");
   }
 }
 function getBrowserProfileDir(config) {
@@ -10489,8 +11097,8 @@ function getBrowserProfileDir(config) {
   if (configured && configured.trim().length > 0) {
     dir = configured;
   } else {
-    const cacheHome = process.env["XDG_CACHE_HOME"] || join6(homedir2(), ".cache");
-    dir = join6(cacheHome, "pi-research", "profiles");
+    const cacheHome = process.env["XDG_CACHE_HOME"] || join7(homedir2(), ".cache");
+    dir = join7(cacheHome, "pi-research", "profiles");
   }
   if (!existsSync5(dir)) {
     try {
@@ -10543,10 +11151,10 @@ function getCamoufoxBinaryPath() {
   if (osPlatform === "win32") {
     return getWindowsCamoufoxDir();
   } else if (osPlatform === "darwin") {
-    return join6(homedir2(), "Library", "Caches", "camoufox");
+    return join7(homedir2(), "Library", "Caches", "camoufox");
   } else {
-    const cacheHome = process.env["XDG_CACHE_HOME"] || join6(homedir2(), ".cache");
-    return join6(cacheHome, "camoufox");
+    const cacheHome = process.env["XDG_CACHE_HOME"] || join7(homedir2(), ".cache");
+    return join7(cacheHome, "camoufox");
   }
 }
 function generateSchedulerVersion(config) {
@@ -10584,6 +11192,7 @@ function isFullMockMode() {
 // src/infrastructure/browser/browser-client.ts
 init_logger();
 init_error_tracker();
+init_http_body();
 import * as http2 from "node:http";
 
 // src/infrastructure/browser/client-agent.ts
@@ -10593,7 +11202,7 @@ var clientAgent = new http.Agent({
   maxSockets: 100,
   // Allow up to 100 concurrent requests to the leader
   maxFreeSockets: 10,
-  // Set timeout to 180s (3x the client timeout) to handle slow browser responses
+  // 180s (3x the client timeout) to handle slow browser responses
   // and prevent "socket hang up" errors during peak load
   timeout: 18e4
 });
@@ -10610,6 +11219,12 @@ var BrowserClient = class {
   }
   port;
   authSecret;
+  /** The leader port this client was built for — lets the herd-guard cooldown
+   * verify the cached handle still targets the REGISTERED leader, not a
+   * predecessor that died inside the cooldown window. */
+  get targetPort() {
+    return this.port;
+  }
   async request(path19, data, signal) {
     const start = Date.now();
     const operation = path19.includes("/search") ? "search" : path19.includes("/scrape") ? "browser-task" : path19.includes("/healthcheck") ? "healthcheck" : "network";
@@ -10660,8 +11275,8 @@ var BrowserClient = class {
           "X-Browser-Auth": this.authSecret
         }
       }, (res) => {
-        let body = "";
-        res.on("data", (chunk) => body += chunk);
+        const collected = new Utf8Body();
+        res.on("data", (chunk) => collected.push(chunk));
         res.on("end", () => {
           if (resolved) return;
           resolved = true;
@@ -10669,7 +11284,7 @@ var BrowserClient = class {
           abortCleanup?.();
           const duration = Date.now() - start;
           try {
-            const parsed = JSON.parse(body);
+            const parsed = JSON.parse(collected.toString());
             if (res.statusCode === 503 && parsed?.error === "draining") {
               const error = new Error(
                 `Browser pool leader is draining (${parsed.reason || "leadership-lost"}) \u2014 re-elect and retry`
@@ -10694,7 +11309,8 @@ var BrowserClient = class {
               resolve8(parsed);
             }
           } catch (_e) {
-            const preview = body.length > 200 ? body.slice(0, 200) + "..." : body;
+            const raw = collected.toString();
+            const preview = raw.length > 200 ? raw.slice(0, 200) + "..." : raw;
             const error = new Error(`Failed to parse response (status ${res.statusCode}): ${preview}`);
             errorTracker.trackError(error, {
               component: "browser-manager",
@@ -10776,6 +11392,7 @@ init_service_interfaces();
 
 // src/infrastructure/browser/browser-server.ts
 init_logger();
+init_http_body();
 import * as http3 from "node:http";
 import * as crypto3 from "node:crypto";
 
@@ -10813,7 +11430,16 @@ function isServerDrainingError(error) {
 function isPoolShutdownError(error) {
   if (!error || typeof error !== "object") return false;
   const err = error;
-  return typeof err.message === "string" && (err.message.includes("Worker pool is shutting down") || err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool"));
+  return typeof err.message === "string" && (err.message.includes("Worker pool is shutting down") || err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool") || // worker-pool-manager throws this when auto-recovery is still swapping the
+  // pool. Its own text says "please retry", but until it was listed here no
+  // classifier matched it, so the first attempt rethrew instead of retrying —
+  // and auto-recovery fires only after 3 consecutive worker failures, i.e.
+  // exactly when a burst of tasks is in flight and would all die together.
+  err.message.includes("Worker pool is being reset") || // poolifier's wording once destroy() has COMPLETED (vs "destroying pool"
+  // while it is in progress). A queued closure holding a pool captured before
+  // an auto-recovery destroy dispatches into exactly this window; it is the
+  // same transient swap the "being reset" string covers, not a hard fault.
+  err.message.includes("Cannot execute a task on not started pool"));
 }
 var sessionCircuitBreakers = /* @__PURE__ */ new Map();
 var MAX_SESSION_BREAKERS = 256;
@@ -10921,11 +11547,13 @@ var BrowserServer = class {
         const expected = Buffer.from(getOrCreateAuthSecret(), "utf8");
         const actual = Buffer.from(authHeader ?? "", "utf8");
         if (actual.length !== expected.length || !crypto3.timingSafeEqual(actual, expected)) {
+          req.resume();
           res.writeHead(403, { "Content-Type": "application/json" });
           res.end(JSON.stringify({ error: "Unauthorized" }));
           return;
         }
         if (this.draining) {
+          req.resume();
           res.writeHead(503, {
             "Content-Type": "application/json",
             "Connection": "close"
@@ -10934,16 +11562,17 @@ var BrowserServer = class {
           return;
         }
         if (req.method !== "POST") {
+          req.resume();
           res.writeHead(405);
           res.end("Method Not Allowed");
           return;
         }
-        let body = "";
+        const collected = new Utf8Body();
         let oversized = false;
         const MAX_BODY_SIZE = 10 * 1024 * 1024;
         req.on("data", (chunk) => {
-          body += chunk;
-          if (body.length > MAX_BODY_SIZE) {
+          collected.push(chunk);
+          if (collected.byteLength > MAX_BODY_SIZE) {
             oversized = true;
             req.destroy(new Error("Payload too large"));
           }
@@ -10960,7 +11589,7 @@ var BrowserServer = class {
         });
         req.on("end", async () => {
           try {
-            const data = JSON.parse(body);
+            const data = JSON.parse(collected.toString());
             let result;
             switch (req.url) {
               case "/search":
@@ -11339,10 +11968,10 @@ var PriorityTaskQueue = class {
     this.activeCount++;
     logger.debug(`[PriorityQueue] Starting task: ${task.type}. Active: ${this.activeCount}/${this.maxTotalConcurrency}`);
     let onAbort;
-    const fnPromise = task.fn();
-    fnPromise.catch(() => {
-    });
     try {
+      const fnPromise = task.fn();
+      fnPromise.catch(() => {
+      });
       let result;
       if (task.signal) {
         const abortPromise = new Promise((_, rej) => {
@@ -11408,6 +12037,25 @@ var PriorityTaskQueue = class {
 };
 
 // src/infrastructure/browser/browser-task-scheduler.ts
+var WORKER_DEATH_BACKSTOP_GRACE_MS = 5e3;
+async function executePoolTaskWithDeathBackstop(execute, taskTimeoutMs, label) {
+  const backstopMs = taskTimeoutMs + WORKER_DEATH_BACKSTOP_GRACE_MS;
+  let backstopId;
+  try {
+    return await Promise.race([
+      execute(),
+      new Promise((_, reject) => {
+        backstopId = setTimeout(
+          () => reject(new Error(`${label} task unanswered after ${backstopMs}ms \u2014 worker likely died mid-task`)),
+          backstopMs
+        );
+        if (backstopId.unref) backstopId.unref();
+      })
+    ]);
+  } finally {
+    if (backstopId) clearTimeout(backstopId);
+  }
+}
 var BrowserTaskScheduler = class {
   // 5 minutes (was 30min — wasted RAM)
   constructor(schedulerId, stateManager, container = getServiceContainer()) {
@@ -11535,15 +12183,18 @@ var BrowserTaskScheduler = class {
     });
     logger.debug(`[BrowserTaskScheduler] Executing search: "${query}" (Timeout: ${timeoutMs}ms)`);
     let result;
+    const settled = new AbortController();
+    const queueSignal = signal ? AbortSignal.any([signal, settled.signal]) : settled.signal;
     try {
       const queue = this.getPriorityQueue(config);
       result = await Promise.race([
         queue.enqueue("search", async () => {
-          return await Promise.race([
-            pool.execute({ type: "search", query, queuedAt: startTime, taskTimeoutMs: timeoutMs }),
-            timeoutPromise
-          ]);
-        }, signal),
+          return await executePoolTaskWithDeathBackstop(
+            () => pool.execute({ type: "search", query, queuedAt: startTime, taskTimeoutMs: timeoutMs }),
+            timeoutMs,
+            "Search"
+          );
+        }, queueSignal),
         timeoutPromise
       ]);
       logger.debug(`[BrowserTaskScheduler] Search completed: "${query}" in ${Date.now() - startTime}ms`);
@@ -11563,6 +12214,7 @@ var BrowserTaskScheduler = class {
       throw error;
     } finally {
       if (timeoutId) clearTimeout(timeoutId);
+      settled.abort();
     }
     const duration = Date.now() - startTime;
     metrics.observe("browser_search_duration_ms", duration, { status: "success" });
@@ -11596,15 +12248,18 @@ var BrowserTaskScheduler = class {
       if (timeoutId.unref) timeoutId.unref();
     });
     let result;
+    const settled = new AbortController();
+    const queueSignal = signal ? AbortSignal.any([signal, settled.signal]) : settled.signal;
     try {
       const queue = this.getPriorityQueue(config);
       result = await Promise.race([
         queue.enqueue("scrape", async () => {
-          return await Promise.race([
-            pool.execute({ type: "scrape", url, queuedAt: startTime, taskTimeoutMs: timeoutMs }),
-            timeoutPromise
-          ]);
-        }, signal),
+          return await executePoolTaskWithDeathBackstop(
+            () => pool.execute({ type: "scrape", url, queuedAt: startTime, taskTimeoutMs: timeoutMs }),
+            timeoutMs,
+            "Scrape"
+          );
+        }, queueSignal),
         timeoutPromise
       ]);
     } catch (error) {
@@ -11621,6 +12276,7 @@ var BrowserTaskScheduler = class {
       throw error;
     } finally {
       if (timeoutId) clearTimeout(timeoutId);
+      settled.abort();
     }
     const duration = Date.now() - startTime;
     metrics.observe("browser_scrape_duration_ms", duration, { status: "success" });
@@ -11650,17 +12306,18 @@ var BrowserTaskScheduler = class {
       if (timeoutId.unref) timeoutId.unref();
     });
     let result;
+    const settled = new AbortController();
+    const queueSignal = signal ? AbortSignal.any([signal, settled.signal]) : settled.signal;
     try {
       const queue = this.getPriorityQueue(config);
       result = await Promise.race([
         queue.enqueue("healthcheck", async () => {
-          const execPromise = pool.execute({ type: "healthcheck", queuedAt: startTime, taskTimeoutMs: timeoutMs });
-          execPromise.catch((err) => logger.debug(`[BrowserTaskScheduler] Background healthcheck task rejection: ${err.message}`));
-          return await Promise.race([
-            execPromise,
-            timeoutPromise
-          ]);
-        }, signal),
+          return await executePoolTaskWithDeathBackstop(() => {
+            const execPromise = pool.execute({ type: "healthcheck", queuedAt: startTime, taskTimeoutMs: timeoutMs });
+            execPromise.catch((err) => logger.debug(`[BrowserTaskScheduler] Background healthcheck task rejection: ${err.message}`));
+            return execPromise;
+          }, timeoutMs, "Healthcheck");
+        }, queueSignal),
         timeoutPromise
       ]);
     } catch (error) {
@@ -11677,6 +12334,7 @@ var BrowserTaskScheduler = class {
       throw error;
     } finally {
       if (timeoutId) clearTimeout(timeoutId);
+      settled.abort();
     }
     const duration = Date.now() - startTime;
     metrics.observe("browser_healthcheck_duration_ms", duration, { status: "success" });
@@ -11717,12 +12375,16 @@ var BrowserTaskScheduler = class {
       this.leadershipTimer = null;
     }
     if (!this.container.isDisposing) {
-      const schedulerService = await getService(ServiceNames.SCHEDULER, void 0, this.container);
-      const currentScheduler = schedulerService.getSchedulerInstance();
-      if (currentScheduler && "schedulerId" in currentScheduler && currentScheduler.schedulerId === this.schedulerId) {
-        schedulerService.setSchedulerInstance(null);
-        schedulerService.setSchedulerVersion(null);
-        schedulerService.setSchedulerInitializationPromise(null);
+      try {
+        const schedulerService = await getService(ServiceNames.SCHEDULER, void 0, this.container);
+        const currentScheduler = schedulerService.getSchedulerInstance();
+        if (currentScheduler && "schedulerId" in currentScheduler && currentScheduler.schedulerId === this.schedulerId) {
+          schedulerService.setSchedulerInstance(null);
+          schedulerService.setSchedulerVersion(null);
+          schedulerService.setSchedulerInitializationPromise(null);
+        }
+      } catch (err) {
+        logger.debug("[Scheduler] Could not clear scheduler service reference during shutdown:", err);
       }
     }
     let serverInfo = null;
@@ -11968,6 +12630,15 @@ async function getScheduler(config, container = getServiceContainer()) {
       let wonElection = false;
       let winnerPort = port;
       let winnerAuthSecret;
+      const myStartTime = await (async () => {
+        try {
+          const processLifecycle = await getService(ServiceNames.PROCESS_LIFECYCLE, void 0, container);
+          return await processLifecycle.getCurrentProcessStartTime();
+        } catch (err) {
+          logger.debug("[Scheduler] Could not read own process start time (PID-reuse guard degrades to signal-0):", err);
+          return null;
+        }
+      })();
       try {
         await stateManager.updateState(async (state) => {
           if (state.browserServer) {
@@ -11980,7 +12651,13 @@ async function getScheduler(config, container = getServiceContainer()) {
             }
           }
           const secret = getBrowserServerAuthSecret();
-          state.browserServer = { port, pid: process.pid, schedulerId, authSecret: secret };
+          state.browserServer = {
+            port,
+            pid: process.pid,
+            schedulerId,
+            authSecret: secret,
+            ...myStartTime !== null ? { startTime: myStartTime } : {}
+          };
           state.schedulerVersion = schedulerVersion;
           wonElection = true;
           return state;
@@ -12078,8 +12755,9 @@ init_service_interfaces();
 // src/infrastructure/state/state-manager.ts
 init_config();
 init_logger();
+init_atomic_replace();
 init_metrics();
-import * as fs7 from "node:fs/promises";
+import * as fs8 from "node:fs/promises";
 import * as path8 from "node:path";
 import * as crypto5 from "node:crypto";
 import process2 from "node:process";
@@ -12130,7 +12808,16 @@ var SingletonStateSchema = Type3.Object({
     // cross-embed and corrupt the vector space) — it falls back to a local
     // in-process embedder instead. Optional for entries written by older
     // processes, which are tolerated as matching.
-    model: Type3.Optional(Type3.String())
+    model: Type3.Optional(Type3.String()),
+    // Shared secret a follower must present on every embed request. Mirrors
+    // browserServer.authSecret: the server listens on loopback, but loopback is
+    // not an authorization boundary — any local process could otherwise enqueue
+    // embedding work, and because the serial queue steps the leader down when
+    // poisoned, sustained abuse denies the knowledge store rather than merely
+    // burning GPU. Optional so an entry written by an older leader still parses;
+    // a client that finds none simply sends no header, and such a leader does not
+    // check one either.
+    authSecret: Type3.Optional(Type3.String())
   }))
 });
 
@@ -12347,7 +13034,7 @@ var StateManager = class {
     ];
     for (const dir of dirs) {
       try {
-        await fs7.mkdir(dir, { recursive: true, mode: 448 });
+        await fs8.mkdir(dir, { recursive: true, mode: 448 });
       } catch (err) {
         logger.error(`[StateManager] Failed to create directory ${dir}:`, err);
         throw err;
@@ -12377,14 +13064,14 @@ var StateManager = class {
     const stateDir = path8.dirname(this.stateFilePath);
     const cutoff = Date.now() - STALE_TMP_MS;
     try {
-      const entries = await fs7.readdir(stateDir);
+      const entries = await fs8.readdir(stateDir);
       for (const entry of entries) {
         if (!entry.startsWith("research-state-") || !entry.endsWith(".tmp")) continue;
         const filePath = path8.join(stateDir, entry);
         try {
-          const stats = await fs7.stat(filePath);
+          const stats = await fs8.stat(filePath);
           if (!stats.isFile() || stats.mtimeMs >= cutoff) continue;
-          await fs7.unlink(filePath);
+          await fs8.unlink(filePath);
           logger.debug(`[StateManager] Removed orphaned state temp file: ${entry}`);
         } catch {
         }
@@ -12415,7 +13102,7 @@ var StateManager = class {
       return this.getDefaultState();
     }
     try {
-      const content = await fs7.readFile(this.stateFilePath, "utf-8");
+      const content = await fs8.readFile(this.stateFilePath, "utf-8");
       const state = JSON.parse(content);
       return this.validator.migrateAndValidate(state);
     } catch (error) {
@@ -12444,7 +13131,7 @@ var StateManager = class {
         );
         try {
           await this.recoverFromCorruptionDirect();
-          const recovered = await fs7.readFile(this.stateFilePath, "utf-8");
+          const recovered = await fs8.readFile(this.stateFilePath, "utf-8");
           return this.validator.migrateAndValidate(JSON.parse(recovered));
         } catch (recoveryError) {
           logger.error(
@@ -12505,26 +13192,24 @@ var StateManager = class {
       const tempFileName = `research-state-${crypto5.randomBytes(16).toString("hex")}.tmp`;
       tempFilePath = path8.join(path8.dirname(this.stateFilePath), tempFileName);
       const content = JSON.stringify(state, null, 2);
-      const fh = await fs7.open(tempFilePath, "w", 384);
+      const fh = await fs8.open(tempFilePath, "w", 384);
       try {
         await fh.writeFile(content, { encoding: "utf-8" });
         await fh.sync();
       } finally {
         await fh.close();
       }
-      try {
-        await fs7.rename(tempFilePath, this.stateFilePath);
-      } catch (renameErr) {
-        if (process2.platform === "win32") {
-          await fs7.copyFile(tempFilePath, this.stateFilePath);
-          const tmp = tempFilePath;
-          tempFilePath = null;
-          await fs7.unlink(tmp).catch((err) => {
-            logger.warn("[StateManager] Failed to remove temp file after copy fallback (write succeeded):", err);
-          });
-        } else {
-          throw renameErr;
-        }
+      const outcome = await replaceFile(tempFilePath, this.stateFilePath);
+      if (outcome === "copied") {
+        logger.warn(
+          "[StateManager] State written via non-atomic copy: the rename was blocked by another process holding the state file. A concurrent reader may observe a partial file."
+        );
+        metrics.increment("state_write_non_atomic_total", 1);
+        const tmp = tempFilePath;
+        tempFilePath = null;
+        await fs8.unlink(tmp).catch((err) => {
+          logger.warn("[StateManager] Failed to remove temp file after copy fallback (write succeeded):", err);
+        });
       }
       tempFilePath = null;
       await this.backupManager.cleanupOldBackups();
@@ -12532,7 +13217,7 @@ var StateManager = class {
       throw new Error(`Failed to write state: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     } finally {
       if (tempFilePath) {
-        await fs7.unlink(tempFilePath).catch((err) => {
+        await fs8.unlink(tempFilePath).catch((err) => {
           logger.warn("[StateManager] Failed to clean up temp file:", err);
         });
       }
@@ -12962,8 +13647,23 @@ var MetricsService = class {
 // src/infrastructure/process-lifecycle-service.ts
 init_service_registry();
 init_service_names();
-import * as fs8 from "node:fs/promises";
+import * as fs9 from "node:fs/promises";
 import { execFile } from "node:child_process";
+function parseEtime(value) {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(value.trim());
+  if (!m) return null;
+  const days = m[1] ? parseInt(m[1], 10) : 0;
+  const hours = m[2] ? parseInt(m[2], 10) : 0;
+  const minutes = parseInt(m[3], 10);
+  const seconds = parseInt(m[4], 10);
+  if ([days, hours, minutes, seconds].some((n) => isNaN(n))) return null;
+  return days * 86400 + hours * 3600 + minutes * 60 + seconds;
+}
+function isDefinitelyGone(err) {
+  const code = err?.code;
+  if (code === "EPERM" || code === "EACCES") return false;
+  return true;
+}
 var ProcessLifecycleService = class {
   name = ServiceNames.PROCESS_LIFECYCLE;
   lifecycle = "uninitialized" /* UNINITIALIZED */;
@@ -12984,7 +13684,7 @@ var ProcessLifecycleService = class {
   async getProcessStartTime(pid) {
     if (process.platform === "linux") {
       try {
-        const stat5 = await fs8.readFile(`/proc/${pid}/stat`, "utf8");
+        const stat5 = await fs9.readFile(`/proc/${pid}/stat`, "utf8");
         const lastParenIndex = stat5.lastIndexOf(")");
         if (lastParenIndex === -1) return null;
         const partsAfterName = stat5.substring(lastParenIndex + 2).trim().split(/\s+/);
@@ -13012,23 +13712,35 @@ var ProcessLifecycleService = class {
         return null;
       }
     }
-    try {
-      const output = await new Promise((resolve8, reject) => {
-        const child = execFile(
-          "ps",
-          ["-o", "etimes=", "-p", String(pid)],
-          { encoding: "utf8", timeout: 3e3 },
-          (err, stdout) => err ? reject(err) : resolve8(stdout)
-        );
-        child.unref?.();
-      });
-      if (!output || !output.trim()) return null;
-      const elapsedSec = parseInt(output.trim(), 10);
-      if (isNaN(elapsedSec)) return null;
-      return Math.floor(Date.now() / 1e3) - elapsedSec;
-    } catch {
-      return null;
+    const elapsedSec = await this.readElapsedSeconds(pid);
+    if (elapsedSec === null) return null;
+    return Math.floor(Date.now() / 1e3) - elapsedSec;
+  }
+  /** Elapsed seconds for `pid` via ps, or null. Tries `etimes`, then POSIX `etime`. */
+  async readElapsedSeconds(pid) {
+    const run = async (fmt) => {
+      try {
+        return await new Promise((resolve8, reject) => {
+          const child = execFile(
+            "ps",
+            ["-o", fmt, "-p", String(pid)],
+            { encoding: "utf8", timeout: 3e3 },
+            (err, stdout) => err ? reject(err) : resolve8(stdout)
+          );
+          child.unref?.();
+        });
+      } catch {
+        return null;
+      }
+    };
+    const etimes = await run("etimes=");
+    if (etimes && etimes.trim()) {
+      const n = parseInt(etimes.trim(), 10);
+      if (!isNaN(n)) return n;
     }
+    const etime = await run("etime=");
+    if (etime && etime.trim()) return parseEtime(etime.trim());
+    return null;
   }
   /**
    * Get the start time for the current process
@@ -13049,17 +13761,25 @@ var ProcessLifecycleService = class {
   async isProcessAlive(pid, expectedStartTime) {
     try {
       process.kill(pid, 0);
+    } catch (err) {
+      if (isDefinitelyGone(err)) return false;
+    }
+    try {
       if (expectedStartTime !== void 0 && expectedStartTime !== null) {
         const actualStartTime = await this.getProcessStartTime(pid);
         if (actualStartTime === null) {
-          process.kill(pid, 0);
-          return true;
+          try {
+            process.kill(pid, 0);
+            return true;
+          } catch (reconfirmErr) {
+            return !isDefinitelyGone(reconfirmErr);
+          }
         }
         return Math.abs(actualStartTime - expectedStartTime) <= 1;
       }
       return true;
     } catch {
-      return false;
+      return true;
     }
   }
   /**
@@ -13069,8 +13789,8 @@ var ProcessLifecycleService = class {
     try {
       process.kill(pid, 0);
       return true;
-    } catch {
-      return false;
+    } catch (err) {
+      return !isDefinitelyGone(err);
     }
   }
   /**
@@ -13567,7 +14287,7 @@ var StateValidator = class {
 init_logger();
 init_metrics();
 init_config();
-import { dirname as dirname7, join as join11 } from "node:path";
+import { dirname as dirname7, join as join12 } from "node:path";
 import { existsSync as existsSync7 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { FixedClusterPool, WorkerChoiceStrategies } from "poolifier";
@@ -13578,7 +14298,7 @@ import { spawn } from "node:child_process";
 import { createRequire as createRequire3 } from "node:module";
 import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync6, readdirSync as readdirSync2, statSync as statSync3, fstatSync, openSync as openSync3, closeSync as closeSync3, rmSync } from "node:fs";
-import { join as join9, dirname as dirname6 } from "node:path";
+import { join as join10, dirname as dirname6 } from "node:path";
 import { tmpdir as tmpdir2 } from "node:os";
 var FETCH_TIMEOUT_MS = 15 * 60 * 1e3;
 var STALE_LOCK_MS = 20 * 60 * 1e3;
@@ -13591,7 +14311,7 @@ function isBrowserBinaryPresent() {
     if (!existsSync6(cacheDir)) return false;
     return readdirSync2(cacheDir).some((entry) => {
       try {
-        return statSync3(join9(cacheDir, entry)).isDirectory();
+        return statSync3(join10(cacheDir, entry)).isDirectory();
       } catch {
         return false;
       }
@@ -13604,7 +14324,7 @@ function resolveCamoufoxBin() {
   try {
     const require2 = createRequire3(import.meta.url);
     const pkgJson = require2.resolve("camoufox-js/package.json");
-    const bin = join9(dirname6(pkgJson), "..", ".bin", process.platform === "win32" ? "camoufox-js.cmd" : "camoufox-js");
+    const bin = join10(dirname6(pkgJson), "..", ".bin", process.platform === "win32" ? "camoufox-js.cmd" : "camoufox-js");
     if (existsSync6(bin)) return bin;
   } catch {
   }
@@ -13648,7 +14368,7 @@ async function provision() {
     return;
   }
   const cacheKey = createHash2("sha256").update(getCamoufoxBinaryPath()).digest("hex").slice(0, 16);
-  const lockPath = join9(tmpdir2(), `pi-research-camoufox-fetch-${cacheKey}.lock`);
+  const lockPath = join10(tmpdir2(), `pi-research-camoufox-fetch-${cacheKey}.lock`);
   let haveLock = false;
   try {
     closeSync3(openSync3(lockPath, "wx", 384));
@@ -13703,12 +14423,26 @@ function ensureBrowserInstalled() {
 
 // src/infrastructure/browser/cleanup-utils.ts
 init_logger();
-import * as fs9 from "node:fs/promises";
+import * as fs10 from "node:fs/promises";
 import * as path9 from "node:path";
 import * as os4 from "node:os";
 var DEFAULT_STALE_MS = 30 * 24 * 60 * 60 * 1e3;
 var LOCK_FILE_NAMES = ["lock", ".parentlock", "parent.lock"];
 var LOCK_FRESHNESS_MS = 2 * 60 * 1e3;
+async function isWindowsParentLockHeld(lockPath) {
+  let handle;
+  try {
+    handle = await fs10.open(lockPath, "r");
+  } catch (e) {
+    const code = e?.code;
+    if (code === "ENOENT") return false;
+    if (code === "EBUSY" || code === "EPERM" || code === "EACCES") return true;
+    return null;
+  }
+  await handle.close().catch(() => {
+  });
+  return false;
+}
 function parsePidFromLockTarget(target) {
   const m = /\+(\d+)\s*$/.exec(target);
   if (!m) return null;
@@ -13728,17 +14462,22 @@ async function isProfileLive(profileDir) {
     const lockPath = path9.join(profileDir, name);
     let lst;
     try {
-      lst = await fs9.lstat(lockPath);
+      lst = await fs10.lstat(lockPath);
     } catch {
       continue;
     }
     if (lst.isSymbolicLink()) {
       try {
-        const pid = parsePidFromLockTarget(await fs9.readlink(lockPath));
+        const pid = parsePidFromLockTarget(await fs10.readlink(lockPath));
         if (pid !== null) return isPidAlive(pid);
       } catch {
       }
     }
+    if (process.platform === "win32" && name === "parent.lock") {
+      const held = await isWindowsParentLockHeld(lockPath);
+      if (held !== null) return held;
+      return true;
+    }
     return Date.now() - lst.mtimeMs < LOCK_FRESHNESS_MS;
   }
   return false;
@@ -13750,19 +14489,19 @@ async function cleanupStaleProfiles(baseDir, staleMs = DEFAULT_STALE_MS) {
   let removed = 0;
   let errors = 0;
   try {
-    const entries = await fs9.readdir(scanDir);
+    const entries = await fs10.readdir(scanDir);
     const now = Date.now();
     for (const entry of entries) {
       if (usePrefix && !entry.startsWith(prefix)) continue;
       const fullPath = path9.join(scanDir, entry);
       try {
-        const stats = await fs9.stat(fullPath);
+        const stats = await fs10.stat(fullPath);
         if (!stats.isDirectory()) continue;
         const isProfileLike = entry.startsWith(prefix) || entry.startsWith("playwright-artifacts-");
         if (isProfileLike) {
-          const inner = await fs9.readdir(fullPath);
+          const inner = await fs10.readdir(fullPath);
           if (inner.length === 0) {
-            await fs9.rmdir(fullPath);
+            await fs10.rmdir(fullPath);
             removed++;
             continue;
           }
@@ -13770,12 +14509,12 @@ async function cleanupStaleProfiles(baseDir, staleMs = DEFAULT_STALE_MS) {
             logger.debug(`[Cleanup] Skipping profile ${entry} \u2014 owned by a live browser`);
             continue;
           }
-          await fs9.rm(fullPath, { recursive: true, force: true });
+          await fs10.rm(fullPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
           removed++;
           continue;
         }
         if (now - stats.mtimeMs > staleMs && !await isProfileLive(fullPath)) {
-          await fs9.rm(fullPath, { recursive: true, force: true });
+          await fs10.rm(fullPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
           removed++;
         }
       } catch (_e) {
@@ -13795,7 +14534,7 @@ async function cleanupStaleProfiles(baseDir, staleMs = DEFAULT_STALE_MS) {
 init_log_utils();
 import process3 from "node:process";
 import cluster from "node:cluster";
-import * as fs10 from "node:fs/promises";
+import * as fs11 from "node:fs/promises";
 var workerId = "";
 var BENIGN_IPC_CODES = /* @__PURE__ */ new Set(["EPIPE", "ERR_IPC_CHANNEL_CLOSED", "ECONNRESET"]);
 function isBenignClusterIpcError(err) {
@@ -13856,7 +14595,7 @@ function logToDebugFile(level, ...args) {
         return String(arg);
       }).join(" "))
     };
-    fs10.appendFile(logFile, `${JSON.stringify(entry)}
+    fs11.appendFile(logFile, `${JSON.stringify(entry)}
 `).catch(() => {
     });
   } catch {
@@ -13931,6 +14670,7 @@ var WorkerPoolManager = class {
       try {
         if (this.pool && this.currentWorkerCount !== maxWorkers) {
           logger.log(`[WorkerPoolManager] Worker count changed from ${this.currentWorkerCount} to ${maxWorkers}, recreating pool...`);
+          this.poolEpoch++;
           await this.pool.destroy();
           this.pool = null;
         }
@@ -13945,7 +14685,7 @@ var WorkerPoolManager = class {
         void cleanupStaleProfiles(void 0, STALE_PROFILE_MS).catch((e) => logger.debug("[WorkerPoolManager] Profile sweep (legacy tmp) failed:", e));
         void cleanupOrphanedCamoufoxProcesses().catch((e) => logger.debug("[WorkerPoolManager] Startup orphan sweep failed:", e));
         const workerConcurrency = (config || getConfig()).WORKER_CONCURRENCY;
-        const workerPath = join11(__dirname, "./thread-worker.mjs");
+        const workerPath = join12(__dirname, "./thread-worker.mjs");
         if (!existsSync7(workerPath)) {
           throw new Error(
             `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.`
@@ -13975,7 +14715,7 @@ var WorkerPoolManager = class {
             }
           },
           exitHandler: (code) => {
-            if (code !== 0 && code !== null && this.poolEpoch === myEpoch) {
+            if (code !== 0 && this.poolEpoch === myEpoch) {
               logger.error(`[WorkerPoolManager] Worker exited with code ${code}`);
               this.consecutiveErrors++;
               if (this.consecutiveErrors >= 3) {
@@ -13998,6 +14738,7 @@ var WorkerPoolManager = class {
           logger.warn("[WorkerPoolManager] Pool initialized but a shutdown intervened. Destroying...");
           const built = this.pool;
           if (this.pool === built) this.pool = null;
+          this.poolEpoch++;
           await built.destroy().catch((err) => logger.debug("Swallowed pool destroy error:", err));
           throw new Error("Worker pool is shutting down");
         }
@@ -14058,6 +14799,7 @@ var WorkerPoolManager = class {
     const t = setTimeout(async () => {
       try {
         if (this.isShuttingDown || this.generation !== myGen) return;
+        this.poolEpoch++;
         if (deadPool) await deadPool.destroy();
         logger.info("[WorkerPoolManager] Auto-recovery: old pool destroyed.");
       } catch (err) {
@@ -14098,6 +14840,7 @@ var WorkerPoolManager = class {
     }
     if (this.pool) {
       try {
+        this.poolEpoch++;
         const destroyPromise = this.pool.destroy();
         destroyPromise.catch((err) => logger.debug(`[WorkerPoolManager] Background pool destroy rejection: ${err.message}`));
         await raceWithDeadline(destroyPromise, 5e3);
@@ -14275,7 +15018,7 @@ var ResearchRunSemaphore = class {
     if (this._initialized) return;
     this.lifecycle = "initializing" /* INITIALIZING */;
     try {
-      await import("node:fs/promises").then((fs17) => fs17.mkdir(this.slotDir, { recursive: true, mode: 448 }));
+      await import("node:fs/promises").then((fs18) => fs18.mkdir(this.slotDir, { recursive: true, mode: 448 }));
     } catch (err) {
       logger.warn(`[ResearchRunSemaphore] Could not create slot dir ${this.slotDir}: ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -14410,9 +15153,10 @@ function sleep(ms, signal) {
 
 // src/infrastructure/state/state-backup-manager.ts
 init_logger();
+init_atomic_replace();
 init_service_registry();
 init_service_names();
-import * as fs11 from "node:fs/promises";
+import * as fs12 from "node:fs/promises";
 import * as crypto6 from "node:crypto";
 import * as path11 from "node:path";
 var QUARANTINE_KEEP = 5;
@@ -14436,7 +15180,7 @@ var StateBackupManager = class {
       return;
     }
     this.lifecycle = "initializing" /* INITIALIZING */;
-    await fs11.mkdir(this.backupDirPath, { recursive: true, mode: 448 });
+    await fs12.mkdir(this.backupDirPath, { recursive: true, mode: 448 });
     this._initialized = true;
     this.lifecycle = "initialized" /* INITIALIZED */;
   }
@@ -14450,15 +15194,15 @@ var StateBackupManager = class {
   async createBackup() {
     try {
       try {
-        await fs11.access(this.stateFilePath);
+        await fs12.access(this.stateFilePath);
       } catch {
         return;
       }
-      await fs11.mkdir(this.backupDirPath, { recursive: true, mode: 448 });
+      await fs12.mkdir(this.backupDirPath, { recursive: true, mode: 448 });
       const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
       const backupFileName = `research-state-${timestamp}-${crypto6.randomBytes(4).toString("hex")}.json`;
       const backupFilePath = path11.join(this.backupDirPath, backupFileName);
-      await fs11.copyFile(this.stateFilePath, backupFilePath);
+      await fs12.copyFile(this.stateFilePath, backupFilePath);
     } catch (error) {
       throw new Error(`Failed to create backup: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
@@ -14468,14 +15212,14 @@ var StateBackupManager = class {
    */
   async cleanupOldBackups() {
     try {
-      const entries = await fs11.readdir(this.backupDirPath);
+      const entries = await fs12.readdir(this.backupDirPath);
       if (entries.length <= this.maxBackups) {
         return;
       }
       const backupFiles = [];
       for (const entry of entries) {
         const filePath = path11.join(this.backupDirPath, entry);
-        const stats = await fs11.stat(filePath);
+        const stats = await fs12.stat(filePath);
         if (stats.isFile() && entry.startsWith("research-state-") && entry.endsWith(".json")) {
           backupFiles.push({ name: entry, mtime: stats.mtime });
         }
@@ -14484,7 +15228,7 @@ var StateBackupManager = class {
       const backupsToRemove = backupFiles.slice(this.maxBackups);
       for (const backupFile of backupsToRemove) {
         const filePath = path11.join(this.backupDirPath, backupFile.name);
-        await fs11.unlink(filePath);
+        await fs12.unlink(filePath);
       }
     } catch (error) {
       logger.error(`Failed to cleanup old backups: ${error instanceof Error ? error.message : String(error)}`);
@@ -14497,10 +15241,10 @@ var StateBackupManager = class {
     try {
       let backups = [];
       try {
-        const entries = await fs11.readdir(this.backupDirPath);
+        const entries = await fs12.readdir(this.backupDirPath);
         for (const entry of entries) {
           const filePath = path11.join(this.backupDirPath, entry);
-          const stats = await fs11.stat(filePath);
+          const stats = await fs12.stat(filePath);
           if (stats.isFile() && entry.startsWith("research-state-") && entry.endsWith(".json")) {
             backups.push({ name: entry, mtime: stats.mtime });
           }
@@ -14512,7 +15256,7 @@ var StateBackupManager = class {
         const backupPath = path11.join(this.backupDirPath, backup.name);
         let restoreContent;
         try {
-          const content = await fs11.readFile(backupPath, "utf-8");
+          const content = await fs12.readFile(backupPath, "utf-8");
           const validated = this.validator.migrateAndValidate(JSON.parse(content));
           restoreContent = JSON.stringify(validated, null, 2);
         } catch (err) {
@@ -14540,27 +15284,27 @@ var StateBackupManager = class {
    */
   async quarantineFutureState(fileVersion) {
     try {
-      await fs11.access(this.stateFilePath);
+      await fs12.access(this.stateFilePath);
     } catch {
       return;
     }
-    await fs11.mkdir(this.backupDirPath, { recursive: true, mode: 448 });
+    await fs12.mkdir(this.backupDirPath, { recursive: true, mode: 448 });
     const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     const name = `research-state-future-v${fileVersion}-${timestamp}.quarantine`;
     const dest = path11.join(this.backupDirPath, name);
-    await fs11.copyFile(this.stateFilePath, dest);
+    await fs12.copyFile(this.stateFilePath, dest);
     logger.warn(`[StateManager] Quarantined newer-build state (v${fileVersion}) copy at ${dest}`);
     await this.pruneQuarantineFiles(QUARANTINE_KEEP);
   }
   /** Keep only the newest `keep` *.quarantine files; delete the rest. Best-effort. */
   async pruneQuarantineFiles(keep) {
     try {
-      const entries = await fs11.readdir(this.backupDirPath);
+      const entries = await fs12.readdir(this.backupDirPath);
       const quarantines = [];
       for (const entry of entries) {
         if (!entry.endsWith(".quarantine")) continue;
         try {
-          const stats = await fs11.stat(path11.join(this.backupDirPath, entry));
+          const stats = await fs12.stat(path11.join(this.backupDirPath, entry));
           if (stats.isFile()) quarantines.push({ name: entry, mtime: stats.mtimeMs });
         } catch {
         }
@@ -14569,7 +15313,7 @@ var StateBackupManager = class {
       quarantines.sort((a, b) => b.mtime - a.mtime);
       for (const stale of quarantines.slice(keep)) {
         try {
-          await fs11.unlink(path11.join(this.backupDirPath, stale.name));
+          await fs12.unlink(path11.join(this.backupDirPath, stale.name));
         } catch {
         }
       }
@@ -14582,10 +15326,10 @@ var StateBackupManager = class {
    */
   async atomicWriteStateFile(content) {
     const stateDir = path11.dirname(this.stateFilePath);
-    await fs11.mkdir(stateDir, { recursive: true, mode: 448 });
+    await fs12.mkdir(stateDir, { recursive: true, mode: 448 });
     const tempFile = `research-state-${crypto6.randomBytes(16).toString("hex")}.tmp`;
     const tempPath = path11.join(stateDir, tempFile);
-    const fh = await fs11.open(tempPath, "w", 384);
+    const fh = await fs12.open(tempPath, "w", 384);
     try {
       await fh.writeFile(content, { encoding: "utf-8" });
       await fh.sync();
@@ -14593,17 +15337,14 @@ var StateBackupManager = class {
       await fh.close();
     }
     try {
-      await fs11.rename(tempPath, this.stateFilePath);
-    } catch (renameErr) {
-      if (process.platform === "win32") {
-        await fs11.copyFile(tempPath, this.stateFilePath);
-        await fs11.unlink(tempPath).catch(() => {
-        });
-      } else {
-        await fs11.unlink(tempPath).catch(() => {
+      if (await replaceFile(tempPath, this.stateFilePath) === "copied") {
+        await fs12.unlink(tempPath).catch(() => {
         });
-        throw renameErr;
       }
+    } catch (renameErr) {
+      await fs12.unlink(tempPath).catch(() => {
+      });
+      throw renameErr;
     }
   }
   /**
@@ -14910,6 +15651,41 @@ async function recoverFromLeaderHandover(container) {
     (err) => logger.debug("Wait for browser idle timed out or failed:", err)
   );
 }
+async function isRegisteredLeaderAliveUncached(container) {
+  try {
+    const stateManager = await getService(ServiceNames.STATE_MANAGER, void 0, container);
+    const info = await stateManager.getBrowserServer();
+    if (!info) return false;
+    const schedulerService = await getService(ServiceNames.SCHEDULER, void 0, container);
+    const cached = schedulerService.getSchedulerInstance();
+    if (cached instanceof BrowserClient && cached.targetPort !== info.port) return false;
+    return await stateManager.isPidAlive(info.pid, info.schedulerId);
+  } catch {
+    return false;
+  }
+}
+var LEADER_LIVENESS_COALESCE_MS = 1e3;
+var leaderLivenessProbe = null;
+async function isRegisteredLeaderAlive(container) {
+  const now = Date.now();
+  if (leaderLivenessProbe && now - leaderLivenessProbe.startedAt < LEADER_LIVENESS_COALESCE_MS) {
+    return leaderLivenessProbe.result;
+  }
+  const result = isRegisteredLeaderAliveUncached(container);
+  leaderLivenessProbe = { startedAt: now, result };
+  return result;
+}
+async function restartSchedulerWithHerdGuard(container) {
+  const now = Date.now();
+  if (now - lastRestartTime > RESTART_COOLDOWN_MS || !await isRegisteredLeaderAlive(container)) {
+    lastRestartTime = now;
+    logger.warn("[BrowserManager] Forcing scheduler restart and retrying...");
+    await forceSchedulerRestart2(false, container);
+  } else {
+    logger.warn("[BrowserManager] Scheduler restart triggered recently and the registered leader is still alive \u2014 waiting for pool idle instead...");
+  }
+  await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
+}
 async function getScheduler2(config, container = getServiceContainer()) {
   try {
     const factory = await getService(ServiceNames.SCHEDULER_FACTORY, void 0, container);
@@ -14972,16 +15748,7 @@ async function runBrowserTask(taskOrUrl, type = "scrape", config, signal, retrie
         logger.warn(`[BrowserManager] Pool is draining \u2014 waiting for pool idle before retry...`);
         await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
       } else {
-        const now = Date.now();
-        if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
-          lastRestartTime = now;
-          logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(false, container);
-          await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
-        } else {
-          logger.warn(`[BrowserManager] Scheduler restart recently triggered, waiting for pool idle...`);
-          await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
-        }
+        await restartSchedulerWithHerdGuard(container);
       }
       const jitter = 100 + Math.floor(Math.random() * 400);
       await new Promise((resolve8) => setTimeout(resolve8, jitter));
@@ -15007,15 +15774,7 @@ async function runBrowserHealthCheck(config, retries = 1, signal, container = ge
       if (isPoolShutdownError(error)) {
         await recoverFromLeaderHandover(container);
       } else {
-        const now = Date.now();
-        if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
-          lastRestartTime = now;
-          logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(false, container);
-          await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
-        } else {
-          await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
-        }
+        await restartSchedulerWithHerdGuard(container);
       }
       const jitter = 100 + Math.floor(Math.random() * 400);
       await new Promise((resolve8) => setTimeout(resolve8, jitter));
@@ -15059,15 +15818,7 @@ async function runWorkerSearch(query, config, signal, retries = 1, sessionId, co
       if (isPoolShutdownError(error)) {
         await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
       } else {
-        const now = Date.now();
-        if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
-          lastRestartTime = now;
-          logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(false, container);
-          await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
-        } else {
-          await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
-        }
+        await restartSchedulerWithHerdGuard(container);
       }
       const jitter = 100 + Math.floor(Math.random() * 400);
       await new Promise((resolve8) => setTimeout(resolve8, jitter));
@@ -15083,7 +15834,7 @@ init_safe_unref();
 init_url_utils();
 init_metrics();
 init_service_registry();
-async function performSearch(queries, config, signal, onProgress, container = getServiceContainer()) {
+async function performSearch(queries, config, signal, onProgress, container = getServiceContainer(), failures) {
   const startTime = Date.now();
   const resultMap = /* @__PURE__ */ new Map();
   const seenUrls = /* @__PURE__ */ new Set();
@@ -15106,7 +15857,7 @@ async function performSearch(queries, config, signal, onProgress, container = ge
   logger.log(`[Search] Orchestrating ${queries.length} queries across ${maxWorkers} worker processes...`);
   if (onProgress) onProgress(0);
   const QUERY_TIMEOUT_MS = (config?.SEARCH_TIMEOUT_MS ?? 45e3) + (config?.BROWSER_TASK_TIMEOUT_MS ?? 1e4);
-  const filteredQueries = queries.filter((q) => q.trim());
+  const filteredQueries = [...new Set(queries.filter((q) => q.trim()))];
   let timeoutCount = 0;
   let errorCount = 0;
   let sampleWorkerError = "";
@@ -15151,11 +15902,24 @@ async function performSearch(queries, config, signal, onProgress, container = ge
       metrics.increment("browser_search_queries_total", 1, { status });
       if (isTimeout) {
         logger.warn(`[Search] Query timed out after ${QUERY_TIMEOUT_MS}ms \u2014 likely starved waiting for a free browser worker under concurrent load, or a slow/blocked search provider: "${query}"`);
+        failures?.set(query, {
+          type: "timeout",
+          message: `Search timed out after ${QUERY_TIMEOUT_MS}ms before returning anything. This says nothing about the query \u2014 the browser pool was saturated or the search provider was slow/blocked. Retrying the same query later is reasonable.`
+        });
       } else {
         const msg2 = error instanceof Error ? error.message : String(error);
         if (msg2 !== "Aborted") {
           if (!sampleWorkerError) sampleWorkerError = msg2;
           logger.error(`[Search] Worker failed for "${query}": ${msg2}`);
+          failures?.set(query, {
+            type: "service_unavailable",
+            message: `The search backend failed for this query (${msg2}). This is an infrastructure failure, not a signal about the query itself \u2014 do not rewrite the query in response to it.`
+          });
+        } else if (!signal?.aborted) {
+          failures?.set(query, {
+            type: "service_unavailable",
+            message: "The search task was cancelled on the worker side (pool drain or leader handover) before completing. This says nothing about the query \u2014 do not rewrite it; retrying the same query later is reasonable."
+          });
         }
       }
       resultMap.set(query, []);
@@ -15165,6 +15929,9 @@ async function performSearch(queries, config, signal, onProgress, container = ge
     }
   });
   await Promise.all(searchTasks);
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
   const totalResults = Array.from(resultMap.values()).reduce((sum, r) => sum + r.length, 0);
   if (totalResults === 0 && filteredQueries.length > 0) {
     metrics.increment("browser_search_total_failures_total", 1);
@@ -15195,7 +15962,8 @@ async function search(queries, config, signal, onProgress, container = getServic
   metrics.observe("search_query_count_per_request", queries.length);
   const searchStart = Date.now();
   try {
-    const resultMap = await performSearch(queries, config, signal, onProgress, container);
+    const failures = /* @__PURE__ */ new Map();
+    const resultMap = await performSearch(queries, config, signal, onProgress, container, failures);
     const searchDuration = Date.now() - searchStart;
     metrics.observe("search_latency_ms", searchDuration);
     let totalResults = 0;
@@ -15209,7 +15977,7 @@ async function search(queries, config, signal, onProgress, container = getServic
         successfulQueries++;
         metrics.observe("search_results_per_query", qResults.length);
       } else {
-        result.error = {
+        result.error = failures.get(q) ?? {
           type: "empty_results",
           message: "Browser-based search returned no relevant results for this query (the query may be too narrow, or the site returned nothing usable)."
         };
@@ -15224,10 +15992,13 @@ async function search(queries, config, signal, onProgress, container = getServic
     return results;
   } catch (error) {
     const searchDuration = Date.now() - searchStart;
+    const message = error instanceof Error ? error.message : String(error);
+    if (signal?.aborted || message === "Aborted") {
+      throw error;
+    }
     metrics.observe("search_latency_ms", searchDuration, { status: "error" });
     metrics.increment("search_queries_total", queries.length, { status: "error" });
     metrics.increment("search_errors_total", 1, { error_type: "search_failed" });
-    const message = error instanceof Error ? error.message : String(error);
     if (message.includes("Search completely failed")) {
       metrics.increment("search_errors_total", 1, { error_type: "total_search_failure" });
       throw error;
@@ -15602,7 +16373,9 @@ function createSearchTool(options) {
           markdown += `## Query ${i + 1}: ${r.query}
 `;
           if (r.results.length === 0) {
-            markdown += `*No results found.*
+            markdown += r.error ? `*${r.error.message}*
+
+` : `*No results found.*
 
 `;
           } else {
@@ -15746,7 +16519,7 @@ init_logger();
 import * as dns from "node:dns/promises";
 import * as dnsCb from "node:dns";
 import * as net3 from "node:net";
-import crypto8 from "node:crypto";
+import crypto9 from "node:crypto";
 import { NodeHtmlMarkdown } from "node-html-markdown";
 function isBenignScrapeFailure(error) {
   const msg2 = error instanceof Error ? error.message : String(error);
@@ -15757,7 +16530,7 @@ function isBenignScrapeFailure(error) {
 }
 function getRandomUserAgent() {
   try {
-    const index = crypto8.randomInt(0, USER_AGENTS.length);
+    const index = crypto9.randomInt(0, USER_AGENTS.length);
     const userAgent = USER_AGENTS[index];
     return userAgent ?? USER_AGENTS[0];
   } catch {
@@ -15999,6 +16772,7 @@ function validateContent(html, markdown, url) {
 // src/web-research/web-scraper.ts
 init_retry_utils();
 init_safe_unref();
+init_http_body();
 init_service_registry();
 var FETCH_RETRY_DELAY_MS = 250;
 var playwrightAvailable = false;
@@ -16095,48 +16869,6 @@ function decodeHtmlBody(bytes, contentTypeHeader) {
     return new TextDecoder("utf-8").decode(bytes);
   }
 }
-var BodyTooLargeError = class extends Error {
-  constructor(bytesRead, maxBytes) {
-    super(`Response body exceeded ${maxBytes} byte cap`);
-    this.bytesRead = bytesRead;
-    this.maxBytes = maxBytes;
-    this.name = "BodyTooLargeError";
-  }
-  bytesRead;
-  maxBytes;
-};
-async function readBodyCapped(response, maxBytes) {
-  const body = response.body;
-  if (!body || typeof body.getReader !== "function") {
-    return new Uint8Array(await response.arrayBuffer());
-  }
-  const reader = body.getReader();
-  const chunks = [];
-  let total = 0;
-  try {
-    for (; ; ) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (value) {
-        total += value.byteLength;
-        if (total > maxBytes) throw new BodyTooLargeError(total, maxBytes);
-        chunks.push(value);
-      }
-    }
-  } finally {
-    try {
-      await reader.cancel();
-    } catch {
-    }
-  }
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const c of chunks) {
-    out.set(c, offset);
-    offset += c.byteLength;
-  }
-  return out;
-}
 function trackFetchLayerFailure(url, error) {
   const isSsrf = error instanceof Error && error.message.includes("not allowed");
   errorTracker.trackError(error instanceof Error ? error : String(error), {
@@ -16710,6 +17442,7 @@ init_retry_utils();
 init_circuit_breaker();
 init_safe_unref();
 init_metrics();
+init_http_body();
 
 // src/security/nvd-types.ts
 function isWeaknessDescription(value) {
@@ -16998,18 +17731,20 @@ async function fetchPaginated(term, options, maxResults, severityVersion, admitE
     const response = await fetchWithRetry(url, signal);
     let data;
     try {
-      data = await response.json();
-    } catch {
-      metrics.increment("nvd_search_errors_total", 1, { error_type: "malformed_json" });
+      data = await readJsonCapped(response, MAX_BULK_JSON_BODY_BYTES);
+    } catch (err) {
+      metrics.increment("nvd_search_errors_total", 1, {
+        error_type: err instanceof BodyTooLargeError ? "body_too_large" : "malformed_json"
+      });
       break;
     }
     const rawEntries = extractNVDEntries(data);
     const admitted = rawEntries.filter(admitEntry).map((entry) => parseNVDEntry(entry, options));
     if (rawEntries.length === 0) {
-      metrics.increment("nvd_cache_misses_total", 1, { term });
+      metrics.increment("nvd_cache_misses_total", 1);
       break;
     }
-    metrics.increment("nvd_cache_hits_total", 1, { term });
+    metrics.increment("nvd_cache_hits_total", 1);
     allVulnerabilities.push(...admitted);
     const responseData = data;
     if (responseData?.["totalResults"] !== void 0 && typeof responseData["totalResults"] === "number" && startIndex + pageSize >= responseData["totalResults"]) {
@@ -17103,6 +17838,7 @@ async function searchNVD(terms, options) {
 init_retry_utils();
 init_circuit_breaker();
 init_metrics();
+init_http_body();
 var CISA_KEV_URL = "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json";
 var cisaCircuitBreaker = new CircuitBreaker({
   failureThreshold: 5,
@@ -17186,10 +17922,14 @@ async function searchCisaKev(terms = [], options) {
     }, options?.signal);
     let data;
     try {
-      data = await response.json();
-    } catch {
+      data = await readJsonCapped(response, MAX_BULK_JSON_BODY_BYTES);
+    } catch (err) {
+      if (err instanceof BodyTooLargeError) {
+        metrics.increment("cisa_kev_errors_total", 1, { error_type: "body_too_large" });
+        throw err;
+      }
       metrics.increment("cisa_kev_errors_total", 1, { error_type: "malformed_json" });
-      throw new Error("CISA KEV feed returned a malformed JSON response.");
+      throw new Error("CISA KEV feed returned a malformed JSON response.", { cause: err });
     }
     const cisaData = extractCisaKevItems(data);
     metrics.increment(cisaData.length > 0 ? "cisa_kev_cache_hits_total" : "cisa_kev_cache_misses_total", 1);
@@ -17312,6 +18052,7 @@ function normalizeEcosystem(value, target) {
 init_retry_utils();
 init_circuit_breaker();
 init_metrics();
+init_http_body();
 init_logger();
 
 // src/security/github-advisory-types.ts
@@ -17533,10 +18274,14 @@ async function searchGitHubAdvisories(terms, options) {
       }));
       let data;
       try {
-        data = await response.json();
-      } catch {
+        data = await readJsonCapped(response);
+      } catch (err) {
+        if (err instanceof BodyTooLargeError) {
+          metrics.increment("github_search_errors_total", 1, { error_type: "body_too_large" });
+          throw err;
+        }
         metrics.increment("github_search_errors_total", 1, { error_type: "malformed_json" });
-        throw new Error("GitHub API returned a malformed JSON response (repo advisories).");
+        throw new Error("GitHub API returned a malformed JSON response (repo advisories).", { cause: err });
       }
       let repoAdvisories = [];
       if (isGitHubAdvisoryArray(data)) {
@@ -17602,10 +18347,14 @@ async function searchGitHubAdvisories(terms, options) {
         }));
         let data;
         try {
-          data = await response.json();
-        } catch {
+          data = await readJsonCapped(response);
+        } catch (err) {
+          if (err instanceof BodyTooLargeError) {
+            metrics.increment("github_search_errors_total", 1, { error_type: "body_too_large", endpoint: endpointType });
+            throw err;
+          }
           metrics.increment("github_search_errors_total", 1, { error_type: "malformed_json", endpoint: endpointType });
-          throw new Error(`GitHub API returned a malformed JSON response for term "${term}".`);
+          throw new Error(`GitHub API returned a malformed JSON response for term "${term}".`, { cause: err });
         }
         let items = [];
         if (isGitHubAdvisoryArray(data)) {
@@ -17615,7 +18364,7 @@ async function searchGitHubAdvisories(terms, options) {
         } else if (isGitHubAdvisoryListResponse(data) && isArray(data.items)) {
           items = data.items.filter(isGitHubAdvisoryRaw);
         }
-        metrics.increment(items.length > 0 ? "github_cache_hits_total" : "github_cache_misses_total", 1, { term, endpoint: endpointType });
+        metrics.increment(items.length > 0 ? "github_cache_hits_total" : "github_cache_misses_total", 1, { endpoint: endpointType });
         return items.map(mapGitHubAdvisory);
       };
       const settled = await Promise.allSettled(terms.map(fetchTerm));
@@ -17686,6 +18435,7 @@ init_logger();
 init_constants();
 init_circuit_breaker();
 init_metrics();
+init_http_body();
 
 // src/security/cvss.ts
 var AV = { N: 0.85, A: 0.62, L: 0.55, P: 0.2 };
@@ -17957,10 +18707,14 @@ async function searchOSV(terms, options) {
       }
       let data;
       try {
-        data = await response.json();
-      } catch {
+        data = await readJsonCapped(response);
+      } catch (err) {
+        if (err instanceof BodyTooLargeError) {
+          metrics.increment("osv_search_errors_total", 1, { error_type: "body_too_large" });
+          throw err;
+        }
         metrics.increment("osv_search_errors_total", 1, { error_type: "malformed_json" });
-        throw new Error(`OSV returned a malformed JSON response for "${term}".`);
+        throw new Error(`OSV returned a malformed JSON response for "${term}".`, { cause: err });
       }
       let items;
       if (isOsvVulnerability(data)) {
@@ -17972,7 +18726,7 @@ async function searchOSV(terms, options) {
         return { vulns: [], skipped: false };
       }
       const endpoint = isIdLookup ? "vulns_by_id" : "query";
-      metrics.increment(items.length > 0 ? "osv_cache_hits_total" : "osv_cache_misses_total", 1, { term, endpoint });
+      metrics.increment(items.length > 0 ? "osv_cache_hits_total" : "osv_cache_misses_total", 1, { endpoint });
       const vulns = [];
       for (const item of items) {
         if (item.withdrawn) continue;
@@ -18565,6 +19319,7 @@ import { Value as Value8 } from "typebox/value";
 init_logger();
 init_circuit_breaker();
 init_metrics();
+init_http_body();
 var API_BASE = "https://api.stackexchange.com/2.3";
 var StackExchangeClient = class {
   _apiKey;
@@ -18629,8 +19384,9 @@ var StackExchangeClient = class {
         });
         let data;
         try {
-          data = await response.json();
+          data = await readJsonCapped(response);
         } catch (parseErr) {
+          if (parseErr instanceof BodyTooLargeError) throw parseErr;
           if (!response.ok) throw new Error(`HTTP ${response.status} from Stack Exchange API`, { cause: parseErr });
           throw parseErr;
         }
@@ -19404,6 +20160,7 @@ init_retry_utils();
 init_circuit_breaker();
 init_logger();
 init_metrics();
+init_http_body();
 
 // src/youtube/potoken.ts
 init_logger();
@@ -19636,7 +20393,7 @@ async function fetchOne(session, videoId, contentToken, lang, timeoutMs, signal,
             });
             throw new Error(`HTTP ${response.status} from timedtext endpoint`);
           }
-          const body = await response.text();
+          const body = await readTextCapped(response);
           const text = parseJson3(body);
           if (!text) {
             throw new Error("Empty transcript body (bot-protection rejected the token).");
@@ -21025,7 +21782,7 @@ ${prompt}`);
         modelRegistry: ctx.modelRegistry,
         systemPrompt: prompt,
         extensionCtx: ctx,
-        excludeTools: this.options.excludeTools || ["grep"],
+        excludeTools: resolveExcludedTools(this.options.excludeTools),
         config: this.config,
         getGlobalState: () => ({
           version: 1,
@@ -21354,6 +22111,9 @@ var DeepResearchOrchestrator = class {
             excludeTools: this.options.excludeTools,
             steeringMessages: steeringTexts
           });
+        } else if (this.currentRound >= maxRounds) {
+          logger.log(`[DeepOrchestrator] Round cap (${maxRounds}) reached \u2014 skipping the evaluator and going straight to final synthesis ${this.elapsed()}`);
+          break;
         } else {
           const synthesisService2 = await getService(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
           observer?.onEvaluationStart?.(this.currentRound);
@@ -21479,7 +22239,7 @@ var DeepResearchOrchestrator = class {
             options: {
               ...this.options,
               config: this.config,
-              excludeTools: this.options.excludeTools || ["grep"],
+              excludeTools: resolveExcludedTools(this.options.excludeTools),
               observer: this.observer
             },
             currentRound: this.currentRound,
@@ -21656,7 +22416,7 @@ var ResearchOrchestrationService = class {
     const { ctx, query, depth = 0, observer, onUpdate, sessionId, researchId, config, excludeTools } = options;
     const researchConfig = config || getConfig(ctx.cwd);
     const configDisabledTools = researchConfig.DISABLED_TOOLS ? researchConfig.DISABLED_TOOLS.split(",").map((s) => s.trim()).filter(Boolean) : [];
-    const mergedExcludeTools = configDisabledTools.length > 0 ? [.../* @__PURE__ */ new Set([...excludeTools ?? [], ...configDisabledTools])] : excludeTools;
+    const mergedExcludeTools = resolveExcludedTools(excludeTools, configDisabledTools);
     const selectedModel = await this.resolveResearchModel(options);
     logger.info(`[ResearchOrchestrationService] Using model: ${selectedModel.provider}/${selectedModel.id}`);
     const researchStart = Date.now();
@@ -22178,42 +22938,6 @@ init_service_registry();
 init_service_names();
 var NO_SOURCES_NOTE = "CITED LINKS\n_No web sources were successfully retrieved for this report \u2014 searches or page fetches may have been blocked (for example by site bot-protection) or returned no usable results. Treat the findings above as unverified._";
 var UNVERIFIED_LINKS_NOTE = "_None of the links above could be verified: no page fetch succeeded this session and no citation could be matched to retrieved content. They may be inaccurate or invented \u2014 check each one before relying on it._";
-var MAX_PLAUSIBLE_CITATION_MARKER = 200;
-function rewriteCitationMarkers(text, remap, isDangling) {
-  const inFence = fencedCodeMask(text);
-  return text.replace(/([ \t]*)\[(\d+)\]/g, (match, pad, digits, offset) => {
-    const n = parseInt(digits, 10);
-    const mapped = remap.get(n);
-    if (mapped !== void 0) return `${pad}[${mapped}]`;
-    if (n < 1 || n > MAX_PLAUSIBLE_CITATION_MARKER || !isDangling(n)) return match;
-    if (inFence(offset) || inInlineCodeSpan(text, offset)) return match;
-    const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
-    return text.slice(lineStart, offset).trim() === "" ? pad : "";
-  });
-}
-function fencedCodeMask(text) {
-  const ranges = [];
-  let open4 = -1;
-  let pos = 0;
-  for (const line of text.split("\n")) {
-    if (/^\s{0,3}(```|~~~)/.test(line)) {
-      if (open4 < 0) open4 = pos;
-      else {
-        ranges.push([open4, pos + line.length]);
-        open4 = -1;
-      }
-    }
-    pos += line.length + 1;
-  }
-  if (open4 >= 0) ranges.push([open4, text.length]);
-  return (offset) => ranges.some(([start, end]) => offset >= start && offset < end);
-}
-function inInlineCodeSpan(text, offset) {
-  const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
-  let ticks = 0;
-  for (let i = lineStart; i < offset; i++) if (text[i] === "`") ticks++;
-  return ticks % 2 === 1;
-}
 function redactUnverifiedProseUrls(text, trusted) {
   if (trusted.size === 0) return text;
   let removed = 0;
@@ -22257,6 +22981,23 @@ var ResearchSynthesisService = class _ResearchSynthesisService {
     this.sessions.set(sessionId, reports);
     return reports;
   }
+  /**
+   * Read a session's reports WITHOUT creating an entry for an unknown id.
+   *
+   * The read-only accessors below must not go through `getSessionReports`: that
+   * is create-on-read, so a query for an id we have never seen inserts an empty
+   * map — and at MAX_SESSIONS that insert evicts the current head. The LRU touch
+   * protects sessions that are read or written, but an in-flight run whose
+   * researchers are all still executing (reports stored early, nothing touched
+   * since) is exactly the stalest key, so a stray read for an unknown session
+   * could evict a live run's reports and silently shrink its final synthesis.
+   *
+   * Returns a shared empty map for unknown ids — callers here only read.
+   */
+  peekSessionReports(sessionId) {
+    return this.sessions.get(sessionId) ?? _ResearchSynthesisService.EMPTY_REPORTS;
+  }
+  static EMPTY_REPORTS = /* @__PURE__ */ new Map();
   /**
    * Store a researcher report
    * @param sessionId - Session identifier
@@ -22270,13 +23011,13 @@ var ResearchSynthesisService = class _ResearchSynthesisService {
    * Get a report by ID
    */
   getReport(sessionId, id) {
-    return this.getSessionReports(sessionId).get(id);
+    return this.peekSessionReports(sessionId).get(id);
   }
   /**
    * Get all reports
    */
   getAllReports(sessionId) {
-    return new Map(this.getSessionReports(sessionId));
+    return new Map(this.peekSessionReports(sessionId));
   }
   /**
    * Get reports for a specific round
@@ -22284,7 +23025,7 @@ var ResearchSynthesisService = class _ResearchSynthesisService {
   getReportsForRound(sessionId, round) {
     const roundReports = /* @__PURE__ */ new Map();
     const prefix = `${round}.`;
-    for (const [key, report] of this.getSessionReports(sessionId).entries()) {
+    for (const [key, report] of this.peekSessionReports(sessionId).entries()) {
       if (key.startsWith(prefix)) {
         roundReports.set(key, report);
       }
@@ -22295,13 +23036,13 @@ var ResearchSynthesisService = class _ResearchSynthesisService {
    * Get total number of reports
    */
   getReportCount(sessionId) {
-    return this.getSessionReports(sessionId).size;
+    return this.peekSessionReports(sessionId).size;
   }
   /**
    * Check if there are any reports
    */
   hasReports(sessionId) {
-    return this.getSessionReports(sessionId).size > 0;
+    return this.peekSessionReports(sessionId).size > 0;
   }
   /**
    * Clear reports for a session, or all reports if no sessionId provided
@@ -22320,7 +23061,7 @@ var ResearchSynthesisService = class _ResearchSynthesisService {
    * @returns Fallback synthesis string
    */
   buildFallbackSynthesis(sessionId, currentRound = 0) {
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
     const reportCount = reports.size;
     const roundInfo = currentRound > 0 ? ` (up to Round ${currentRound})` : "";
     let synthesis = `Research Findings${roundInfo}
@@ -22356,7 +23097,7 @@ Research performed using ${modelId}`;
    * @returns Synthesis with guaranteed and verified CITED LINKS section
    */
   ensureCitedLinks(sessionId, synthesis) {
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
     let globalCitations = reports.size > 0 ? normalizeCitations(reports).globalCitations : [];
     if (reports.size > 0) {
       const scraped = getScrapedLinks(sessionId);
@@ -22455,7 +23196,7 @@ ${guidanceSection}`;
   extractAllCitations(sessionId) {
     const seen = /* @__PURE__ */ new Set();
     const allCitations = [];
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
     for (const report of reports.values()) {
       const citations = parseCitations(report);
       for (const cit of citations) {
@@ -23117,10 +23858,10 @@ init_url_utils();
 // src/utils/research-export.ts
 init_logger();
 init_constants();
-import { promises as fs14 } from "node:fs";
+import { promises as fs15 } from "node:fs";
 import { homedir as homedir4, tmpdir as tmpdir4, platform as platform3 } from "node:os";
-import { join as join18, resolve as resolve3, normalize, sep as sep2 } from "node:path";
-import { randomBytes as randomBytes5 } from "node:crypto";
+import { join as join19, resolve as resolve3, normalize, sep as sep2 } from "node:path";
+import { randomBytes as randomBytes6 } from "node:crypto";
 var PREFERRED_SUBDIRS = [
   "research",
   "docs",
@@ -23183,16 +23924,16 @@ function isSafeToWriteDirectly(dir) {
 async function findPreferredSubdir(cwd) {
   let entries;
   try {
-    entries = await fs14.readdir(cwd);
+    entries = await fs15.readdir(cwd);
   } catch {
     return null;
   }
   for (const target of PREFERRED_SUBDIRS) {
     const match = entries.find((e) => e.toLowerCase() === target);
     if (match === void 0) continue;
-    const candidate = join18(cwd, match);
+    const candidate = join19(cwd, match);
     try {
-      const stat5 = await fs14.stat(candidate);
+      const stat5 = await fs15.stat(candidate);
       if (stat5.isDirectory()) return candidate;
     } catch {
     }
@@ -23215,7 +23956,7 @@ function sanitizeQuery2(query) {
   return query.toLowerCase().trim().slice(0, MAX_FILENAME_QUERY_LENGTH).replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function generateHash() {
-  return randomBytes5(3).toString("hex");
+  return randomBytes6(3).toString("hex");
 }
 async function exportResearchReport(query, result, _mode, cwd, explicitDir) {
   const sanitizedQuery = sanitizeQuery2(query);
@@ -23224,7 +23965,7 @@ async function exportResearchReport(query, result, _mode, cwd, explicitDir) {
   if (explicitDir && explicitDir.trim()) {
     targetDir = resolve3(explicitDir.trim());
     try {
-      await fs14.mkdir(targetDir, { recursive: true });
+      await fs15.mkdir(targetDir, { recursive: true });
     } catch (error) {
       logger.error(`[export] Could not create export dir "${targetDir}":`, error);
       return null;
@@ -23235,9 +23976,9 @@ async function exportResearchReport(query, result, _mode, cwd, explicitDir) {
   for (let attempt = 0; attempt < MAX_EXPORT_RETRIES; attempt++) {
     const hash = generateHash();
     const filename = `${baseFilename}-${hash}.md`;
-    const filepath = join18(targetDir, filename);
+    const filepath = join19(targetDir, filename);
     try {
-      await fs14.writeFile(filepath, result, { flag: "wx" });
+      await fs15.writeFile(filepath, result, { flag: "wx" });
       logger.log(`[export] Research report saved to: ${filepath}`);
       return filepath;
     } catch (error) {
@@ -23255,8 +23996,8 @@ function appendExportMessage(result, filepath, totalCost) {
 ---
 
 Research report saved to: ${filepath}`;
-  if (totalCost !== void 0 && totalCost > 0) {
-    const costStr = totalCost < 0.01 ? "<$0.01" : `$${totalCost.toFixed(4)}`.replace(/0+$/, "").replace(/\.$/, "");
+  if (totalCost !== void 0) {
+    const costStr = totalCost === 0 ? "$0.00" : totalCost < 0.01 ? "<$0.01" : `$${totalCost.toFixed(4)}`.replace(/0+$/, "").replace(/\.$/, "");
     footer += `
 Total cost: ${costStr}`;
   }
@@ -23270,7 +24011,7 @@ import { getAgentDir as getAgentDir2 } from "@earendil-works/pi-coding-agent";
 function readPkgVersion() {
   try {
     const pkgPath = fileURLToPath5(new URL("../package.json", import.meta.url));
-    const pkg = JSON.parse(fs16.readFileSync(pkgPath, "utf-8"));
+    const pkg = JSON.parse(fs17.readFileSync(pkgPath, "utf-8"));
     return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
   } catch {
     return "0.0.0";
@@ -23293,8 +24034,28 @@ var EXIT = {
    * again shortly" apart from "this run crashed" and back off instead of
    * re-running a broken command.
    */
-  TEMPFAIL: 75
+  TEMPFAIL: 75,
+  /**
+   * The run was CANCELLED via a programmatic abort (the caller's AbortSignal),
+   * with no OS signal involved. 130 — 128+SIGINT — is the conventional
+   * "interrupted" code and the natural default when there is no signal number to
+   * derive one from.
+   *
+   * A cancellation caused by an actual SIGNAL does NOT use this constant: see
+   * exitCodeForSignal below, which reports the true 128+N.
+   *
+   * Distinct from SOFTWARE for the same reason TEMPFAIL is: a deliberate stop is
+   * not a fault. Reported as SOFTWARE (70), a cancel matched the skill contract's
+   * "runtime error — suggest one retry for transient failures", so an agent
+   * relaying the result would offer to re-run the very research the user had just
+   * interrupted, and a --json consumer could not tell a cancel from a crash.
+   */
+  CANCELLED: 130
 };
+function exitCodeForSignal(sig) {
+  const signum = os7.constants.signals[sig];
+  return typeof signum === "number" ? 128 + signum : EXIT.CANCELLED;
+}
 function toStderr(s) {
   process.stderr.write(s);
 }
@@ -23339,10 +24100,16 @@ function makeProgressObserver() {
           toStderr(`  \u2022 evaluator: ${data?.action}
 `);
           break;
-        case "tokens_consumed":
-          if (data?.cost) toStderr(`  \u2022 tokens: ${data?.tokens ?? 0} ($${Number(data.cost).toFixed(4)})
+        case "tokens_consumed": {
+          const consumed = Number(data?.tokens ?? 0);
+          const costVal = typeof data?.cost === "number" ? data.cost : void 0;
+          if (consumed > 0 || costVal !== void 0) {
+            const costPart = costVal === void 0 ? "" : ` ($${costVal.toFixed(4)})`;
+            toStderr(`  \u2022 tokens: ${consumed}${costPart}
 `);
+          }
           break;
+        }
         case "complete":
           toStderr(`  \u2022 complete (${data?.result?.length ?? 0} chars)
 `);
@@ -23362,16 +24129,22 @@ function bridgeConfigEnv(explicitConfigPath) {
   const cliOverlayPath = getInterfaceEnvFilePath("cli");
   let loaded = false;
   const merged = {};
+  const fromExplicitBase = /* @__PURE__ */ new Set();
   for (const filePath of [basePath, cliOverlayPath]) {
     try {
-      if (!fs16.existsSync(filePath)) continue;
-      Object.assign(merged, parseDotEnv(fs16.readFileSync(filePath, "utf-8")));
+      if (!fs17.existsSync(filePath)) continue;
+      const parsed = parseDotEnv(fs17.readFileSync(filePath, "utf-8"));
+      Object.assign(merged, parsed);
+      for (const k of Object.keys(parsed)) {
+        if (explicitConfigPath !== void 0 && filePath === basePath) fromExplicitBase.add(k);
+        else fromExplicitBase.delete(k);
+      }
       loaded = true;
     } catch {
     }
   }
   for (const [k, v] of Object.entries(merged)) {
-    if (isProjectScopedKey(k)) continue;
+    if (isProjectScopedKey(k) && !fromExplicitBase.has(k)) continue;
     if (process.env[k] === void 0 && (k.startsWith("PI_RESEARCH_") || k === "STACKEXCHANGE_API_KEY" || k === "GITHUB_TOKEN" || k === "NVD_API_KEY")) {
       process.env[k] = v;
     }
@@ -23393,7 +24166,7 @@ function resolvedConfigPaths() {
 }
 function fileExists(p) {
   try {
-    return fs16.existsSync(p);
+    return fs17.existsSync(p);
   } catch {
     return false;
   }
@@ -23864,18 +24637,26 @@ async function reportError(err, what, json) {
   const lower = msg2.toLowerCase();
   const isTaggedResearchStop = err?.code === RESEARCH_STOPPED_ERROR_CODE;
   const isCapacity = err instanceof Error && err.name === "ResearchRunCapacityError";
-  const isConfigError = !isTaggedResearchStop && !isCapacity && (lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key"));
-  const isRateLimit = lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests");
-  const exitCode = isCapacity ? EXIT.TEMPFAIL : isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
+  const isCancellation = cancellationRequested || err instanceof Error && /^(aborted|research (aborted|cancelled))$/i.test(msg2);
+  const isConfigError = !isTaggedResearchStop && !isCapacity && !isCancellation && (lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key"));
+  const isRateLimit = !isCancellation && (lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests"));
+  const exitCode = isCancellation ? cancellationSignal ? exitCodeForSignal(cancellationSignal) : EXIT.CANCELLED : isCapacity ? EXIT.TEMPFAIL : isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
   if (json) {
     const payload = { ok: false, error: msg2, exitCode };
-    if (isCapacity || isRateLimit) payload["retryable"] = true;
+    if ((isCapacity || isRateLimit) && !isCancellation) payload["retryable"] = true;
+    if (isCancellation) payload["cancelled"] = true;
     if (process.env["PI_RESEARCH_DEBUG"] === "true" && err instanceof Error && err.stack) {
       payload["stack"] = err.stack;
     }
     toStdout(pretty(payload));
     return exitCode;
   }
+  if (isCancellation) {
+    toStderr(`
+pi-research ${what} cancelled.
+`);
+    return exitCode;
+  }
   if (isCapacity) {
     toStderr(`
 Error: pi-research ${what} did not start: ${msg2}
@@ -23982,10 +24763,14 @@ CONFIGURE
   Run \`${BINARY_NAME} status\` to see exactly what is detected.
 
 EXIT CODES
-  0  success
-  64 bad arguments
-  78 not configured \u2014 message prints the exact locations to fix
-  70 runtime error (network, provider, internal)
+  0   success
+  64  bad arguments
+  75  at capacity \u2014 every concurrent run slot is busy; nothing is broken, retry later
+  78  not configured \u2014 message prints the exact locations to fix
+      (on \`knowledge\`, also returned when the store is deliberately disabled)
+  130 cancelled \u2014 Ctrl-C; nothing failed, do not auto-retry
+      (other stop signals report POSIX 128+N: 143 SIGTERM, 129 SIGHUP, 131 SIGQUIT)
+  70  runtime error (network, provider, internal)
 `;
 }
 function parseArgs(argv) {
@@ -24180,19 +24965,35 @@ var flushAndExit = (code) => {
   });
 };
 var activeResearchAbortController = null;
+var cancellationRequested = false;
+var cancellationSignal = null;
+function _resetCancellationLatchForTests() {
+  cancellationRequested = false;
+  cancellationSignal = null;
+}
+function _markCancellationForTests(sig) {
+  cancellationRequested = true;
+  cancellationSignal = sig ?? null;
+}
 async function main(argv) {
   let _signalCleanupDone = false;
   const onSignal = (sig) => {
     if (_signalCleanupDone) return;
     _signalCleanupDone = true;
+    cancellationRequested = true;
+    cancellationSignal = sig;
     toStderr(`
 [pi-research] ${sig} \u2014 cleaning up\u2026
 `);
     activeResearchAbortController?.abort();
-    void safeShutdown().finally(() => flushAndExit(EXIT.SOFTWARE));
+    void safeShutdown().finally(() => flushAndExit(exitCodeForSignal(sig)));
   };
   process.once("SIGINT", () => onSignal("SIGINT"));
   process.once("SIGTERM", () => onSignal("SIGTERM"));
+  process.once("SIGHUP", () => onSignal("SIGHUP"));
+  if (process.platform === "win32") {
+    process.once("SIGBREAK", () => onSignal("SIGBREAK"));
+  }
   let parsed;
   try {
     parsed = parseArgs(argv);
@@ -24239,8 +25040,8 @@ ${buildHelp()}`);
 var _isMain = (() => {
   try {
     if (!process.argv[1]) return false;
-    const modulePath = fs16.realpathSync(path18.resolve(fileURLToPath5(import.meta.url)));
-    const invokedPath = fs16.realpathSync(path18.resolve(process.argv[1]));
+    const modulePath = fs17.realpathSync(path18.resolve(fileURLToPath5(import.meta.url)));
+    const invokedPath = fs17.realpathSync(path18.resolve(process.argv[1]));
     return modulePath === invokedPath;
   } catch {
     return false;
@@ -24257,7 +25058,10 @@ Error: fatal: ${err instanceof Error ? err.message : String(err)}
 export {
   EXIT,
   UsageError,
+  _markCancellationForTests,
+  _resetCancellationLatchForTests,
   bridgeConfigEnv,
+  exitCodeForSignal,
   parseArgs,
   reportError
 };