@lincoln504/pi-research 1.1.2 → 1.2.0

package/scripts/prepare.cjs

@@ -15,14 +15,24 @@
 
 'use strict';
 
-const { execSync } = require('child_process');
+const { spawnSync } = require('child_process');
 const path = require('path');
 
 const ROOT = path.join(__dirname, '..');
 
-try {
-  execSync('node scripts/build.cjs all', { stdio: 'inherit', cwd: ROOT });
-} catch (err) {
-  console.error('[prepare] Build failed:', err.message);
+// spawnSync with an argv array, not execSync with a quoted string: execSync goes
+// through /bin/sh -c, where $(…), backticks and quotes stay live INSIDE double
+// quotes — so a Node binary path under a directory named with shell metacharacters
+// would execute them during npm ci / a git install. Same fix setup.cjs and
+// cleanup.cjs already carry. process.execPath (not a bare 'node') for the same
+// reason as ensure-native-deps.cjs: a PATH lookup can resolve a different
+// interpreter (nvm-windows, Volta, a portable Node) than the one running npm.
+const r = spawnSync(process.execPath, ['scripts/build.cjs', 'all'], { stdio: 'inherit', cwd: ROOT });
+if (r.error) {
+  console.error('[prepare] Build failed:', r.error.message);
   process.exit(1);
 }
+if (r.status !== 0) {
+  console.error(`[prepare] Build failed with exit code ${r.status}`);
+  process.exit(r.status ?? 1);
+}

package/scripts/setup.cjs

@@ -11,7 +11,7 @@
  *   PLAYWRIGHT_INSTALL_DEPS=true        - also install Linux system deps (or pass --system-deps)
  */
 
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 const { existsSync, readdirSync, statSync } = require('fs');
 const { homedir } = require('os');
 const path = require('path');
@@ -95,18 +95,38 @@ if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') {
   if (!alreadyInstalled) {
     try {
       const bin = resolveCamoufoxBin();
-      const cmd = bin ? `"${bin}" fetch` : 'npx camoufox-js fetch';
+      // spawnSync with an ARGV ARRAY, never a shell string. `bin` is a filesystem
+      // path derived from the install directory, and execSync runs through
+      // `/bin/sh -c` where `$(…)`, backticks and quotes stay live INSIDE double
+      // quotes — so a package installed under a directory whose name contains
+      // shell metacharacters would execute them at install time. Windows still
+      // needs a shell to run the `.cmd` shim, and there the path is quoted; the
+      // runtime twin in ensure-browser.ts uses the same shape.
       // Bound the ~100MB download so a stalled/interrupted network fails fast
       // instead of hanging `npm install` forever (the catch below exits 0, and the
       // browser is re-fetchable manually). 15 min is ample even on slow links.
-      execSync(cmd, { stdio: 'inherit', env, timeout: 15 * 60 * 1000 });
+      const spawnOpts = { stdio: 'inherit', env, timeout: 15 * 60 * 1000 };
+      const res = bin
+        ? (isWindows
+            ? spawnSync(`"${bin}"`, ['fetch'], { ...spawnOpts, shell: true })
+            : spawnSync(bin, ['fetch'], spawnOpts))
+        : spawnSync('npx', ['camoufox-js', 'fetch'], { ...spawnOpts, shell: isWindows });
+      if (res.error) throw res.error;
+      if (res.status !== 0) throw new Error(`camoufox fetch exited with code ${res.status}`);
       browsersInstalled = true;
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
       console.error('ERROR: Camoufox browser install failed — pi-research will not work.');
       console.error('Run manually to fix: npx camoufox-js fetch');
       console.error(`Reason: ${msg}`);
-      process.exit(0);
+      // Exit 0 by default: the browser is fetched lazily on first use, so a restrictive
+      // network must not fail a user's install. But that also meant nothing here could
+      // ever turn CI red — a broken Windows launcher yielded a green `npm ci`. CI sets
+      // PI_RESEARCH_STRICT_SETUP=1 so the platform-specific spawn paths above are
+      // actually enforced somewhere.
+      const strict = process.env.PI_RESEARCH_STRICT_SETUP === '1' ||
+                     process.env.PI_RESEARCH_STRICT_SETUP === 'true';
+      process.exit(strict ? 1 : 0);
     }
   } else {
     browsersInstalled = true;

package/skills/pi-research/README.md

@@ -52,7 +52,13 @@ node "<skill_dir>/scripts/run.mjs" status  # verify detection
 Recommended. From the pi extension, run `/research-config` and choose
 Install in External Agents. It detects Claude, Codex, and OpenClaw and
 symlinks this skill into each one that is installed. Remove from External Agents
-removes those symlinks (cleanup also runs automatically on `npm uninstall`).
+removes those symlinks.
+
+Uninstalling the npm package does **not** remove them: npm 7 and newer do not run a
+package's own `preuninstall` script (verified against npm 11). Use Remove from
+External Agents first, or run `node scripts/cleanup.cjs` from the package directory,
+otherwise the symlinks, `~/.pi/research/state` and the `~/.cache/pi-research` model
+cache are all left behind.
 
 Cursor is not auto-installed — it has no global skills directory and only reads
 project-level `.cursor/skills/`. Symlink it per-project instead (see the table).
@@ -82,7 +88,8 @@ node "<skill_dir>/scripts/run.mjs" status
 ### Files
 
 - `SKILL.md` — the skill definition + system prompt (what agents read).
-- `scripts/run.mjs` — the launcher (compiled from `run.ts`).
+- `scripts/run.mjs` — the launcher (built from `run.ts`, which is a repo-only source
+  file and is not shipped in the npm package).
 - `references/configuration.md` — model/key setup and the full variable reference.
 
 ### License

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.1.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.2.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 
@@ -55,8 +55,10 @@ node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
 - **Cite the report's sources.** Carry its URLs/`[n]` references into your answer;
   attribute each non-trivial claim. Never present researched facts as unsourced;
   never invent or substitute sources.
-- **Surface the saved file.** If stderr/stdout ends with `Research report saved to: <path>`,
-  give the user that exact path. If absent, no file was written — say nothing about one.
+- **Surface the saved file.** Look for a saved-report line: stdout's report footer ends
+  with `Research report saved to: <path>`, and stderr carries `[pi-research] report saved
+  to: <path>`. Give the user that exact path. If neither appears, no file was written —
+  say nothing about one.
 
 ## Exit codes
 
@@ -66,6 +68,7 @@ node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
 | `78` on `knowledge` | Two cases — **read stderr to tell them apart.** | Says the store is **disabled**: silent; proceed to `research`. Mentions **credentials/model/API key**: this is the same hard config failure as `78` on `research` — **stop and relay full stderr**; don't silently continue, `research` will fail the same way. |
 | `78` on `research` | Engine missing or no model/key | **Stop. Relay full stderr** (it shows where to configure). Don't retry until fixed. |
 | `75` | Machine at capacity — other research runs are already using every slot | **Nothing is broken.** Wait for an in-flight run to finish, then retry this query once. Don't reconfigure anything and don't retry in a tight loop. |
+| `130` (and `129`/`131`/`143`) | Cancelled — the run was interrupted. These are the POSIX `128 + signal` codes: `130` Ctrl-C/SIGINT, `143` SIGTERM, `129` SIGHUP, `131` SIGQUIT. Treat **any exit ≥ 128 as a cancellation.** | **Nothing is broken and nothing failed.** Say the research was cancelled. **Do NOT re-run it** unless the user asks; they stopped it deliberately. |
 | `70` | Runtime error | Relay stderr; suggest one retry for transient failures (network, rate limit). |
 | `64` | Bad arguments | Fix args; don't surface unless the query itself is malformed. |
 

package/skills/pi-research/references/configuration.md

@@ -62,8 +62,12 @@ outranks both (the command says so when that happens).
 
 ### Exit codes
 
-`0` success · `64` bad arguments · `78` not configured (engine missing or no
-model/key; message lists the fix) · `70` runtime error (network/provider/internal).
+`0` success · `64` bad arguments · `70` runtime error (network/provider/internal) ·
+`75` machine at capacity — every concurrent-run slot is taken; wait and retry once ·
+`78` not configured (engine missing or no model/key; message lists the fix).
+
+A run stopped by a signal exits `128 + N`: `130` Ctrl-C (SIGINT), `143` SIGTERM,
+`129` SIGHUP, `131` SIGQUIT. See SKILL.md for the full table.
 
 ### Troubleshooting
 

package/skills/pi-research/scripts/run.mjs

@@ -3,13 +3,18 @@
 // skills/pi-research/scripts/run.ts
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, constants as osConstants } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 var PKG = "@lincoln504/pi-research";
 var REQUIRED_DEP = "@earendil-works/pi-coding-agent";
-var EXIT = { OK: 0, USAGE: 64, CONFIG: 78, SOFTWARE: 70 };
+var EXIT = { OK: 0, USAGE: 64, CONFIG: 78, SOFTWARE: 70, CANCELLED: 130 };
+var CANCELLING_SIGNALS = /* @__PURE__ */ new Set(["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"]);
+function exitCodeForSignal(sig) {
+  const signum = osConstants.signals[sig];
+  return typeof signum === "number" ? 128 + signum : EXIT.CANCELLED;
+}
 var argv = process.argv.slice(2);
 var subcommand = argv[0];
 if (!subcommand || subcommand === "-h" || subcommand === "--help" || subcommand === "help") {
@@ -199,6 +204,17 @@ Set PI_RESEARCH_BIN to the engine's node CLI (\u2026\\dist\\cli.mjs) or PI_RESEA
       ...useShell ? { shell: true } : {}
     }
   );
+  for (const sig of CANCELLING_SIGNALS) {
+    try {
+      process.on(sig, () => {
+        try {
+          child.kill(sig);
+        } catch {
+        }
+      });
+    } catch {
+    }
+  }
   child.on("error", (err) => {
     process.stderr.write(`
 Error: failed to launch pi-research (${engine2.label}): ${err.message}
@@ -207,6 +223,12 @@ Error: failed to launch pi-research (${engine2.label}): ${err.message}
   });
   child.on("exit", (code, signal) => {
     if (signal) {
+      if (CANCELLING_SIGNALS.has(signal)) {
+        process.stderr.write(`
+pi-research cancelled (${signal}).
+`);
+        process.exit(exitCodeForSignal(signal));
+      }
       process.stderr.write(`
 Error: pi-research killed by ${signal}
 `);

package/src/cli.ts

@@ -22,6 +22,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -84,8 +85,47 @@ export const EXIT = {
    * re-running a broken command.
    */
   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,
 } as const;
 
+/**
+ * Exit code for a run stopped by `sig`, following the POSIX 128+N convention that
+ * a shell uses when reporting a signal-terminated child (SIGINT → 130,
+ * SIGTERM → 143, SIGHUP → 129, SIGQUIT → 131).
+ *
+ * Why derive it per-signal instead of returning a single "cancelled" code: this
+ * process INSTALLS handlers for those signals, so it is never actually killed by
+ * them — it catches them and exits deliberately. If it exited a flat 130, the code
+ * a wrapper observes would depend on whether our handler won the race against a
+ * force-kill: handler wins → 130, handler loses → the shell's 143. Deriving 128+N
+ * makes the handler transparent, so the same user action reports the same number
+ * either way.
+ *
+ * Every value lands in 129..143, safely inside the 0-255 range a POSIX wait status
+ * preserves — nothing here can be truncated to a false 0. Windows does not
+ * implement the 128+N convention at all (its exit codes are 32-bit and carry no
+ * signal semantics), so there these are simply our documented contract values.
+ */
+export function exitCodeForSignal(sig: NodeJS.Signals): number {
+  const signum = (os.constants.signals as Record<string, number | undefined>)[sig];
+  return typeof signum === 'number' ? 128 + signum : EXIT.CANCELLED;
+}
+
 // ---------------------------------------------------------------------------
 // Output helpers
 // ---------------------------------------------------------------------------
@@ -190,20 +230,33 @@ export function bridgeConfigEnv(explicitConfigPath?: string): { path: string; lo
   // iteration and the "don't clobber the real environment" guard would then
   // block the overlay's value — cli.env could never override config.env.
   const merged: Record<string, string> = {};
+  // Keys whose winning value came from an EXPLICIT --config file (not the
+  // default base, not the cli.env overlay). Project-scoped keys are only
+  // bridged for these — see below.
+  const fromExplicitBase = new Set<string>();
   for (const filePath of [basePath, cliOverlayPath]) {
     try {
       if (!fs.existsSync(filePath)) continue;
-      Object.assign(merged, parseDotEnv(fs.readFileSync(filePath, 'utf-8')));
+      const parsed = parseDotEnv(fs.readFileSync(filePath, 'utf-8'));
+      Object.assign(merged, parsed);
+      for (const k of Object.keys(parsed)) {
+        if (explicitConfigPath !== undefined && filePath === basePath) fromExplicitBase.add(k);
+        else fromExplicitBase.delete(k);
+      }
       loaded = true;
     } catch {
       // ignore unreadable file; fall through to the next
     }
   }
   for (const [k, v] of Object.entries(merged)) {
-    // Skip per-directory (project-scoped) keys: promoting them into process.env would make
-    // config.env out-rank the per-directory registry, defeating a per-cwd override. They are
-    // still applied as a lower-precedence file layer by getConfig()/loadEnvFiles().
-    if (isProjectScopedKey(k)) continue;
+    // Skip per-directory (project-scoped) keys from the AMBIENT files: promoting them into
+    // process.env would make config.env out-rank the per-directory registry, defeating a
+    // per-cwd override. They are still applied as a lower-precedence file layer by
+    // getConfig()/loadEnvFiles(). An EXPLICIT --config file is different: getConfig never
+    // reads that path, so skipping its keys silently dropped them (a depth or
+    // knowledge-mode set in `--config ci.env` simply did not apply) — and a file the user
+    // named on this exact invocation outranking the per-directory registry is the intent.
+    if (isProjectScopedKey(k) && !fromExplicitBase.has(k)) continue;
     if (process.env[k] === undefined && (k.startsWith('PI_RESEARCH_') || k === 'STACKEXCHANGE_API_KEY' || k === 'GITHUB_TOKEN' || k === 'NVD_API_KEY')) {
       process.env[k] = v;
     }
@@ -863,9 +916,25 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
   // machine as a setup problem would send the user to reconfigure a working install.
   const isCapacity = err instanceof Error && err.name === 'ResearchRunCapacityError';
 
+  // Cancellation. Primary signal is the latch set by the SIGINT/SIGTERM handler —
+  // an exact fact, unlike the message, which varies by whichever subsystem noticed
+  // the abort first ('Aborted' from the search layer, 'Research aborted' /
+  // 'Research cancelled' from the orchestrator). The anchored message signatures
+  // only cover a programmatic abort where no signal arrived. Deliberately NOT
+  // matched: a bare `err.name === 'AbortError'` — internal timeout aborts
+  // (AbortSignal-driven retry/scrape deadlines) throw that name too, and an
+  // escaped one would report "cancelled — do not re-run" for a run nobody
+  // stopped. In the CLI every real cancellation sets the latch or carries these
+  // exact signatures. Checked before everything below: an abort can unwind
+  // through a provider call and surface wording that the config/rate-limit
+  // heuristics would otherwise claim.
+  const isCancellation =
+    cancellationRequested ||
+    (err instanceof Error && /^(aborted|research (aborted|cancelled))$/i.test(msg));
+
   // Auth / model / config-shaped errors → CONFIG exit + config block.
   const isConfigError =
-    !isTaggedResearchStop && !isCapacity && (
+    !isTaggedResearchStop && !isCapacity && !isCancellation && (
     lower.includes('no llm model available') ||
     lower.includes('not found in pi') ||
     lower.includes('no api key') ||
@@ -879,20 +948,27 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
   // "api key" in its body (e.g. "rate limit exceeded for this api key"), and
   // classifying that as a setup problem sends the user to reconfigure a
   // perfectly working key instead of waiting out the limit.
-  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 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;
 
   // --json: emit a structured error on stdout so a machine consumer never has to
   // special-case plain-text stderr. Mirrors the { ok: true, ... } success shape.
   if (json) {
     const payload: Record<string, unknown> = { ok: false, error: msg, exitCode };
     // Machine-readable "this will succeed later" flag, so a consumer can back off
-    // and retry without string-matching the human message.
-    if (isCapacity || isRateLimit) payload['retryable'] = true;
+    // and retry without string-matching the human message. Gated on cancellation:
+    // a Ctrl-C landing in the same window a queue-wait expires must never emit
+    // `cancelled: true` alongside `retryable: true` — a consumer honouring the
+    // latter would re-run the research the user just stopped.
+    if ((isCapacity || isRateLimit) && !isCancellation) payload['retryable'] = true;
+    // A cancel is emphatically NOT retryable-by-default: the user asked to stop.
+    if (isCancellation) payload['cancelled'] = true;
     if (process.env['PI_RESEARCH_DEBUG'] === 'true' && err instanceof Error && err.stack) {
       payload['stack'] = err.stack;
     }
@@ -900,6 +976,13 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
     return exitCode;
   }
 
+  // Cancellation is a completed intention, not a failure — never a stack trace,
+  // and never the word "failed".
+  if (isCancellation) {
+    toStderr(`\npi-research ${what} cancelled.\n`);
+    return exitCode;
+  }
+
   // Capacity exhaustion is a healthy-machine "busy" state — report it as such and
   // never with a stack trace, which would read as a crash for a routine condition.
   if (isCapacity) {
@@ -1024,12 +1107,14 @@ CONFIGURE
   Run \`${BINARY_NAME} status\` to see exactly what is detected.
 
 EXIT CODES
-  0  success
-  64 bad arguments
-  75 at capacity — every concurrent run slot is busy; nothing is broken, retry later
-  78 not configured — message prints the exact locations to fix
-     (on \`knowledge\`, also returned when the store is deliberately disabled)
-  70 runtime error (network, provider, internal)
+  0   success
+  64  bad arguments
+  75  at capacity — every concurrent run slot is busy; nothing is broken, retry later
+  78  not configured — message prints the exact locations to fix
+      (on \`knowledge\`, also returned when the store is deliberately disabled)
+  130 cancelled — 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)
 `;
 }
 
@@ -1269,6 +1354,32 @@ const flushAndExit = (code: number): void => {
 // outlives that one run.
 let activeResearchAbortController: AbortController | null = null;
 
+/**
+ * Set once SIGINT/SIGTERM has been handled. Read by reportError so a cancellation
+ * is classified by the fact that we were signalled, not by pattern-matching the
+ * message an aborted subsystem happened to throw.
+ */
+let cancellationRequested = false;
+
+/**
+ * WHICH signal fired — so a cancellation that unwinds through reportError
+ * reports the same 128+N the signal path itself would (SIGTERM → 143, not a
+ * flat 130). reportError races onSignal's own flushAndExit; latching the name
+ * makes both racers agree on the number, and keeps the `exitCode` field in
+ * `--json` from contradicting the actual exit status.
+ */
+let cancellationSignal: NodeJS.Signals | null = null;
+
+/** Test seams for the module-level cancellation latch (set only by onSignal). */
+export function _resetCancellationLatchForTests(): void {
+  cancellationRequested = false;
+  cancellationSignal = null;
+}
+export function _markCancellationForTests(sig?: NodeJS.Signals): void {
+  cancellationRequested = true;
+  cancellationSignal = sig ?? null;
+}
+
 async function main(argv: string[]): Promise<number> {
   // Register signal handlers so SIGINT/SIGTERM always trigger SDK shutdown
   // before the process exits. safeShutdown() is idempotent — safe to call
@@ -1277,6 +1388,8 @@ async function main(argv: string[]): Promise<number> {
   const onSignal = (sig: string) => {
     if (_signalCleanupDone) return;
     _signalCleanupDone = true;
+    cancellationRequested = true;
+    cancellationSignal = sig as NodeJS.Signals;
     toStderr(`\n[pi-research] ${sig} — cleaning up…\n`);
     // Abort the in-flight research run FIRST (synchronously ahead of the shutdown
     // teardown below) so the orchestrator's existing signal-aware cancellation path
@@ -1286,10 +1399,25 @@ async function main(argv: string[]): Promise<number> {
     // Fire-and-forget: we can't await here, but safeShutdown swallows errors
     // and the finally blocks in each command handler also call it. Drain via
     // flushAndExit (not a bare process.exit) so buffered stdout isn't truncated.
-    void safeShutdown().finally(() => flushAndExit(EXIT.SOFTWARE));
+    // 128+N, not a flat CANCELLED: see exitCodeForSignal. Because we handle these
+    // signals rather than dying from them, a fixed code would make the observed
+    // exit status depend on whether this handler beat a force-kill.
+    void safeShutdown().finally(() => flushAndExit(exitCodeForSignal(sig as NodeJS.Signals)));
   };
   process.once('SIGINT', () => onSignal('SIGINT'));
   process.once('SIGTERM', () => onSignal('SIGTERM'));
+  // SIGHUP (terminal closed) and, on Windows, SIGBREAK (Ctrl+Break). Without these
+  // the run dies without cancelling: no abort of the in-flight research, no browser
+  // or embedding-server teardown, and no 128+N exit code. On Windows it matters
+  // most — SIGTERM is never delivered there (process.kill maps to TerminateProcess),
+  // so Ctrl-C and Ctrl+Break are the only signals that reach this handler at all.
+  // The SDK already registers both (see _addSignalHandlers); the CLI did not, which
+  // left the SDK's handler to tear the container down underneath a live orchestrator
+  // — exactly the race the CLI installs its own handlers to avoid.
+  process.once('SIGHUP', () => onSignal('SIGHUP'));
+  if (process.platform === 'win32') {
+    process.once('SIGBREAK', () => onSignal('SIGBREAK'));
+  }
 
   let parsed: ParsedArgs;
   try {

package/src/config.ts

@@ -14,6 +14,7 @@ import { getConfigDirName } from './utils/host-config.ts';
 import { Type, type Static } from 'typebox';
 import { Value } from 'typebox/value';
 import { normalizeWorkspacePath } from './utils/text-utils.ts';
+import { replaceFileSync } from './utils/atomic-replace.ts';
 
 /**
  * Validates configuration schema using TypeBox.
@@ -501,7 +502,7 @@ export function describeKnowledgeStoreMode(
     let registryHasKey = false;
     try {
       const registry = loadProjectSettingsRegistry();
-      registryHasKey = registry[normalizeWorkspacePath(cwd)]?.[KEY] !== undefined;
+      registryHasKey = findRegistryEntry(registry, normalizeWorkspacePath(cwd))?.[KEY] !== undefined;
     } catch { /* unreadable registry → not the origin */ }
     if (registryHasKey) origin = 'this directory (project settings)';
     else if (iface && fileHasKey(getInterfaceEnvFilePath(iface))) origin = `${iface}.env overlay`;
@@ -546,12 +547,48 @@ export function parseDotEnv(content: string): Record<string, string> {
  * Load environment variables from global and local files.
  * Order: Global File < Interface overlay < Legacy .env < Centralized Registry (WINS)
  */
+/**
+ * Look up a directory's entry in the project-settings registry, tolerating case.
+ *
+ * On Windows and on macOS's default (case-insensitive) filesystem, `C:\\Users\\Bob\\Proj`
+ * and `c:\\users\\bob\\proj` are the SAME directory but different object keys, so a shell
+ * that reports a different casing than the one the settings were saved under made those
+ * settings silently vanish. normalizeWorkspacePath only resolves and strips a trailing
+ * separator; it does not fold case, and it must not start doing so — the key it produces
+ * is persisted, so folding it would orphan every entry already on disk.
+ *
+ * Resolving at READ time instead fixes the lookup without touching stored data: exact
+ * match first (the only path taken on Linux, and the fast path everywhere), then a
+ * case-insensitive scan as a fallback.
+ */
+function findRegistryKey(
+  registry: Record<string, Record<string, string>>,
+  normalizedCwd: string,
+): string | undefined {
+  if (registry[normalizedCwd] !== undefined) return normalizedCwd;
+  // Only case-insensitive filesystems can produce this mismatch; skip the scan elsewhere.
+  if (process.platform !== 'win32' && process.platform !== 'darwin') return undefined;
+  const lowered = normalizedCwd.toLowerCase();
+  for (const key of Object.keys(registry)) {
+    if (key.toLowerCase() === lowered) return key;
+  }
+  return undefined;
+}
+
+function findRegistryEntry(
+  registry: Record<string, Record<string, string>>,
+  normalizedCwd: string,
+): Record<string, string> | undefined {
+  const key = findRegistryKey(registry, normalizedCwd);
+  return key === undefined ? undefined : registry[key];
+}
+
 function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, string> {
   const merged: Record<string, string> = {};
   const globalPath = getGlobalEnvFilePath();
   const registry = loadProjectSettingsRegistry();
   const normalizedCwd = normalizeWorkspacePath(cwd);
-  const homeRegistry = registry[normalizeWorkspacePath(os.homedir())];
+  const homeRegistry = findRegistryEntry(registry, normalizeWorkspacePath(os.homedir()));
 
   // 1. ONE-TIME MIGRATION: Populate config.env from HOME registry if missing
   try {
@@ -613,15 +650,17 @@ function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, stri
         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...`);
         // Persist under the registry lock, reading the latest on-disk state so a concurrent
         // write isn't lost; also reflect the merge in the in-memory `registry` used just below.
-        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) {
@@ -633,8 +672,9 @@ function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, stri
   //    LOCAL_SCOPE_KEYS are applied (and may override), never user-scoped keys — those belong to
   //    config.env. Any non-local key present here is stale pollution (e.g. a pre-fix legacy
   //    migration) and is ignored rather than allowed to override the user's global settings.
-  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)) {
         // Don't interpolate values in warnings — a config key could carry a secret and
         // redactSecrets won't catch short/non-standard tokens. Key + winner is enough.
@@ -763,7 +803,11 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     // Read-merge-write under one lock so a concurrent local write to another directory
     // isn't lost (the merge onto the existing entry happens against the latest on-disk state).
     updateProjectSettingsRegistry((registry) => {
-      registry[normalizedCwd] = { ...(registry[normalizedCwd] ?? {}), ...newValues };
+      // Merge into the entry that already represents THIS directory, even if it was
+      // written with different casing on a case-insensitive filesystem. Writing a
+      // second key would leave the earlier settings stranded and unreachable.
+      const key = findRegistryKey(registry, normalizedCwd) ?? normalizedCwd;
+      registry[key] = { ...(registry[key] ?? {}), ...newValues };
     });
 
     logger.debug(`[config] Saved project settings for ${normalizedCwd} to central registry.`);
@@ -870,15 +914,12 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     const tmpPath = `${p}.tmp.${process.pid}.${Date.now()}`;
     fs.writeFileSync(tmpPath, outLines.join('\n'), { encoding: 'utf-8', mode: 0o600 });
     try {
-      fs.renameSync(tmpPath, p);
-    } catch (renameErr) {
-      if (process.platform === 'win32') {
-        fs.copyFileSync(tmpPath, p);
+      if (replaceFileSync(tmpPath, p) === 'copied') {
         try { fs.unlinkSync(tmpPath); } catch { /* best effort */ }
-      } else {
-        try { fs.unlinkSync(tmpPath); } catch { /* best effort */ }
-        throw renameErr;
       }
+    } catch (renameErr) {
+      try { fs.unlinkSync(tmpPath); } catch { /* best effort */ }
+      throw renameErr;
     }
     // Tighten regardless of how the file came to exist (fresh rename, Windows copy over
     // an existing file, or a pre-hardening 0644 file that the rename replaced-in-place).

package/src/constants.ts

@@ -177,3 +177,34 @@ export const RESEARCHER_LAUNCH_DELAY_MS = 1500;
 export const MAX_QUERIES_PER_RESEARCHER_LEVEL_1 = 10;
 export const MAX_QUERIES_PER_RESEARCHER_LEVEL_2 = 15;
 export const MAX_QUERIES_PER_RESEARCHER_LEVEL_3 = 20;
+
+/**
+ * Tools excluded from every researcher unless the caller says otherwise.
+ *
+ * `grep` is developer-only: during WEB research a high-capability model otherwise
+ * spends turns searching the local filesystem instead of the internet.
+ */
+export const DEFAULT_EXCLUDED_TOOLS: readonly string[] = ['grep'];
+
+/**
+ * Resolve the effective researcher exclusion list.
+ *
+ * An EMPTY array is "no preference", not "exclude nothing". The two front-ends
+ * express no-preference differently — the pi extension always builds an array
+ * (`[...new Set([...])]`, often empty) while the CLI omits the key entirely — so a
+ * plain truthiness test made the same user input mean opposite things: grep was
+ * available in the extension and excluded on the CLI, regardless of depth.
+ *
+ * `configDisabled` (PI_RESEARCH_DISABLED_TOOLS) is strictly ADDITIVE. Folding it in
+ * as a replacement meant disabling any unrelated tool silently ENABLED grep, so a
+ * subtract-only setting could grant a capability.
+ */
+export function resolveExcludedTools(
+  callerExclusions: readonly string[] | undefined,
+  configDisabled: readonly string[] = [],
+): string[] {
+  const base = callerExclusions && callerExclusions.length > 0
+    ? callerExclusions
+    : DEFAULT_EXCLUDED_TOOLS;
+  return [...new Set([...base, ...configDisabled])];
+}

package/src/core/interfaces/knowledge-interfaces.ts

@@ -120,7 +120,12 @@ export interface IKnowledgeStore extends IService {
   /** Extended operations */
   addDocuments(docs: StoreDocument[]): Promise<void>;
   deleteByUrl(url: string): Promise<void>;
-  deleteByUrlAndType(url: string, ingestionType: string): Promise<void>;
+  /**
+   * @param olderThan When set, only rows with `timestamp < olderThan` are removed —
+   *   lets a refresh insert its replacement first and prune the superseded rows
+   *   afterwards, so a failed insert can never leave the URL with nothing.
+   */
+  deleteByUrlAndType(url: string, ingestionType: string, olderThan?: number): Promise<void>;
   isStoreClosed?(): boolean;
 
   /**