@lincoln504/pi-research 1.1.2 → 1.3.0

package/scripts/cleanup.cjs

@@ -1,7 +1,22 @@
 #!/usr/bin/env node
 
-const { execSync } = require('child_process');
-const { rmSync, existsSync, lstatSync, readlinkSync, readFileSync, writeFileSync, unlinkSync } = require('fs');
+/**
+ * Uninstall-time cleanup: skill links, cache tree, state tree.
+ *
+ * IMPORTANT — this does NOT run on `npm uninstall`. npm removed the
+ * `preuninstall`/`postuninstall` lifecycle for the package being removed in
+ * npm 7; verified against npm 11, where `postinstall` fires on install but
+ * `preuninstall` never fires on uninstall. The `preuninstall` entry in
+ * package.json is retained for package managers that still honour it, but it
+ * must not be treated as the cleanup path.
+ *
+ * The supported paths are `pi-research skill uninstall` (removes the skill
+ * links via the same owned-only manifest logic) and running this script
+ * directly:  node <package-root>/scripts/cleanup.cjs
+ */
+
+const { spawnSync } = require('child_process');
+const { rmSync, existsSync, lstatSync, readdirSync, readlinkSync, readFileSync, writeFileSync, unlinkSync } = require('fs');
 const os = require('os');
 const path = require('path');
 
@@ -52,7 +67,7 @@ function removeInstalledSkills() {
     if (!owned) { kept.push(e); continue; }
     try {
       if (lstatSync(p).isSymbolicLink()) unlinkSync(p);
-      else rmSync(p, { recursive: true, force: true });
+      else rmSync(p, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
       console.log(`pi-research: removed skill install at ${p}`);
     } catch (err) {
       kept.push(e);
@@ -93,8 +108,17 @@ if (process.env.PI_RESEARCH_PURGE_BROWSERS === '1') {
   if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD !== '1') {
     try {
       const bin = resolveCamoufoxBin();
-      const cmd = bin ? `"${bin}" remove` : 'npx camoufox-js remove';
-      execSync(cmd, { stdio: 'inherit' });
+      // Argv array, not a shell string — see the matching note in setup.cjs: `bin`
+      // is derived from the install directory, and a shell string would let a
+      // directory name containing `$(…)` execute at uninstall time.
+      const isWin = process.platform === 'win32';
+      const res = bin
+        ? (isWin
+            ? spawnSync(`"${bin}"`, ['remove'], { stdio: 'inherit', shell: true })
+            : spawnSync(bin, ['remove'], { stdio: 'inherit' }))
+        : spawnSync('npx', ['camoufox-js', 'remove'], { stdio: 'inherit', shell: isWin });
+      if (res.error) throw res.error;
+      if (res.status !== 0) throw new Error(`camoufox remove exited with code ${res.status}`);
       console.log('pi-research: camoufox browser binaries removed.');
     } catch (error) {
       console.warn(`pi-research: could not remove camoufox binaries: ${error instanceof Error ? error.message : String(error)}`);
@@ -109,7 +133,7 @@ if (process.env.PI_RESEARCH_PURGE_BROWSERS === '1') {
 const legacyCacheDir = path.join(projectRoot, '.browser');
 if (existsSync(legacyCacheDir)) {
   try {
-    rmSync(legacyCacheDir, { recursive: true, force: true });
+    rmSync(legacyCacheDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
   } catch (error) {
     console.warn(`pi-research: could not remove ${legacyCacheDir}: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -126,7 +150,7 @@ if (existsSync(legacyCacheDir)) {
 function removeOwnedScratchDir(label, dir) {
   if (!dir || !existsSync(dir)) return;
   try {
-    rmSync(dir, { recursive: true, force: true });
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
     console.log(`pi-research: removed ${label} ${dir}`);
   } catch (error) {
     console.warn(`pi-research: could not remove ${label} ${dir}: ${error instanceof Error ? error.message : String(error)}`);
@@ -136,14 +160,92 @@ function removeOwnedScratchDir(label, dir) {
 // Cache tree: browser profiles, webgpu-viability probe, downloaded embedding models.
 // Same resolution as config.ts (XDG_CACHE_HOME || ~/.cache, then pi-research) on
 // every platform. Shared camoufox binaries live in ~/.cache/camoufox (handled above).
-const cacheHome = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+// A RELATIVE XDG_CACHE_HOME is ignored, exactly as embedder-utils.ts does at runtime.
+// Honouring one here would rmSync a cwd-relative `pi-research` tree — deleting whatever
+// happens to sit there — while leaving the real cache untouched. This script's whole job
+// is deletion, so it must not resolve paths more loosely than the code that created them.
+const xdgCache = process.env.XDG_CACHE_HOME;
+const cacheHome = xdgCache && path.isAbsolute(xdgCache) ? xdgCache : path.join(os.homedir(), '.cache');
 removeOwnedScratchDir('cache dir', path.join(cacheHome, 'pi-research'));
 
 // State tree: transient run state, locks, backups, project-settings. Now lives in
 // pi-research's own namespace (~/.pi/research/state), honoring the same overrides
-// as getGlobalConfigDir()/PI_RESEARCH_STATE_DIR.
-const stateDir = process.env.PI_RESEARCH_STATE_DIR
-  || path.join(os.homedir(), process.env.PI_RESEARCH_CONFIG_DIR_NAME || '.pi', 'research', 'state');
-removeOwnedScratchDir('state dir', stateDir);
+// as getGlobalConfigDir()/PI_RESEARCH_STATE_DIR — with the same strictness the
+// XDG guard above applies. A RELATIVE state dir would rmSync a tree relative to
+// wherever the user happens to invoke this script (generally NOT where the
+// runtime created state), and a config-dir name carrying a path separator could
+// traverse out of HOME entirely. Deletion must never resolve paths more loosely
+// than the code that created them.
+const stateOverride = process.env.PI_RESEARCH_STATE_DIR;
+const rawDirName = process.env.PI_RESEARCH_CONFIG_DIR_NAME;
+const dirName = rawDirName && !rawDirName.includes('/') && !rawDirName.includes('\\') && rawDirName !== '.' && rawDirName !== '..'
+  ? rawDirName
+  : '.pi';
+
+/**
+ * Is this path PROVABLY equivalent to the layout the runtime itself would have
+ * constructed by default (`<dirName>/research`)? Wholesale rm of a state-dir
+ * override is only safe when the answer is yes: PI_RESEARCH_STATE_DIR may point
+ * at a SHARED directory, and rm'ing the override itself (unlike the cache sweep,
+ * which is namespaced via join(cacheHome, 'pi-research')) deleted everything the
+ * user kept beside our state.
+ *
+ * Deliberately NOT a bare "does any segment literally say pi-research" check —
+ * that matches naming convention, not ownership. A user is entirely free to
+ * point the override at, say, `~/agents-state/pi-research/` while keeping other
+ * tools' notes alongside it in the same folder (a natural way to organize
+ * several tools' state by name); a substring match would treat that shared
+ * folder as exclusively ours and wholesale-delete it. Only the exact default
+ * layout is something WE constructed and can therefore prove is ours.
+ */
+function isPiResearchNamespaced(p) {
+  const segs = p.split(/[\\/]+/).filter(Boolean);
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (segs[i] === dirName && segs[i + 1] === 'research') return true;
+  }
+  return false;
+}
+
+/**
+ * Targeted state sweep for a non-namespaced override dir: delete ONLY the
+ * entries the runtime actually creates there and leave everything else — and
+ * the directory itself — untouched. The entry list mirrors the writers:
+ *   research-state.json + research-state-<hex>.tmp   (state-manager)
+ *   .locks/, backups/                                 (state-path-configuration)
+ *   project-settings.json + its .lock / .tmp. / .lock.stale- companions (config.ts)
+ *   research-run-slot-<i>.lock                        (research-run-semaphore)
+ * Best-effort; never throws.
+ */
+function removeOwnedStateEntries(dir) {
+  if (!dir || !existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  const owned = (name) =>
+    name === 'research-state.json' ||
+    (name.startsWith('research-state-') && name.endsWith('.tmp')) ||
+    name === '.locks' ||
+    name === 'backups' ||
+    name === 'project-settings.json' ||
+    name.startsWith('project-settings.json.') ||
+    /^research-run-slot-\d+\.lock$/.test(name);
+  for (const name of entries) {
+    if (!owned(name)) continue;
+    try {
+      rmSync(path.join(dir, name), { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+    } catch (error) {
+      console.warn(`pi-research: could not remove state entry ${path.join(dir, name)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  console.log(`pi-research: removed pi-research state entries from ${dir} (directory preserved — not a pi-research-namespaced path).`);
+}
+
+const stateDir = stateOverride && path.isAbsolute(stateOverride)
+  ? stateOverride
+  : path.join(os.homedir(), dirName, 'research', 'state');
+if (stateOverride && path.isAbsolute(stateOverride) && !isPiResearchNamespaced(stateDir)) {
+  removeOwnedStateEntries(stateDir);
+} else {
+  removeOwnedScratchDir('state dir', stateDir);
+}
 
 process.exit(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.3.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/cleanup/research-cleanup.ts

@@ -82,11 +82,19 @@ export function createCleanupFunction(
     const { resetLogger } = await import('../logger.ts');
     resetLogger(researchId);
     
-    // FIX (#10): Clear session circuit breaker to prevent unbounded map growth.
+    // FIX (#10): Clear the session's browser circuit breaker to prevent unbounded
+    // map growth. Breakers are keyed by the plain researchId — createResearchRunId()
+    // generates it (`run-<8 hex>`) independently of piSessionId in
+    // research-tool-definition.ts, and tools/scrape.ts / tools/search.ts thread that
+    // same bare researchId into getBrowserCircuitBreaker() as BrowserTask.sessionId.
+    // (The `${piSessionId}-<8 hex>` shape this comment used to assume is produced
+    // only by generateSessionId(), which has no production caller.) This duplicates
+    // the clearSessionCircuitBreaker(targetId) call research-orchestration-service.ts
+    // already makes in its own finally block on the normal run-completion path; it
+    // matters here on paths where this cleanup runs alone, e.g. a throw before
+    // orchestrator.run() is ever reached.
     const { clearSessionCircuitBreaker } = await import('../infrastructure/browser/browser-error-utils.ts');
-    if (piSessionId) {
-      clearSessionCircuitBreaker(piSessionId);
-    }
+    clearSessionCircuitBreaker(researchId);
     
     const activePanels = getPiActivePanels(piSessionId);
     if (activePanels.length === 0) {