@lincoln504/pi-research 1.7.4 → 1.7.6

package/README.md

@@ -19,11 +19,11 @@
   ·
   <a href="docs/ARCHITECTURE.md">Architecture</a>
   ·
-  <a href="docs/DOCUMENTATION-ES.md">ES</a>
+  <a href="https://github.com/Lincoln504/pi-research/blob/main/docs/DOCUMENTATION-ES.md">ES</a>
   ·
-  <a href="docs/DOCUMENTATION-ZH.md">中文研究</a>
+  <a href="https://github.com/Lincoln504/pi-research/blob/main/docs/DOCUMENTATION-ZH.md">中文研究</a>
   ·
-  <a href="docs/DOCUMENTATION-JA.md">日本語研究</a>
+  <a href="https://github.com/Lincoln504/pi-research/blob/main/docs/DOCUMENTATION-JA.md">日本語研究</a>
 </p>
 
 ---
@@ -49,7 +49,7 @@ npm install -g @lincoln504/pi-research
 pi-research skill install
 ```
 
-No extra setup is needed. The package ships ready-made bindings for every platform and runs no install scripts. The stealth browser (1GB+ installed) downloads on first use, so the first scrape takes a few minutes. npm ≥11.19 skips install scripts by default. Leave it that way: nothing needs approving or building. Only Windows with npm older than 11.19 can fail when the install tries to compile from source. Upgrading npm fixes it.
+No extra setup is needed. The package ships ready-made bindings for every platform and declares no build step, so there is nothing to approve or compile. The stealth browser (1GB+ installed) is fetched by the `postinstall` script when npm runs install scripts, which it does by default up to npm 11.18 — that is the bundled npm on the Node 22.22.2 floor this package requires, so expect the fetch during install. Newer npm (11.19+) skips install scripts by default, and the browser is then fetched lazily on the first scrape instead. Either way the first scrape takes a few minutes until it is in place. Set `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` to defer the fetch deliberately. Only Windows with npm older than 11.19 can fail when the install tries to compile from source. Upgrading npm fixes it.
 
 The `@earendil-works/pi-*` host packages are **peer dependencies**. pi supplies its own copies when it loads this as an extension, and npm ≥7 installs them automatically for a standalone (global or project) install. An install that skips peers does not get them: `npm install --legacy-peer-deps`, yarn classic, and `pi install` itself (it passes that flag on purpose) are all in that group. The standalone engine and the agent-skill launcher then stop with a message naming the missing package; add it with:
 
@@ -63,7 +63,7 @@ In pi, the extension works out of the box on the session's model and pi's config
 
 ### Uninstall
 
-`pi remove npm:@lincoln504/pi-research` removes the extension. `npm uninstall -g @lincoln504/pi-research` removes the standalone engine. npm 7+ no longer runs `preuninstall`, so nothing else is removed on its own: skill links into other agents (Claude Code, Codex, …), the state directory (`~/.pi/research/state`), and the cache (`~/.cache/pi-research`, including any downloaded embedding models) stay in place. Remove the skill links first with `pi-research skill uninstall` (or `/research-config` → Remove from External Agents). The shared stealth-browser cache (`~/.cache/camoufox`) is preserved unless `PI_RESEARCH_PURGE_BROWSERS=1`. See [AGENT-SKILL.md](docs/AGENT-SKILL.md#installation-flow) for the full picture.
+`pi remove npm:@lincoln504/pi-research` removes the extension. `npm uninstall -g @lincoln504/pi-research` removes the standalone engine. npm 7+ no longer runs `preuninstall`, so nothing else is removed on its own: skill links into other agents (Claude Code, Codex, …), the state directory (`~/.pi/research/state`), and the cache (`~/.cache/pi-research`, including any downloaded embedding models) stay in place. Remove the skill links first with `pi-research skill uninstall` (or `/research-config` → Remove from External Agents), then remove the rest with `pi-research cleanup`: The shared stealth-browser cache (`~/.cache/camoufox`) is preserved unless `PI_RESEARCH_PURGE_BROWSERS=1`. See [AGENT-SKILL.md](docs/AGENT-SKILL.md#installation-flow) for the full picture.
 
 ### How it works
 

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

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

package/dist/cli-bin.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * The installed `pi-research` bin.
+ *
+ * WHY THIS SHIM EXISTS INSTEAD OF POINTING `bin` STRAIGHT AT dist/cli.mjs
+ *
+ * dist/cli.mjs statically imports the `@earendil-works/pi-*` host packages, which
+ * are declared as PEER dependencies: pi supplies its own copies when it loads
+ * this package as an extension, and npm >= 7 resolves them automatically for a
+ * standalone (global or project) install. An install that skips peers leaves
+ * them absent — `npm install --legacy-peer-deps`, yarn classic, and a pnpm
+ * config with `auto-install-peers=false` all do that — and Node then dies at
+ * module load with a raw `ERR_MODULE_NOT_FOUND` stack before any of our code
+ * runs. The user sees an internal Node error instead of the one-line fix.
+ *
+ * The preflight cannot live inside the bundle: esbuild hoists the bundle's
+ * external `import` declarations to the very top of the output file, ahead of
+ * every statement in the program, so anything the bundle body does runs AFTER
+ * the failing import has already thrown. (Verified: a wrapper entry point whose
+ * first statement is the preflight still crashes, because the emitted file
+ * begins with `import "…/pi-ai";`.) It has to be a separate module, which is
+ * why this file is shipped unbundled and why `bin` points at it.
+ *
+ * The check uses `import.meta.resolve()`, NOT `createRequire().resolve()`: both
+ * host packages are ESM-only (`exports` maps with no `require` condition), so
+ * the CJS resolver fails on them with `ERR_PACKAGE_PATH_NOT_EXPORTED` even when
+ * they are correctly installed — a false negative that would break every
+ * healthy install. `import.meta.resolve()` uses the same ESM resolution the
+ * bundle itself uses, returns when the package is present, and throws
+ * `ERR_MODULE_NOT_FOUND` when it is not.
+ *
+ * Exit code 78 (EXIT.CONFIG) and the remedy text match the agent-skill
+ * launcher's `depMissing()` — one failure, one message, whichever entry point
+ * the user reached for.
+ */
+
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
+
+/**
+ * Probe one peer dependency.
+ *
+ *   'ok'      — resolves, and the file it resolves to exists
+ *   'missing' — does not resolve at all (the --legacy-peer-deps case)
+ *   'broken'  — resolves (its package.json and exports map are readable) but the
+ *               file those point at is not on disk
+ *
+ * The 'broken' case is checked with existsSync rather than by importing the
+ * module. Resolving is not loading: an interrupted install, a pruned
+ * node_modules or a bad package-cache restore leaves a package that resolves
+ * perfectly and then fails to load, which would pass this preflight and die
+ * inside cli.mjs with the same raw ERR_MODULE_NOT_FOUND this shim exists to
+ * replace. Importing it here instead would work, but it runs the host
+ * package's module side effects before the CLI proper has decided to start, so
+ * the cheap existence check is the right trade.
+ *
+ * @returns {'ok' | 'missing' | 'broken'}
+ */
+function probePeer(name) {
+  let resolved;
+  try {
+    resolved = import.meta.resolve(name);
+  } catch {
+    return 'missing';
+  }
+  try {
+    return existsSync(fileURLToPath(resolved)) ? 'ok' : 'broken';
+  } catch {
+    // Resolved to something fileURLToPath cannot turn into a path (not a file:
+    // URL). It resolved, so treat it as present rather than inventing a failure.
+    return 'ok';
+  }
+}
+
+const status = new Map(REQUIRED_PEERS.map((name) => [name, probePeer(name)]));
+const missing = REQUIRED_PEERS.filter((name) => status.get(name) === 'missing');
+const broken = REQUIRED_PEERS.filter((name) => status.get(name) === 'broken');
+
+if (missing.length > 0 || broken.length > 0) {
+  // The remedy names the packages that are ACTUALLY absent. It used to hardcode
+  // `npm install -g @earendil-works/pi-coding-agent` with the comment "add just
+  // the missing host package", which was wrong whenever pi-ai was the missing
+  // one: the instruction named a package the user already had, and following it
+  // changed nothing. Reported by review 2026-10-01.
+  const needsInstall = [...missing, ...broken];
+  const lines = [
+    '',
+    'Error: pi-research cannot start — it is missing required runtime dependencies:',
+    ...missing.map((name) => `    ${name}`),
+    ...broken.map((name) => `    ${name}  (installed, but its files are incomplete)`),
+    '',
+    'These are PEER dependencies. pi provides its own copies when it loads this',
+    'package as an extension, and npm >= 7 installs them automatically for a',
+    'standalone (global or project) install. This install skipped them, which is',
+    'what --legacy-peer-deps, yarn classic, and a pnpm config with',
+    'auto-install-peers=false do.',
+    '',
+    'Install the missing package(s), or reinstall this package, which resolves',
+    'them as peers:',
+    '',
+    `    npm install -g ${needsInstall.join(' ')}`,
+    '    npm install -g @lincoln504/pi-research',
+    '',
+  ];
+  process.stderr.write(lines.join('\n'));
+  process.exit(78);
+}
+
+// dist/cli.mjs decides whether to run by comparing its own module URL against
+// process.argv[1]. Because this shim is what the OS (or npm's Windows .cmd shim)
+// actually invokes, argv[1] is THIS file; without the rewrite below that check
+// would be false and the CLI would exit 0 having done nothing at all. Point it
+// at the real entry point before importing it, so both sides resolve to the
+// same realpath.
+//
+// fileURLToPath, not URL.pathname: on Windows the latter yields
+// `/C:/…/cli.mjs`, which is not a path any filesystem call accepts.
+process.argv[1] = fileURLToPath(new URL('./cli.mjs', import.meta.url));
+
+await import('./cli.mjs');

package/dist/cli.mjs

@@ -11122,6 +11122,7 @@ var init_skill_installer = __esm({
 import * as fs17 from "node:fs";
 import * as os7 from "node:os";
 import * as path19 from "node:path";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
 
 // src/core/service-initialization.ts
@@ -27790,6 +27791,30 @@ change the machine-wide defaults: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> an
     return reportError(err, "knowledge-config", kc.json);
   }
 }
+function cmdCleanup(c) {
+  const script = fileURLToPath6(new URL("../scripts/cleanup.cjs", import.meta.url));
+  if (!fs17.existsSync(script)) {
+    toStderr(
+      `
+Error: cleanup script not found at ${script}.
+Run it from the installed package instead: node <package-dir>/scripts/cleanup.cjs
+`
+    );
+    return EXIT.CONFIG;
+  }
+  const env = { ...process.env };
+  if (c.purgeBrowsers) {
+    env["PI_RESEARCH_PURGE_BROWSERS"] = "1";
+  }
+  const res = spawnSync(process.execPath, [script], { stdio: "inherit", env });
+  if (res.error) {
+    toStderr(`
+Error: could not run ${script}: ${res.error.message}
+`);
+    return EXIT.SOFTWARE;
+  }
+  return res.status ?? EXIT.SOFTWARE;
+}
 async function cmdSkill(s) {
   const {
     installSkill: installSkill2,
@@ -28043,6 +28068,12 @@ COMMANDS
   skill uninstall                Remove the skill from agents where pi-research installed it.
     --dry-run | --json           Plan only; JSON output.
 
+  cleanup                        Remove what npm uninstall leaves behind: the skill links, the
+                                 state tree (<config dir>/research/state) and the cache, including
+                                 downloaded embedding models. Keeps config.env and the knowledge
+                                 store database. --purge-browsers also deletes the shared
+                                 stealth-browser cache (~/.cache/camoufox) other tools use.
+
   help, --help, -h               Show this help.
   --version, -v                  Print the pi-research version.
 
@@ -28199,6 +28230,17 @@ function parseArgs(argv) {
     }
     throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global> | set retrieval <vector|bm25>.`);
   }
+  if (cmd === "cleanup") {
+    let purgeBrowsers = false;
+    for (const a of rest) {
+      if (a === "--purge-browsers") purgeBrowsers = true;
+      else if (a?.startsWith("--")) throw new UsageError(`unknown option for cleanup: ${a}`);
+      else throw new UsageError(`unexpected argument "${a}" after "cleanup".`);
+    }
+    out.command = "cleanup";
+    out.cleanup = { purgeBrowsers };
+    return out;
+  }
   if (cmd === "skill") {
     let json = false;
     let dryRun = false;
@@ -28412,6 +28454,8 @@ Error: ${err.message}
       return cmdKnowledgeConfig(parsed.knowledgeConfig);
     case "skill":
       return cmdSkill(parsed.skill);
+    case "cleanup":
+      return cmdCleanup(parsed.cleanup);
     case "research":
       return cmdResearch(parsed.research);
     default:

package/docs/AGENT-SKILL.md

@@ -110,7 +110,10 @@ Install in External Agents. The installer:
 > @lincoln504/pi-research` leaves the skill links, the state directory
 > (`~/.pi/research/state`) and the cache directory (`~/.cache/pi-research`,
 > including downloaded embedding models) in place. Run `pi-research skill uninstall`
-> **before** removing the package to take the links with you.
+> **before** removing the package to take the links with you. Then run
+> `pi-research cleanup` to remove the state tree and the cache (it keeps `config.env`
+> and the knowledge store database); add `--purge-browsers` to delete the shared
+> `~/.cache/camoufox` cache as well.
 
 Standalone (no pi extension). `pi-research skill install` and `pi-research skill uninstall`
 do exactly the same from the CLI — same agent detection, same manifest, same

package/docs/ARCHITECTURE.md

@@ -428,7 +428,7 @@ to support testing (mock replacement) and enforce init → use → dispose lifec
 Pure ESM — the codebase is ES Modules (`"type": "module"`). Worker bundles are built with
 esbuild (`npm run build:worker`) before integration tests or publishing.
 
-Enforced boundaries — `docs/deps.svg` is regenerated on every push (madge), and
+Enforced boundaries — [`docs/deps.svg`](https://github.com/Lincoln504/pi-research/blob/main/docs/deps.svg) is regenerated on every push (madge), and
 architectural rules are enforced by dependency-cruiser
 (`config/tooling/dependency-cruiser.cjs`).
 

package/docs/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.6] - 2026-10-01
+
+### Fixed
+
+- **The missing-peer remedy names the package that is actually missing.** The 1.7.5 shim's bullet list correctly enumerated every absent `@earendil-works/pi-*` package, but the command underneath it was hardcoded to `npm install -g @earendil-works/pi-coding-agent` with the comment "add just the missing host package". When `pi-ai` (and not `pi-coding-agent`) was the absent one, the instruction named a package the user already had and following it changed nothing. The remedy is now built from the detected set, so both peers are named when both are missing and only the absent one is named otherwise. Caught in review; pinned by a test that asserts the present package is never the one the remedy suggests installing.
+- **The bin preflight detects an install whose files are incomplete, not just an absent package.** It resolved each peer and treated a successful resolve as healthy. Resolving is not loading: an interrupted install, a pruned `node_modules` or a bad package-cache restore leaves `package.json` and its `exports` map intact with the file they point at gone, so the preflight passed it through and the bundle died on that import with the raw `ERR_MODULE_NOT_FOUND` the shim exists to replace. The preflight now also checks that the resolved file exists and reports `installed, but its files are incomplete` with the same exit 78. Checked with `existsSync` rather than by importing the module, which would run the host packages' side effects before the CLI has decided to start. Verified by reverting each half in isolation: without the `argv[1]` rewrite the stub engine exits 97, with a resolve-only preflight a deliberately truncated peer produces `ERR_MODULE_NOT_FOUND`, and the fixed shim produces exit 78.
+- **`dist/cli-bin.mjs` ships executable.** It was published at mode 644 against 755 for `dist/cli.mjs`, because the build copies it with `copyFileSync`, which preserves the committed source mode. Every package manager chmods the declared `bin` target itself, so no install was broken, but the shipped artifact should not depend on that. The build now chmods 755 and the source is committed executable.
+
+## [1.7.5] - 2026-10-01
+
+### Added
+
+- **`pi-research cleanup` removes what `npm uninstall` leaves behind.** npm 7 dropped `preuninstall`, so uninstalling removes the package directory and nothing else: skill links in other agents, the state tree and the cache (downloaded embedding models included) all stay on disk. The deletion logic already existed in `scripts/cleanup.cjs` (shipped in the tarball, wired to the `preuninstall` and `cleanup` npm scripts), but reaching it meant knowing where your package manager put the package. The new subcommand delegates to that script rather than reimplementing it, so there is one deletion implementation and one set of ownership guards, prints `--purge-browsers` to also delete the shared `~/.cache/camoufox` cache, and exits with the script's status. Verified end to end against a redirected HOME: state and cache removed, `config.env` and `knowledge_db/` preserved, second run idempotent. Alongside it the uninstall story is now documented as commands rather than only as a list of what stays: README, `docs/AGENT-SKILL.md`, `docs/CONFIGURATION.md` (which also gained the three leftover rows it was missing: the embedding model cache, the camoufox cache, the skills manifest, and the debug log that nothing removes) and the ES/JA/ZH docs.
+
+### Fixed
+
+- **A silently dropped optional `@huggingface/transformers` subtree no longer fails the type-check gate, and both the release and CI type-check jobs now repair it.** `npm ci` (npm/cli#4828, the same bug the lancedb binding self-heal exists for) can drop the ENTIRE optional embedding tree without printing any `npm warn optional` line: the v1.7.4 release run installed 592 packages from the same lockfile that had installed 606 minutes earlier in CI, and its `npm run type-check` then failed with six `TS2307: Cannot find module '@huggingface/transformers'` errors, because `src/` imports that package's declarations unconditionally. Re-running the identical job installed 606 and passed, then published. The runtime tolerates the absence by design (the knowledge store disables cleanly, which is why the package is optional), but the type-check gate does not, so the failure was a delivery flake rather than a code defect. `scripts/ensure-native-deps.cjs` now reads the pin from `optionalDependencies` (one source of truth), verifies it resolves, and when it does not installs that exact version by name, which is not subject to the optional-dependency resolution bug. The repair uses `--no-save --no-package-lock` so package.json and the tracked lockfile stay untouched, emits a GitHub warning annotation so it is visible in the run summary, and exits non-zero if the repair does not take. Verified against a scratch tree with the subtree deleted: the package is restored at the pinned version, both manifest hashes are unchanged, and `npm run type-check` then passes. The CI type-check job now runs the self-heal too (it was exposed to the same flake and had no repair step), the lancedb install in the same script gained `--no-package-lock` for the same reason, and `test/unit/scripts/ensure-native-deps.test.ts` covers the pin lookup, the resolve check and the platform-package selection.
+- **The `pi-research` bin reports a missing peer dependency instead of dying with a raw module error.** The CLI statically imports the `@earendil-works/pi-*` host packages, which are peer dependencies, so an install that skips peers (`npm install --legacy-peer-deps`, yarn classic, pnpm with `auto-install-peers=false`) left `pi-research` printing an internal `ERR_MODULE_NOT_FOUND` stack trace from inside Node. `bin` now points at a small unbundled shim (`src/cli-bin.mjs` → `dist/cli-bin.mjs`) that preflights both packages and exits 78 with the same remedy text and code the agent-skill launcher already prints, then loads the bundle. It cannot live inside the bundle: esbuild hoists the bundle's external imports to the top of the emitted file, ahead of every statement, so a wrapper entry point still crashed (verified). Two traps are pinned by tests: the check must use `import.meta.resolve()`, because `createRequire().resolve()` reports `ERR_PACKAGE_PATH_NOT_EXPORTED` for these ESM-only packages even when they are installed correctly, and the shim must rewrite `process.argv[1]` to the bundle path, because `cli.ts` runs `main()` only when argv[1] resolves to its own module file (otherwise the CLI exits 0 having done nothing). `scripts/verify-package.cjs` now also asserts that every `bin` target is shipped, so a shim dropped from `files[]` fails the publish gate instead of installing a command that does not exist.
+- **The postinstall no longer starts a browser fetch it cannot finish, and `--system-deps` no longer installs an unpinned package.** `scripts/setup.cjs` used `npx playwright install-deps`, but `playwright` is not a dependency of this package (`playwright-core` is), so that resolved a different, unpinned package from the registry at install time; it now invokes the installed `playwright-core` CLI, which ships the same subcommand. When `CAMOUFOX_INSTALL_DIR` / `PLAYWRIGHT_BROWSERS_PATH` points at a path that exists but is not a usable directory (a plain file, no permission, a broken mount), the script used to log the error and then download the full 663MB browser anyway before failing; it now reports and skips the fetch, and the summary no longer claims the browser is "ready" when the path could not be read. Both paths still exit 0, because a failed install is worse than a browser fetched later.
+- **Install claims and links that did not match reality are corrected.** The README said the package "runs no install scripts" and that the browser "downloads on first use". It declares three lifecycle scripts, and on npm up to 11.18 (the bundled npm on the Node 22.22.2 floor this package requires) the `postinstall` fetches that 663MB browser during install; only npm 11.19+ skips install scripts and defers the fetch to first use. The README, `docs/AGENT-SKILL.md` and the ES/JA/ZH docs now say which happens when, and how to defer it deliberately. The README's three translation links and `docs/ARCHITECTURE.md`'s `deps.svg` reference pointed at files that are not in the published tarball (the translations and the 660KB diagram are deliberately unshipped), so they are absolute repository URLs now and resolve from an installed package as well as from the npm page. `scripts/setup.cjs`'s header no longer claims it can never exit 1, which stopped being true when `PI_RESEARCH_STRICT_SETUP` (used by CI) was added.
+
 ## [1.7.4] - 2026-09-30
 
 ### Changed

package/docs/CONFIGURATION.md

@@ -363,7 +363,20 @@ All pi-research state lives under its own namespace, `~/.pi/research/`:
 | `~/.pi/research/state/` | Active sessions, browser status, locks. |
 | `~/.pi/research/knowledge_db/` | The knowledge store (LanceDB), unless `PI_RESEARCH_KNOWLEDGE_DIR` is set. |
 | `~/.cache/pi-research/profiles/` | Transient browser profiles, unless `PI_RESEARCH_TMP_DIR` is set. Rooted at `$XDG_CACHE_HOME` when that is set. |
+| `~/.cache/pi-research/models/` | Downloaded embedding models (the `@huggingface/transformers` backend). Re-downloaded on demand if removed. Rooted at `$XDG_CACHE_HOME` when that is set. |
 | `~/.cache/pi-research/webgpu-viability.json` | Cached WebGPU-viability verdict (see the knowledge store doc). Rooted at `$XDG_CACHE_HOME` when that is set. |
+| `~/.cache/camoufox/` | The stealth browser itself (1GB+). Shared with any other camoufox user on the machine, so it is never removed by default. |
+| `~/.pi/research/installed-skills.json` | Manifest of the skill links/copies `pi-research skill install` created, so `skill uninstall` removes exactly those. |
+| `$TMPDIR/pi-research.log` | Debug log, kept while `PI_RESEARCH_DEBUG=true`. Rotates at 10MB and keeps 10 archives. `PI_RESEARCH_LOG_PATH` relocates it. |
 
 Paths can be relocated with `PI_RESEARCH_STATE_DIR`, `PI_RESEARCH_KNOWLEDGE_DIR`,
 and `PI_RESEARCH_TMP_DIR`.
+
+### What uninstalling leaves behind
+
+`npm uninstall` removes the package directory and nothing else: npm 7 removed the
+`preuninstall` lifecycle, so the script declared in `package.json` never runs.
+`pi-research skill uninstall` removes the skill links, and `pi-research cleanup`
+removes the state tree and the cache (embedding models included) while keeping
+`config.env` and `knowledge_db/`. Add `--purge-browsers` to also delete the shared
+`~/.cache/camoufox` cache. The debug log is not removed by either.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "bin": {
-    "pi-research": "./dist/cli.mjs"
+    "pi-research": "./dist/cli-bin.mjs"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -16,6 +16,7 @@
   },
   "files": [
     "src/",
+    "dist/cli-bin.mjs",
     "dist/cli.mjs",
     "dist/thread-worker.mjs",
     "dist/pdf-extract-worker.mjs",

package/scripts/build.cjs

@@ -49,6 +49,24 @@ function copyWebGpuProbe() {
   );
 }
 
+// The `pi-research` bin shim (src/cli-bin.mjs), copied unbundled next to the
+// bundle it loads. It MUST NOT be bundled into dist/cli.mjs: its whole job is to
+// run BEFORE that bundle's external peer-dependency imports are evaluated, and
+// esbuild hoists those to the top of the emitted file. See the shim's own header
+// for the full story and for why `bin` points here instead of at dist/cli.mjs.
+function copyCliBin() {
+  fs.mkdirSync(p('dist'), { recursive: true });
+  fs.copyFileSync(p('src', 'cli-bin.mjs'), p('dist', 'cli-bin.mjs'));
+  // copyFileSync preserves the SOURCE mode. The source is committed executable
+  // (100755) so this is belt-and-braces, but nothing about the shipped bin should
+  // depend on the source file's mode or on the umask of whatever builds it. The
+  // bin is what the OS executes, so ship it executable like dist/cli.mjs: every
+  // package manager does its own chmod on the declared bin target, but nothing
+  // should depend on that. (Flagged in review 2026-10-01: the packed 1.7.5 tarball
+  // had dist/cli.mjs at 755 and dist/cli-bin.mjs at 644.)
+  fs.chmodSync(p('dist', 'cli-bin.mjs'), 0o755);
+}
+
 // Build the browser worker bundle. Factored out so the cli target can guarantee
 // it exists when built in isolation (`build:cli`), not only via `build all`.
 function buildWorker() {
@@ -146,6 +164,7 @@ const TARGETS = {
     copyThreadWorker();
     copyPdfWorker();
     copyWebGpuProbe();
+    copyCliBin();
     copyPrompts();
   },
   skill: () => {

package/scripts/setup.cjs

@@ -3,7 +3,13 @@
 /**
  * pi-research postinstall setup.
  * Installs Camoufox browser binaries.
- * Never exits with code 1 — that would break npm install.
+ *
+ * Exits 0 on EVERY failure path, because a non-zero exit from postinstall makes
+ * `npm install` fail and leaves the user without the package at all — the
+ * browser is re-fetchable on first use, a failed install is not. The single
+ * exception is PI_RESEARCH_STRICT_SETUP (set by this repo's CI), which restates
+ * the failure as exit 1 so an install regression fails the build loudly instead
+ * of hiding behind the graceful path.
  *
  * Environment:
  *   PLAYWRIGHT_BROWSERS_PATH            - override browser install location
@@ -82,6 +88,10 @@ function camoufoxCachePath() {
 }
 
 let browsersInstalled = false;
+// Set when a fetch cannot possibly succeed (an unusable configured install dir),
+// so the download is skipped rather than run to completion and then fail. Kept
+// separate from browsersInstalled so the summary below still tells the truth.
+let fetchSkipped = false;
 
 if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') {
   console.log('pi-research: skipping browser download (PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1)');
@@ -98,7 +108,15 @@ if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') {
   const installDeps = process.argv.includes('--system-deps') || process.env.PLAYWRIGHT_INSTALL_DEPS === 'true';
   if (installDeps && isLinux) {
     try {
-      execSync('npx playwright install-deps', { stdio: 'inherit', env: { ...env, PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '0' } });
+      // Use the installed playwright-core CLI, NOT `npx playwright`: `playwright`
+      // is not a dependency of this package (only `playwright-core` is), so
+      // `npx playwright` resolved a DIFFERENT, unpinned package from the registry
+      // at install time — an extra network fetch, an extra supply-chain surface,
+      // and a version that can disagree with the browser we drive. playwright-core
+      // ships the same `install-deps` subcommand (verified: its CLI lists it).
+      const playwrightCoreBin = path.join(projectRoot, 'node_modules', '.bin', isWindows ? 'playwright-core.cmd' : 'playwright-core');
+      const cli = existsSync(playwrightCoreBin) ? playwrightCoreBin : 'playwright-core';
+      execSync(`"${cli}" install-deps`, { stdio: 'inherit', env: { ...env, PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '0' } });
     } catch (e) {
       console.warn(`WARNING: could not install system dependencies. Run: sudo apt-get install -y libgbm1 libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libxcomposite1\nReason: ${e instanceof Error ? e.message : String(e)}\n(These are the libraries headless camoufox needs. Xvfb is NOT required for the default headless mode — only add it if you opt into virtual-display mode with PI_RESEARCH_USE_XVFB=true.)`);
     }
@@ -114,11 +132,23 @@ if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') {
         console.log(`pi-research: Camoufox already installed at ${cachePath}. Skipping fetch.`);
       }
     } catch (e) {
-      console.warn(`pi-research: error checking camoufox path ${cachePath}: ${e instanceof Error ? e.message : String(e)}`);
+      // A configured install dir that exists but cannot be READ as a directory
+      // (a plain file, a broken symlink mount, no permission) makes the fetch
+      // below impossible: camoufox downloads the whole ~663MB archive and then
+      // fails to place it. Report and skip instead, which is what the user's
+      // install needs either way (the catch further down exits 0, and the
+      // browser is re-fetchable once the path is usable).
+      console.warn(`pi-research: cannot use the browser install directory ${cachePath}: ${e instanceof Error ? e.message : String(e)}`);
+      if (customCamoufoxDir()) {
+        console.warn('pi-research: skipping the browser fetch because CAMOUFOX_INSTALL_DIR / PLAYWRIGHT_BROWSERS_PATH points at a path that is not a usable directory. Fix or unset it, then run: npx camoufox-js fetch');
+        fetchSkipped = true;
+      }
     }
   }
 
-  if (!alreadyInstalled) {
+  if (fetchSkipped) {
+    // Reported above; the fetch cannot work until the configured path is fixed.
+  } else if (!alreadyInstalled) {
     try {
       const bin = resolveCamoufoxBin();
       // spawnSync with an ARGV ARRAY, never a shell string. `bin` is a filesystem
@@ -169,7 +199,11 @@ if (existsSync(cachePath)) {
     const versions = readdirSync(cachePath).filter(f => statSync(path.join(cachePath, f)).isDirectory());
     console.log(`pi-research: camoufox ready (${versions.join(', ') || 'installed'})`);
   } catch (e) {
-    console.log(`pi-research: camoufox ready (path check error: ${e instanceof Error ? e.message : String(e)})`);
+    // Not "ready": the path exists but cannot be read as an install dir (a plain
+    // file, no permission, a broken mount). Claiming readiness here is how a
+    // broken CAMOUFOX_INSTALL_DIR turned into a mysterious "browser missing at
+    // runtime" much later. The fetch path above already printed the remedy.
+    console.warn(`pi-research: camoufox install path ${cachePath} could not be verified: ${e instanceof Error ? e.message : String(e)}`);
   }
 } else if (browsersInstalled) {
   console.warn(`pi-research: camoufox binary not found at expected path ${cachePath}`);

package/src/cli-bin.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * The installed `pi-research` bin.
+ *
+ * WHY THIS SHIM EXISTS INSTEAD OF POINTING `bin` STRAIGHT AT dist/cli.mjs
+ *
+ * dist/cli.mjs statically imports the `@earendil-works/pi-*` host packages, which
+ * are declared as PEER dependencies: pi supplies its own copies when it loads
+ * this package as an extension, and npm >= 7 resolves them automatically for a
+ * standalone (global or project) install. An install that skips peers leaves
+ * them absent — `npm install --legacy-peer-deps`, yarn classic, and a pnpm
+ * config with `auto-install-peers=false` all do that — and Node then dies at
+ * module load with a raw `ERR_MODULE_NOT_FOUND` stack before any of our code
+ * runs. The user sees an internal Node error instead of the one-line fix.
+ *
+ * The preflight cannot live inside the bundle: esbuild hoists the bundle's
+ * external `import` declarations to the very top of the output file, ahead of
+ * every statement in the program, so anything the bundle body does runs AFTER
+ * the failing import has already thrown. (Verified: a wrapper entry point whose
+ * first statement is the preflight still crashes, because the emitted file
+ * begins with `import "…/pi-ai";`.) It has to be a separate module, which is
+ * why this file is shipped unbundled and why `bin` points at it.
+ *
+ * The check uses `import.meta.resolve()`, NOT `createRequire().resolve()`: both
+ * host packages are ESM-only (`exports` maps with no `require` condition), so
+ * the CJS resolver fails on them with `ERR_PACKAGE_PATH_NOT_EXPORTED` even when
+ * they are correctly installed — a false negative that would break every
+ * healthy install. `import.meta.resolve()` uses the same ESM resolution the
+ * bundle itself uses, returns when the package is present, and throws
+ * `ERR_MODULE_NOT_FOUND` when it is not.
+ *
+ * Exit code 78 (EXIT.CONFIG) and the remedy text match the agent-skill
+ * launcher's `depMissing()` — one failure, one message, whichever entry point
+ * the user reached for.
+ */
+
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
+
+/**
+ * Probe one peer dependency.
+ *
+ *   'ok'      — resolves, and the file it resolves to exists
+ *   'missing' — does not resolve at all (the --legacy-peer-deps case)
+ *   'broken'  — resolves (its package.json and exports map are readable) but the
+ *               file those point at is not on disk
+ *
+ * The 'broken' case is checked with existsSync rather than by importing the
+ * module. Resolving is not loading: an interrupted install, a pruned
+ * node_modules or a bad package-cache restore leaves a package that resolves
+ * perfectly and then fails to load, which would pass this preflight and die
+ * inside cli.mjs with the same raw ERR_MODULE_NOT_FOUND this shim exists to
+ * replace. Importing it here instead would work, but it runs the host
+ * package's module side effects before the CLI proper has decided to start, so
+ * the cheap existence check is the right trade.
+ *
+ * @returns {'ok' | 'missing' | 'broken'}
+ */
+function probePeer(name) {
+  let resolved;
+  try {
+    resolved = import.meta.resolve(name);
+  } catch {
+    return 'missing';
+  }
+  try {
+    return existsSync(fileURLToPath(resolved)) ? 'ok' : 'broken';
+  } catch {
+    // Resolved to something fileURLToPath cannot turn into a path (not a file:
+    // URL). It resolved, so treat it as present rather than inventing a failure.
+    return 'ok';
+  }
+}
+
+const status = new Map(REQUIRED_PEERS.map((name) => [name, probePeer(name)]));
+const missing = REQUIRED_PEERS.filter((name) => status.get(name) === 'missing');
+const broken = REQUIRED_PEERS.filter((name) => status.get(name) === 'broken');
+
+if (missing.length > 0 || broken.length > 0) {
+  // The remedy names the packages that are ACTUALLY absent. It used to hardcode
+  // `npm install -g @earendil-works/pi-coding-agent` with the comment "add just
+  // the missing host package", which was wrong whenever pi-ai was the missing
+  // one: the instruction named a package the user already had, and following it
+  // changed nothing. Reported by review 2026-10-01.
+  const needsInstall = [...missing, ...broken];
+  const lines = [
+    '',
+    'Error: pi-research cannot start — it is missing required runtime dependencies:',
+    ...missing.map((name) => `    ${name}`),
+    ...broken.map((name) => `    ${name}  (installed, but its files are incomplete)`),
+    '',
+    'These are PEER dependencies. pi provides its own copies when it loads this',
+    'package as an extension, and npm >= 7 installs them automatically for a',
+    'standalone (global or project) install. This install skipped them, which is',
+    'what --legacy-peer-deps, yarn classic, and a pnpm config with',
+    'auto-install-peers=false do.',
+    '',
+    'Install the missing package(s), or reinstall this package, which resolves',
+    'them as peers:',
+    '',
+    `    npm install -g ${needsInstall.join(' ')}`,
+    '    npm install -g @lincoln504/pi-research',
+    '',
+  ];
+  process.stderr.write(lines.join('\n'));
+  process.exit(78);
+}
+
+// dist/cli.mjs decides whether to run by comparing its own module URL against
+// process.argv[1]. Because this shim is what the OS (or npm's Windows .cmd shim)
+// actually invokes, argv[1] is THIS file; without the rewrite below that check
+// would be false and the CLI would exit 0 having done nothing at all. Point it
+// at the real entry point before importing it, so both sides resolve to the
+// same realpath.
+//
+// fileURLToPath, not URL.pathname: on Windows the latter yields
+// `/C:/…/cli.mjs`, which is not a path any filesystem call accepts.
+process.argv[1] = fileURLToPath(new URL('./cli.mjs', import.meta.url));
+
+await import('./cli.mjs');

package/src/cli.ts

@@ -25,6 +25,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 // pi-research internals (bundled; native/npm deps stay external).
@@ -989,6 +990,55 @@ export async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeCo
  * clobbered, and every link/copy is manifest-tracked so uninstall removes exactly
  * what was created.
  */
+/**
+ * `pi-research cleanup` — the supported way to remove what `npm uninstall`
+ * leaves behind.
+ *
+ * npm removed `preuninstall` in npm 7, so an uninstall removes the package
+ * directory and nothing else: skill links in other agents, the state tree and
+ * the cache (downloaded embedding models included) all stay on disk. The
+ * deletion logic already exists in `scripts/cleanup.cjs`, which ships in the
+ * tarball and is wired to the `preuninstall` and `cleanup` npm scripts — but
+ * reaching it means knowing where your package manager put the package.
+ *
+ * Delegates to that script rather than reimplementing it, deliberately: one
+ * deletion implementation, one set of ownership guards (it removes only what it
+ * can prove it created, and refuses to touch the shared camoufox cache unless
+ * asked). spawnSync with an argv array and process.execPath, never a shell
+ * string, so a package installed under a path containing shell metacharacters
+ * cannot execute anything.
+ *
+ * Resolves the script relative to THIS module: `src/cli.ts` and the bundled
+ * `dist/cli.mjs` are each one level below the package root, so `../scripts/`
+ * is correct for a source checkout, a local install and a global install alike.
+ */
+function cmdCleanup(c: NonNullable<ParsedArgs['cleanup']>): number {
+  const script = fileURLToPath(new URL('../scripts/cleanup.cjs', import.meta.url));
+  if (!fs.existsSync(script)) {
+    toStderr(
+      `\nError: cleanup script not found at ${script}.\n` +
+        'Run it from the installed package instead: node <package-dir>/scripts/cleanup.cjs\n',
+    );
+    return EXIT.CONFIG;
+  }
+
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  if (c.purgeBrowsers) {
+    // Shared with every other camoufox user on the box, which is why it is not
+    // the default. The script prints what it is about to delete.
+    env['PI_RESEARCH_PURGE_BROWSERS'] = '1';
+  }
+
+  // stdio: 'inherit' — the script narrates each removal, and that narration is
+  // the user's only confirmation of what was deleted.
+  const res = spawnSync(process.execPath, [script], { stdio: 'inherit', env });
+  if (res.error) {
+    toStderr(`\nError: could not run ${script}: ${res.error.message}\n`);
+    return EXIT.SOFTWARE;
+  }
+  return res.status ?? EXIT.SOFTWARE;
+}
+
 async function cmdSkill(s: NonNullable<ParsedArgs['skill']>): Promise<number> {
   const {
     installSkill, uninstallSkill, skillInstallCandidates, skillUninstallCandidates,
@@ -1268,6 +1318,7 @@ interface ParsedArgs {
   knowledgeConfig?: { action: 'show' | 'set' | 'set-retrieval'; mode?: 'none' | 'project' | 'global'; retrieval?: 'vector' | 'bm25'; json?: boolean };
   status?: { json?: boolean };
   skill?: { action: 'install' | 'uninstall' | 'status'; json?: boolean; dryRun?: boolean; copy?: boolean };
+  cleanup?: { purgeBrowsers?: boolean };
   configPath?: string;
   json?: boolean;
 }
@@ -1316,6 +1367,12 @@ COMMANDS
   skill uninstall                Remove the skill from agents where pi-research installed it.
     --dry-run | --json           Plan only; JSON output.
 
+  cleanup                        Remove what npm uninstall leaves behind: the skill links, the
+                                 state tree (<config dir>/research/state) and the cache, including
+                                 downloaded embedding models. Keeps config.env and the knowledge
+                                 store database. --purge-browsers also deletes the shared
+                                 stealth-browser cache (~/.cache/camoufox) other tools use.
+
   help, --help, -h               Show this help.
   --version, -v                  Print the pi-research version.
 
@@ -1492,6 +1549,22 @@ export function parseArgs(argv: string[]): ParsedArgs {
     throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global> | set retrieval <vector|bm25>.`);
   }
 
+  if (cmd === 'cleanup') {
+    // Wrapper for the shipped scripts/cleanup.cjs. npm 7+ never runs
+    // `preuninstall`, so an uninstall leaves the state tree, the cache and any
+    // skill links in other agents behind; this is the documented way to remove
+    // them without locating the script inside node_modules or a global prefix.
+    let purgeBrowsers = false;
+    for (const a of rest) {
+      if (a === '--purge-browsers') purgeBrowsers = true;
+      else if (a?.startsWith('--')) throw new UsageError(`unknown option for cleanup: ${a}`);
+      else throw new UsageError(`unexpected argument "${a}" after "cleanup".`);
+    }
+    out.command = 'cleanup';
+    out.cleanup = { purgeBrowsers };
+    return out;
+  }
+
   if (cmd === 'skill') {
     let json = false;
     let dryRun = false;
@@ -1847,6 +1920,8 @@ async function main(argv: string[]): Promise<number> {
       return cmdKnowledgeConfig(parsed.knowledgeConfig!);
     case 'skill':
       return cmdSkill(parsed.skill!);
+    case 'cleanup':
+      return cmdCleanup(parsed.cleanup!);
     case 'research':
       return cmdResearch(parsed.research!);
     default: