@lincoln504/pi-research 1.7.3 → 1.7.5

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.3", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.7.5", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli-bin.mjs

@@ -0,0 +1,83 @@
+#!/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 { fileURLToPath } from 'node:url';
+
+const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
+
+const missing = REQUIRED_PEERS.filter((name) => {
+  try {
+    import.meta.resolve(name);
+    return false;
+  } catch {
+    return true;
+  }
+});
+
+if (missing.length > 0) {
+  const lines = [
+    '',
+    'Error: pi-research cannot start — it is missing required runtime dependencies:',
+    ...missing.map((name) => `    ${name}`),
+    '',
+    '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.',
+    '',
+    'Either of these fixes it:',
+    '',
+    '    npm install -g @earendil-works/pi-coding-agent   # add just the missing host package',
+    '    npm install -g @lincoln504/pi-research           # or reinstall, resolving peers',
+    '',
+  ];
+  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

@@ -384,16 +384,35 @@ validates with. Bump it in lockstep with the pi host, not independently. (`undic
 contrast, tracks the host's major — the host is on undici 8, and pi-research only uses the
 stable `Agent` connector API, so it follows `^8`.)
 
-Pinned embedding runtime — `@huggingface/transformers` is exact at `4.2.0`. Tried `4.3.0`
-on 2026-10-01 and did not take it: it moves the native stack with it (onnxruntime-node
-`1.24.3` → `1.30.0`, onnxruntime-web `1.26.0-dev.20260416` → `1.31.0-dev.20260914`) and
-reshapes the tree (`roarr`, `boolean` and `detect-node` leave `global-agent`'s subtree). The
-knowledge-store unit suite (26 files, 322 tests) and the integration suites
-(`knowledge-stack`, `knowledge-models`, `research-knowledge-search`; 33 tests, 25 run, 8
-skipped) pass on both versions, so those suites do not decide it — they mock the backend or
-run against an already-cached model, and neither exercises a real model download and backend
-selection. Bump it only with a live embedding check (model load, CPU and WebGPU backends) on
-the new ONNX Runtime.
+Pinned embedding runtime — `@huggingface/transformers` is exact at `4.3.0`. The hold at `4.2.0`
+was lifted on 2026-10-01 for a security reason, not a feature one: `4.2.0` declares
+`sharp ^0.34.5` and pins `onnxruntime-node 1.24.3`, whose `adm-zip ^0.5.16` resolves to the
+advisory-ridden `0.5.18`, and neither range can be lifted downstream (npm ignores a published
+dependency's `overrides`, so the repository's own `sharp`/`adm-zip` overrides reach only the
+tree rooted here). `4.3.0` ships `sharp ^0.35.4` and `onnxruntime-node 1.30.0`
+(`adm-zip ^0.6.0`), which clears both advisory groups for consumers as well. It also moves the
+native stack with it (onnxruntime-web `1.26.0-dev.20260416` → `1.31.0-dev.20260914`, left
+overridden at the stable `1.24.3` as before) and reshapes the tree (`global-agent` 3.0.0 →
+4.1.3, dropping seven packages from its old subtree: `roarr`, `boolean`, `detect-node`, `es6-error`,
+`json-stringify-safe`, `semver-compare`, `sprintf-js`).
+
+The unit suite (26 knowledge files, 322 tests) and the integration suites (`knowledge-stack`,
+`knowledge-models`, `knowledge-migrations`, `research-knowledge-search`; 44 tests, 36 run, 8
+skipped) pass on both versions, so those suites do NOT decide a bump — they mock the backend or
+run against an already-cached model, and neither exercises real model load and backend
+selection. What decided this one was a live embedding check against the real backend, run on
+both release candidates with `onnx-community/granite-embedding-small-english-r2-ONNX`:
+
+dimension 384 on both backends; CPU `initialize` 536 ms (4.2.0) vs 524 ms (4.3.0) and
+`embedMany` of 3 texts 48 ms vs 39 ms; WebGPU (Dawn/Vulkan) `initialize` 1003 ms vs 1409 ms and
+`embedMany` 110 ms vs 71 ms; cosine between the two related sentences 0.90431857 (4.2.0 CPU) vs
+0.90431858 (4.3.0 CPU) against 0.70265303 vs 0.70265297 for the unrelated one; embedding the
+same text twice returns cosine 1.0; and a full store round-trip (two documents written through
+the real embedder, then a hybrid vector + FTS + RRF `search` on both devices) returns the
+expected top hit. The shipped `dist/webgpu-probe.mjs` answers `PROBE_OK 384` on the new runtime.
+The remaining hold condition is unchanged: bump this package only with a live embedding check
+(model load, CPU and WebGPU backends, and a store round-trip) on the new ONNX Runtime, because
+nothing in the test suite fails when the backend is broken.
 
 Transient-failure resilience — every LLM call is a potential single point of failure on a
 streaming endpoint that can drop mid-response (undici surfaces this as `terminated`). The
@@ -409,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,32 @@ 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.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
+
+- **`@huggingface/transformers` moves 4.2.0 → 4.3.0, which closes the `adm-zip` advisory group for consumers.** The hold was lifted for a security reason, not a feature one. `4.2.0` declares `sharp ^0.34.5` and pins `onnxruntime-node` 1.24.3, whose `adm-zip ^0.5.16` resolves to the advisory-ridden `0.5.18`, and no downstream lever could lift either range: npm ignores a published dependency's `overrides`, so this repository's own `sharp` and `adm-zip` overrides reached only the tree rooted here, and the audit gate (which audits that tree) stayed green while consumers resolved the vulnerable versions. `4.3.0` ships `sharp ^0.35.4` and `onnxruntime-node` 1.30.0 (`adm-zip ^0.6.0`), so a consumer install of the published tarball drops from 7 HIGH advisories to 5, or 4 on the peer-skipping shape `pi install` uses. What remains is the `sharp 0.33.5` copy that `@lancedb/lancedb` 0.39.0's hard-pinned `@huggingface/transformers` 3.0.2 brings, clearable only by a consumer-side `overrides: {"sharp": "^0.35.4"}` (verified: 0 on the `pi install` shape), plus the host shrinkwrap's `brace-expansion`. The bump also moves the native stack with it (onnxruntime-web `1.26.0-dev.20260416` → `1.31.0-dev.20260914`, still overridden to the stable `1.24.3`) and reshapes the tree (`global-agent` 3.0.0 → 4.1.3, which drops seven packages from its old subtree: `roarr`, `boolean`, `detect-node`, `es6-error`, `json-stringify-safe`, `semver-compare`, `sprintf-js`).
+- **Incidental in-range dev refresh from the same install:** `@types/node` 26.4.1 → 26.6.3. `npm outdated` afterwards reports only the four documented holds: `apache-arrow` 21.1.0 (21.2.0 breaks LanceDB 0.39.0 IPC reads), `playwright-core` 1.60.0 (camoufox-js 0.12.0 peer cap `<1.61.0`), `typebox` 1.3.27 (lockstep with pi 0.99.2's own pin) and `typescript` 6.0.3.
+  - Decided by a live embedding check, which is the only thing that can decide it: the unit suite and the four knowledge integration suites (44 tests, 36 run, 8 skipped) pass on both versions because they mock the backend or run against an already-cached model. Against `onnx-community/granite-embedding-small-english-r2-ONNX` the new stack gives dimension 384 on both backends, CPU `initialize` 536 ms → 524 ms and `embedMany` of three texts 48 ms → 39 ms, WebGPU (Dawn/Vulkan) `initialize` 1003 ms → 1409 ms and `embedMany` 110 ms → 71 ms, related-sentence cosine 0.90431857 → 0.90431858 against 0.70265303 → 0.70265297 for the unrelated one, same-input cosine 1.0, a full store round-trip (two documents written through the real embedder, then a hybrid vector + FTS + RRF search) returning the expected top hit on both devices, and the shipped `dist/webgpu-probe.mjs` answering `PROBE_OK 384`.
+
+### Fixed
+
+- **The audit-gate runbook's claim that consumers see zero vulnerabilities was false and is withdrawn.** `docs/AUDIT-GATE.md` stated that a consumer's `npm audit --omit=dev` reported zero vulnerabilities since 2026-09-16, on the strength of an empirical run. Measured again on 2026-10-01 against the published tarball, a consumer saw 7 HIGH (adm-zip 0.5.18, sharp 0.34.5 and 0.33.5, brace-expansion 5.0.9), because the gate audits the tree rooted in this repository, where `package.json`'s `overrides` apply, and npm honors those only at the root of an install. The section now carries the measured table for all four install shapes, the consumer-side override recipe that reaches zero, the two groups that remain unfixable downstream (`sharp` via LanceDB's hard-pinned `transformers` 3.0.2, and `brace-expansion` 5.0.9 inside the pi host's `npm-shrinkwrap.json`, which survives even an explicit consumer override), and an explicit statement that a green gate says nothing about a consumer's tree. The same section's claim that both adm-zip pinning parents require `^0.6.0` is corrected: `onnxruntime-node` 1.24.3, the copy `transformers` 4.2.0 pinned, required `adm-zip ^0.5.16`.
+- **`docs/ARCHITECTURE.md`'s embedding-runtime rationale was rewritten around the new pin.** It recorded 4.3.0 as tried and rejected, and told a future maintainer that the knowledge-store suites decide a bump. They do not, since they mock the backend or use a cached model. It now records the security reason the hold was lifted, the measured before-and-after numbers for both backends, and the standing rule that a bump needs a live check (model load, CPU and WebGPU backends, store round-trip) rather than the suite.
+
 ## [1.7.3] - 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.3",
+  "version": "1.7.5",
   "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",
@@ -137,7 +138,7 @@
     "@earendil-works/pi-tui": ">=0.99.0 <1"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "4.2.0",
+    "@huggingface/transformers": "4.3.0",
     "webgpu": "^0.6.0"
   },
   "overrides": {

package/scripts/build.cjs

@@ -49,6 +49,16 @@ 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'));
+}
+
 // 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 +156,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,83 @@
+#!/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 { fileURLToPath } from 'node:url';
+
+const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
+
+const missing = REQUIRED_PEERS.filter((name) => {
+  try {
+    import.meta.resolve(name);
+    return false;
+  } catch {
+    return true;
+  }
+});
+
+if (missing.length > 0) {
+  const lines = [
+    '',
+    'Error: pi-research cannot start — it is missing required runtime dependencies:',
+    ...missing.map((name) => `    ${name}`),
+    '',
+    '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.',
+    '',
+    'Either of these fixes it:',
+    '',
+    '    npm install -g @earendil-works/pi-coding-agent   # add just the missing host package',
+    '    npm install -g @lincoln504/pi-research           # or reinstall, resolving peers',
+    '',
+  ];
+  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: