@lincoln504/pi-research 1.6.3 → 1.6.5

package/README.md

@@ -40,11 +40,17 @@ pi install npm:@lincoln504/pi-research
 Standalone, as an [agent skill](docs/AGENT-SKILL.md) for Claude Code, Codex, and other skills-compatible agents:
 
 ```bash
-npm install -g @lincoln504/pi-research
+npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3
 pi-research skill install
 ```
 
-On npm 12 or newer, add `--allow-scripts` to either install above. npm 12 stopped running dependency install scripts by default, and the stealth browser's native dependencies are built by one — without it searches fail with a missing-module error rather than a warning at install time.
+On npm 12 or newer, npm skips dependency install scripts by default; the flag allows the one that builds search's SQLite module — without it, every search fails with a missing-module error (the flag is harmless on older npm). `pi install` passes no flags to npm, so on npm 12 bracket any install or update with the same allowance as config — set, run, delete — because while the setting is in place it can break installs of other projects with git dependencies ([npm/cli#9783](https://github.com/npm/cli/issues/9783)):
+
+```bash
+npm config set allow-scripts=better-sqlite3 --location=user
+pi install npm:@lincoln504/pi-research
+npm config delete allow-scripts --location=user
+```
 
 In pi it works out of the box on the session's model and pi's configuration. Standalone use ([agent skill](docs/AGENT-SKILL.md) or [SDK](docs/SDK.md)) needs a model configured. See [Configuration](docs/CONFIGURATION.md). The first install downloads the stealth browser engine, which takes a few minutes.
 

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

@@ -43,10 +43,14 @@ model/key is missing.
   model (`PI_RESEARCH_MODEL`) + API key. See [`references/configuration.md`](references/configuration.md).
 
 ```bash
-npm install -g @lincoln504/pi-research
+npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3
 node "<skill_dir>/scripts/run.mjs" status  # verify detection
 ```
 
+On npm 12 or newer the flag is needed: npm blocks the install script that builds the
+stealth browser's SQLite module, and without it every search fails with a
+missing-module error. It is harmless on older npm.
+
 ### Install the skill
 
 Recommended. From the pi extension, run `/research-config` and choose

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

package/dist/cli.mjs

@@ -17556,7 +17556,7 @@ async function performSearch(queries, config, signal, onProgress, container = ge
     if (isNativeBindingError(sampleWorkerError)) {
       metrics.increment("browser_search_total_failures_total", 1, { cause: "native_binding" });
       throw new Error(
-        `Search completely failed: ${reason}, all with a missing native module. This is an incomplete install, not a network problem: the browser engine's native dependencies were never built. npm 12 does not run dependency install scripts by default \u2014 reinstall allowing them (npm install @lincoln504/pi-research --allow-scripts, or npm approve-scripts --allow-scripts-pending), then retry.` + (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : "")
+        `Search completely failed: ${reason}, all with a missing native module. This is an incomplete install, not a network problem: the browser engine's native dependencies were never built. npm 12 does not run dependency install scripts by default \u2014 reinstall allowing the script (global install: npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3; project install: npm approve-scripts better-sqlite3, then npm rebuild better-sqlite3), then retry.` + (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : "")
       );
     }
     throw new Error(
@@ -26752,10 +26752,14 @@ async function cmdStatus(json) {
       installed: browserInstalled,
       nativeDepsOk: nativeDeps.ok,
       nativeDepsError: nativeDeps.ok ? null : nativeDeps.error,
-      nativeDepsFix: nativeDeps.ok ? null : "Reinstall allowing dependency install scripts: npm install -g @lincoln504/pi-research --allow-scripts (npm 12 turns them off by default).",
+      // --allow-scripts is a package-name LIST, not a boolean: the bare flag is
+      // accepted and silently allows nothing (measured on npm 12.0.2). It is
+      // also global/one-off only — a project-scoped install rejects it with
+      // EALLOWSCRIPTS, where `npm approve-scripts` is the supported route.
+      nativeDepsFix: nativeDeps.ok ? null : "Reinstall allowing the dependency install script: npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3 (npm 12 blocks dependency install scripts by default). For a project-scoped install: npm approve-scripts better-sqlite3, then npm rebuild better-sqlite3.",
       // Same remedy the health check prints, so both surfaces name one command.
       fix: browserInstalled ? null : "npx camoufox-js fetch",
-      note: browserInstalled ? null : "Stealth browser not installed \u2014 scraping falls back to plain fetch, which some sites block. npm 11.19+ blocks install scripts by default, which skips this package's postinstall."
+      note: browserInstalled ? null : "Stealth browser not installed \u2014 scraping falls back to plain fetch, which some sites block. npm 12 blocks install scripts by default, which skips this package's postinstall; the engine is fetched on first use instead."
     },
     knowledgeStoreMode: cfg.KNOWLEDGE_STORE_MODE,
     defaultDepth: cfg.DEFAULT_RESEARCH_DEPTH,

package/docs/AGENT-SKILL.md

@@ -17,10 +17,15 @@ For standalone use without pi, install the engine globally, then link the skill
 every coding agent detected on this machine:
 
 ```bash
-npm install -g @lincoln504/pi-research   # the engine (puts `pi-research` on PATH)
+npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3   # the engine (puts `pi-research` on PATH)
 pi-research skill install                # link the skill into every detected agent
 ```
 
+On npm 12 or newer the flag is needed: npm blocks dependency install scripts by
+default, and without the one that builds the stealth browser's SQLite module every
+search fails with a missing-module error. It is harmless on older npm (see the
+[README](../README.md#install)).
+
 `skill install` targets only agents already set up under `$HOME`, never overwrites a
 different skill in the slot, and records what it created so `pi-research skill uninstall`
 removes exactly that. Run `pi-research skill status` to see where it is installed.
@@ -125,7 +130,7 @@ Manual. Symlink the directory into any agent's skills folder yourself:
   (`PI_RESEARCH_MODEL`) + API key. See [Configuration](CONFIGURATION.md).
 
 ```bash
-npm install -g @lincoln504/pi-research
+npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3
 node "<skill_dir>/scripts/run.mjs" status   # verify the engine is detected
 ```
 

package/docs/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.6.5] - 2026-08-26
+
+1.6.4 verified its commands and then recommended the wrong one first: the user-level
+`allow-scripts` config that "covers every install path" does cover them — at a cost
+npm's own tracker had already documented, which the container runs (installing only
+this package) could not see.
+
+### Fixed
+
+- **The install docs led with a config setting that breaks unrelated projects.** While a user-level `allow-scripts` is set, any `npm install` or `npm ci` of a project with a git dependency fails with `EALLOWSCRIPTS` (npm/cli#9783, filed 2026-07-18): git-dependency preparation spawns an inner project-scoped install that receives the setting as `npm_config_allow_scripts`, where npm judges it as a forbidden command-line flag. The same env-forwarding breaks any install reached through `npm run-script` (npm/cli#9912, filed 2026-08-24) — including a `pi install` invoked from an npm script. The 1.6.4 remedy also never said to remove the setting, so a user following it kept the trap armed permanently. Every surface now leads with the remedy that touches nothing else: the inline `--allow-scripts=better-sqlite3` flag on the global install (a one-off — harmless on npm 11.16–11.19, where it at most silences the advisory warning, and on npm ≤11.15, where an unknown config flag is an accepted warning, measured: warning and exit 0), project-local `npm approve-scripts better-sqlite3` + `npm rebuild better-sqlite3` for the SDK path (also the repair for an install that already ran blocked), and for `pi install` — which passes no flags to npm — set the config, install, delete it again, with the reason stated at the point of use. The README prose is shorter than what it replaces (`README.md`, `docs/SDK.md`, `docs/AGENT-SKILL.md`, `agent-skill/pi-research/README.md`).
+- **The manual per-agent install section showed a bare `npm install -g`.** The npm-12 note sat ~110 lines above at the top of the page, so a reader landing at the manual flow — or arriving by search — saw an unguarded command whose failure mode is a search that dies with a missing-module error and an install that reported success. The flag now rides on the command itself, which needs no note (`docs/AGENT-SKILL.md`).
+- **The 1.6.3 "Verified" line named one job for two failures.** It credited "the ubuntu-latest job that caught the failure" directly below a bullet whose failure was seen on macos-latest; the release contained two failures on two runners (the lock race on ubuntu, the cleanup crash on macos). The line now names both, so the record matches the commits (`docs/CHANGELOG.md`).
+
+### Verified
+
+- 2938 unit tests over 233 files, lint, and type-check green.
+- The flag-on-the-line and approve+rebuild forms are the same forms 1.6.4 measured working in npm 12.0.2 containers. The older-npm acceptance of the flag was measured directly (an unknown config flag warns and exits 0, so the install line is safe on the npm shipped with the minimum supported Node). The set-install-delete bracket reuses the config form 1.6.4 verified reaching `pi install`, with the removal step and its reason taken from npm/cli#9783's workaround guidance.
+
+## [1.6.4] - 2026-08-26
+
+The npm 12 install remedy shipped in 1.6.2 was put through real installs in
+disposable npm 12.0.2 containers and found not to work: the bare `--allow-scripts`
+flag every surface recommended is accepted by npm and allows nothing.
+
+### Fixed
+
+- **`status` and the total-search-failure error printed a repair command that repairs nothing.** Measured per npm version against a scripted tarball: npm ≤11.15 runs dependency install scripts silently, 11.16–11.19 warn but still run them, and npm 12 blocks them — so the 1.6.2 claim that "npm 11.19+ blocks" was wrong on version, and the remedy was worse than wrong on form: `--allow-scripts` is a comma-separated package-name list, so the bare flag is accepted and allows nothing — the install stays broken. The flag is also global-install-only: a project-scoped install (the SDK path, and what `pi install` runs underneath) rejects it with `EALLOWSCRIPTS`. And after a blocked install, approving and rerunning `npm install` does not rebuild the already-extracted package. Both surfaces now print commands measured to work — `--allow-scripts=better-sqlite3` for a global install; `npm approve-scripts better-sqlite3` then `npm rebuild better-sqlite3` for a project-scoped one (`src/cli.ts`, `src/web-research/browser-search.ts`).
+
+### Changed
+
+- **Install docs lead with the one form measured to cover every install path** — `npm config set allow-scripts=better-sqlite3 --location=user`, verified against a fresh `pi install` and a project install — and the npm 12 note now appears on every surface that shows an install command (README, SDK, agent-skill docs, and the shipped skill README) rather than the README alone, with the wording tightened.
+
+### Verified
+
+- Each printed command form measured on real installs in npm 12.0.2 containers: the global flag form builds the binding, the user-level config form covers global, project, and `pi install`, and the approve + rebuild flow repairs an already-blocked install.
+- 2938 unit tests over 233 files, lint, and type-check green.
+
 ## [1.6.3] - 2026-08-25
 
 A unit test that had already been granted CI-jitter headroom twice went red a third
@@ -19,7 +56,7 @@ identified a real race in the lock acquire loop rather than a slow runner.
 
 ### Verified
 
-- 2938 unit tests over 233 files, lint, type-check, and the full CI matrix green on the fix commit — including the ubuntu-latest job that caught the failure.
+- 2938 unit tests over 233 files, lint, type-check, and the full CI matrix green on the fix commits — including the ubuntu-latest job that caught the lock race and the macos-latest job that caught the cleanup crash.
 
 ## [1.6.2] - 2026-08-24
 

package/docs/SDK.md

@@ -13,6 +13,19 @@ run the `pi` extension, which keeps its own private copy your scripts can't impo
 npm install @lincoln504/pi-research
 ```
 
+On npm 12 or newer, npm skips dependency install scripts by default and a project-scoped
+install rejects the `--allow-scripts` flag — record the one script search depends on in
+your project instead, then run it:
+
+```bash
+npm approve-scripts better-sqlite3   # pins the approval in your allowScripts field
+npm rebuild better-sqlite3
+```
+
+Without that script every search fails with a missing-module error, and rerunning
+`npm install` does not run it — `npm rebuild` does. The same pair repairs an install
+that already ran blocked.
+
 Then pick the model: pass `model` to `initResearchSDK`, or set `PI_RESEARCH_MODEL`
 (env or `~/.pi/research/config.env`). The SDK never follows the model selected
 inside the pi extension; only when neither is set does it fall back to the first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -793,9 +793,10 @@ async function cmdStatus(json?: boolean): Promise<number> {
   const paths = resolvedConfigPaths();
   const cfg = getConfig(process.cwd(), 'cli');
   // The stealth browser is installed by this package's `postinstall`
-  // (scripts/setup.cjs), which npm 11.19+ BLOCKS BY DEFAULT — it now warns
-  // "packages have install scripts not yet covered by allowScripts" and carries
-  // on, so the browser is simply absent on an otherwise successful install.
+  // (scripts/setup.cjs), which npm 12 BLOCKS BY DEFAULT (11.16–11.19 only warn
+  // and still run it — measured per version against a scripted tarball) — npm
+  // prints "packages had install scripts blocked" and carries on, so the
+  // browser is simply absent on an otherwise successful install.
   // A missing browser DEGRADES capability rather than breaking the tool — the fetch
   // path still serves most pages — so it is reported alongside `ready` rather than
   // folded into it. isBrowserAvailable() is a resolve + existsSync; it never launches
@@ -827,14 +828,18 @@ async function cmdStatus(json?: boolean): Promise<number> {
       installed: browserInstalled,
       nativeDepsOk: nativeDeps.ok,
       nativeDepsError: nativeDeps.ok ? null : nativeDeps.error,
+      // --allow-scripts is a package-name LIST, not a boolean: the bare flag is
+      // accepted and silently allows nothing (measured on npm 12.0.2). It is
+      // also global/one-off only — a project-scoped install rejects it with
+      // EALLOWSCRIPTS, where `npm approve-scripts` is the supported route.
       nativeDepsFix: nativeDeps.ok
         ? null
-        : 'Reinstall allowing dependency install scripts: npm install -g @lincoln504/pi-research --allow-scripts (npm 12 turns them off by default).',
+        : 'Reinstall allowing the dependency install script: npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3 (npm 12 blocks dependency install scripts by default). For a project-scoped install: npm approve-scripts better-sqlite3, then npm rebuild better-sqlite3.',
       // Same remedy the health check prints, so both surfaces name one command.
       fix: browserInstalled ? null : 'npx camoufox-js fetch',
       note: browserInstalled
         ? null
-        : 'Stealth browser not installed — scraping falls back to plain fetch, which some sites block. npm 11.19+ blocks install scripts by default, which skips this package\'s postinstall.',
+        : 'Stealth browser not installed — scraping falls back to plain fetch, which some sites block. npm 12 blocks install scripts by default, which skips this package\'s postinstall; the engine is fetched on first use instead.',
     },
     knowledgeStoreMode: cfg.KNOWLEDGE_STORE_MODE,
     defaultDepth: cfg.DEFAULT_RESEARCH_DEPTH,

package/src/web-research/browser-search.ts

@@ -333,8 +333,9 @@ export async function performSearch(
                 `Search completely failed: ${reason}, all with a missing native module. ` +
                 `This is an incomplete install, not a network problem: the browser engine's ` +
                 `native dependencies were never built. npm 12 does not run dependency install ` +
-                `scripts by default — reinstall allowing them (npm install @lincoln504/pi-research ` +
-                `--allow-scripts, or npm approve-scripts --allow-scripts-pending), then retry.` +
+                `scripts by default — reinstall allowing the script (global install: ` +
+                `npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3; ` +
+                `project install: npm approve-scripts better-sqlite3, then npm rebuild better-sqlite3), then retry.` +
                 (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : '')
             );
         }