@lincoln504/pi-research 1.6.1 → 1.6.3

package/README.md

@@ -44,11 +44,13 @@ npm install -g @lincoln504/pi-research
 pi-research skill install
 ```
 
-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 pulls the stealth browser engine, which takes a few minutes.
+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.
+
+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.
 
 ### How it works
 
-A research run loops through agent teams: a coordinator plans and opens with a search, researcher agents scrape and read in parallel, and a research lead decides whether to go another round — then writes the report from every report collected. The result is one cited Markdown report with findings optionally saved to the knowledge store.
+A research run loops through agent teams: a coordinator plans and starts with a search, researcher agents scrape and read in parallel, and a research lead decides whether to go another round — then writes the report from every report collected. The result is one cited Markdown report with findings optionally saved to the knowledge store.
 
 Three depth levels (normal, deep, ultra) set the team size and number of rounds. A natural-language request is enough — the tool picks the right one:
 
@@ -61,13 +63,12 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 - Keeping a persistent and searchable knowledge store of findings, scoped globally or per project.
 - Building agent systems that find and read web content, or populating a dataset of web sources.
 
-### Why pi-research
+### Why
 
 - **No quota and no monthly fee.** Most AI search providers cap free searches and then charge, with results served from their index on their servers. pi-research searches and scrapes locally through DuckDuckGo in a stealth browser.
-- **The index stays local.** Every finding can be saved to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
-- **Cited reports rather than raw dumps.** Each run returns one sourced Markdown report instead of raw web content pasted into the conversation. Context efficient and easy to verify.
+- **The index is local.** Every finding can be saved to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
 - **Read-only by design.** The research agent cannot run shell commands or write, edit, or delete anything — the right shape for an agent whose whole job is reading untrusted web pages. Prompt injection picked up mid-run has nothing to act on.
-- **Search a little or a lot.** Depth levels span a quick pass to a large-scale investigation.
+- **Search a little or a lot.** Depth levels range from a quick pass to a large-scale investigation.
 
 ### Requirements / limitations
 
@@ -75,7 +76,7 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 - An LLM with a 100k+ context window (an API key or a local model)
 - Internet access on a residential IP, since search, scraping, and YouTube transcripts get bot-blocked from datacenter/VPS/cloud IPs
 - pi. The pi extension uses the host's copy while the standalone CLI and agent skill install it as a dependency.
-- Cloudflare and similar systems block scraping on some sites. A run flags unreachable pages and compensates with a wide pool of search results to cite.
+- Cloudflare Turnstile and similar systems block scraping on some sites. A run compensates with a wide pool of search results to scrape.
 
 ### Channels
 

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

package/dist/cli.mjs

@@ -6831,7 +6831,7 @@ var init_file_lock_service = __esm({
                 const errnoError = error;
                 if (errnoError.code === "EEXIST") {
                   contentionCount++;
-                  let reclaimEligibleAt = null;
+                  let awaitingReclaim = false;
                   try {
                     const rawContent = await fs7.readFile(this.lockFilePath, "utf-8");
                     const parsed = this._parseLockContent(rawContent);
@@ -6843,7 +6843,7 @@ var init_file_lock_service = __esm({
                     }
                     lastSeenUuid = lockUuid;
                     lastSeenMtime = stats.mtimeMs;
-                    reclaimEligibleAt = (parsed?.pid ?? null) === null ? stats.mtimeMs + this._unidentifiedStaleThreshold() : null;
+                    awaitingReclaim = this.lockTimeout > 0 && (parsed?.pid ?? null) === null && lockAge <= this._unidentifiedStaleThreshold();
                     if (lockUuid === this.lockUuid) {
                       try {
                         await fs7.unlink(this.lockFilePath);
@@ -6880,7 +6880,6 @@ var init_file_lock_service = __esm({
                   }
                   const stalledFor = Date.now() - lastProgressAt;
                   const waitedFor = Date.now() - startTime;
-                  const awaitingReclaim = this.lockTimeout > 0 && reclaimEligibleAt !== null && Date.now() < reclaimEligibleAt;
                   if (stalledFor >= this.lockTimeout && !awaitingReclaim || waitedFor >= this.acquireCeilingMs) {
                     metrics.observe("state_lock_acquire_duration_ms", waitedFor, { status: "timeout" });
                     metrics.increment("state_lock_acquire_total", 1, { status: "timeout" });
@@ -10283,9 +10282,17 @@ function detectHarnesses(opts) {
       }
     } catch {
     }
-    return { ...h, present, absSkillsDir, absSkillPath, installed };
+    const broken = (installed === "owned-symlink" || installed === "owned-copy") && !isUsableSkillDir(absSkillPath);
+    return { ...h, present, absSkillsDir, absSkillPath, installed, broken };
   });
 }
+function isUsableSkillDir(p) {
+  try {
+    return fs16.existsSync(path18.join(p, "SKILL.md")) && fs16.existsSync(path18.join(p, "scripts", "run.mjs"));
+  } catch {
+    return false;
+  }
+}
 function isSymlinkPresent(p) {
   try {
     return fs16.lstatSync(p).isSymbolicLink();
@@ -10455,8 +10462,8 @@ function reconcileSkillInstalls(opts = {}) {
   const keep = [];
   for (const e of manifest.entries) {
     if (e.type !== "symlink") {
-      const stale2 = currentVersion !== null && e.version !== currentVersion;
-      if (stale2 && source !== null && fs16.existsSync(e.path) && isOwnedCopy(e.path)) {
+      const stale = currentVersion !== null && e.version !== currentVersion;
+      if (stale && source !== null && fs16.existsSync(e.path) && isOwnedCopy(e.path)) {
         const dir2 = path18.dirname(e.path);
         const base2 = path18.basename(e.path);
         try {
@@ -10533,14 +10540,8 @@ function reconcileSkillInstalls(opts = {}) {
       keep.push(e);
       continue;
     }
-    const targetLive = fs16.existsSync(e.path);
-    let dest = null;
-    try {
-      dest = path18.resolve(path18.dirname(e.path), fs16.readlinkSync(e.path));
-    } catch {
-    }
-    const stale = source !== null && dest !== null && dest !== path18.resolve(source);
-    if (!targetLive || stale) {
+    const targetLive = fs16.existsSync(e.path) && isUsableSkillDir(e.path);
+    if (!targetLive) {
       if (source !== null) {
         try {
           fs16.unlinkSync(e.path);
@@ -12318,6 +12319,7 @@ import * as crypto4 from "node:crypto";
 import { join as join8 } from "node:path";
 import { existsSync as existsSync6, mkdirSync as mkdirSync3 } from "node:fs";
 import { platform, homedir as homedir3 } from "node:os";
+import { createRequire as createRequire3 } from "node:module";
 function getWindowsCamoufoxDir() {
   return join8(homedir3(), "AppData", "Local", "camoufox", "camoufox", "Cache");
 }
@@ -12426,6 +12428,20 @@ function resolveHeadlessMode() {
   if (process.env["PI_RESEARCH_USE_XVFB"] === "true") return "virtual";
   return true;
 }
+function probeBrowserNativeDeps(load = defaultNativeDepLoad) {
+  try {
+    load();
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message.split("\n")[0].trim() : String(err) };
+  }
+}
+function defaultNativeDepLoad() {
+  const require2 = createRequire3(import.meta.url);
+  const Database = require2("better-sqlite3");
+  const db = new Database(":memory:");
+  db.close();
+}
 function isBrowserAvailable() {
   if (isFullMockMode()) return false;
   try {
@@ -12518,6 +12534,11 @@ function isPoolShutdownError(error) {
   // same transient swap the "being reset" string covers, not a hard fault.
   err.message.includes("Cannot execute a task on not started pool"));
 }
+var NATIVE_BINDING_FAILURE = /Could not locate the bindings file|ERR_DLOPEN_FAILED|NODE_MODULE_VERSION|was compiled against a different Node\.js version|invalid ELF header|Cannot find module '[^']*\.node'/;
+function isNativeBindingError(error) {
+  const msg2 = error instanceof Error ? error.message : String(error);
+  return NATIVE_BINDING_FAILURE.test(msg2);
+}
 var BENIGN_NAVIGATION_FAILURE = /page\.goto: (?:Timeout \d+ *ms exceeded|net::|NS_ERROR_|SEC_ERROR_|MOZILLA_PKIX_ERROR_)/;
 function isBenignScrapeFailure(error) {
   const msg2 = error instanceof Error ? error.message : String(error);
@@ -15749,7 +15770,7 @@ import { FixedClusterPool, WorkerChoiceStrategies } from "poolifier";
 // src/infrastructure/browser/ensure-browser.ts
 init_logger();
 import { spawn as spawn2 } from "node:child_process";
-import { createRequire as createRequire3 } from "node:module";
+import { createRequire as createRequire4 } from "node:module";
 import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync7, readdirSync as readdirSync3, statSync as statSync3, fstatSync, openSync as openSync4, closeSync as closeSync4, rmSync } from "node:fs";
 import { join as join11, dirname as dirname8 } from "node:path";
@@ -15776,7 +15797,7 @@ function isBrowserBinaryPresent() {
 }
 function resolveCamoufoxBin() {
   try {
-    const require2 = createRequire3(import.meta.url);
+    const require2 = createRequire4(import.meta.url);
     const pkgJson = require2.resolve("camoufox-js/package.json");
     const bin = join11(dirname8(pkgJson), "..", ".bin", process.platform === "win32" ? "camoufox-js.cmd" : "camoufox-js");
     if (existsSync7(bin)) return bin;
@@ -17532,6 +17553,12 @@ async function performSearch(queries, config, signal, onProgress, container = ge
     } else if (timeoutCount + errorCount === filteredQueries.length) {
       reason = `${timeoutCount} queries timed out and ${errorCount} queries failed`;
     }
+    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}` : "")
+      );
+    }
     throw new Error(
       `Search completely failed: ${reason}. Browser workers may be unavailable, DuckDuckGo is unreachable, or the system is under extreme load.` + (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : "")
     );
@@ -26707,11 +26734,12 @@ async function cmdStatus(json) {
   const paths = resolvedConfigPaths();
   const cfg = getConfig(process.cwd(), "cli");
   const browserInstalled = isBrowserAvailable();
+  const nativeDeps = probeBrowserNativeDeps();
   const summary = {
     package: "@lincoln504/pi-research",
     version: PKG_VERSION,
     cli: `node ${process.argv[1]}`,
-    ready: !det.problem,
+    ready: !det.problem && nativeDeps.ok,
     credentials: {
       source: det.source,
       apiKeyConfigured: det.apiKeyConfigured,
@@ -26722,6 +26750,9 @@ async function cmdStatus(json) {
     },
     browser: {
       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).",
       // 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."
@@ -26739,7 +26770,16 @@ async function cmdStatus(json) {
   toStdout(`ready: ${summary.ready ? "yes" : "no"}
 
 `);
-  toStdout(configBlock(det, summary.ready ? void 0 : "\u2014 fix the problem above, then re-run.") + "\n");
+  toStdout(configBlock(det, det.problem ? "\u2014 fix the problem above, then re-run." : void 0) + "\n");
+  if (!summary.browser.nativeDepsOk) {
+    toStdout(`
+browser engine: BROKEN \u2014 native dependencies were never built, so no search can run.
+`);
+    toStdout(`  ${summary.browser.nativeDepsFix}
+`);
+    toStdout(`  Underlying error: ${summary.browser.nativeDepsError}
+`);
+  }
   if (!summary.browser.installed) {
     toStdout(`
 stealth browser: NOT INSTALLED \u2014 run: ${summary.browser.fix}
@@ -26812,7 +26852,7 @@ async function cmdSkill(s) {
       toStdout(pretty({
         command: "skill",
         action: "status",
-        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, path: d.absSkillPath }))
+        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, broken: d.broken, path: d.absSkillPath }))
       }));
       return EXIT.OK;
     }
@@ -26820,7 +26860,8 @@ async function cmdSkill(s) {
 
 `);
     for (const d of agents) {
-      const state = !d.present ? "agent not detected" : d.installed === "none" ? "not installed" : d.installed === "foreign" ? "a different skill occupies this slot \u2014 left untouched" : `installed (${d.installed === "owned-copy" ? "copy" : "symlink"})`;
+      const kind = d.installed === "owned-copy" ? "copy" : "symlink";
+      const state = !d.present ? "agent not detected" : d.installed === "none" ? "not installed" : d.installed === "foreign" ? "a different skill occupies this slot \u2014 left untouched" : d.broken ? `BROKEN ${kind} \u2014 target is missing or incomplete; re-run \`${BINARY_NAME} skill install\`` : `installed (${kind})`;
       const loc = d.installed === "owned-symlink" || d.installed === "owned-copy" ? `  \u2192 ${d.absSkillPath}` : "";
       toStdout(`  ${d.label.padEnd(18)} ${state}${loc}
 `);

package/docs/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.3] - 2026-08-25
+
+A unit test that had already been granted CI-jitter headroom twice went red a third
+time — and this time the timing signature (rejection 10008ms into a 10000ms window)
+identified a real race in the lock acquire loop rather than a slow runner.
+
+### Fixed
+
+- **A waiter gave up on a torn lock at the exact moment its reclaim window opened.** The acquire loop's reclaim decision measures the lock's age at `fs.stat` time, but the stall-check exemption that keeps a waiter alive until that reclaim ("never give up on a lock we are about to be allowed to take") compared a fresh `Date.now()` against the window. For the few milliseconds between the stat and the stall check the two clocks could disagree, and a retry tick landing astride the window boundary satisfied neither: not yet reclaimable by its stat, no longer awaited by the clock. Since a torn, pid-less lock never shows progress, the long-expired stall bound then fired, and a wait that had correctly outlasted it was abandoned right as the recovery became permitted — in production, a knowledge-store init failing at the moment it could have recovered. Both judgments now derive from the same observation, so every tick that can read the lock either reclaims it or keeps waiting; the try-take exclusion and the absolute ceiling are unchanged (`src/infrastructure/file-lock-service.ts`).
+- **The test's forensic comment blamed scheduler jitter for all three CI failures.** True for the first two (which failed at the stall bound); wrong for this one (which failed at the window boundary). The record now distinguishes the two mechanisms (`test/unit/infrastructure/file-lock-progress-aware-wait.test.ts`).
+- **A browser-config test deleted the whole suite's shared log directory as its own cleanup.** `unit-env.ts` routes every unit worker's log into `<tmpdir>/pi-research-test/`; the profile-containment test nested its scratch path inside that directory and removed the shared parent recursively — destroying the live log out from under every parallel worker, and racing the lazy logger re-creating the file mid-removal, which is an `ENOTEMPTY` crash of the cleanup itself (seen on macos-latest CI on this release's first tag). The test now creates its own `mkdtemp` directory and removes only that (`test/unit/infrastructure/browser-config.test.ts`).
+
+### 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.
+
+## [1.6.2] - 2026-08-24
+
+An agent-skill run reported that every search had failed and concluded it had hit an
+unfixable environment problem. It was half right: the install really was broken, but
+nothing in the tool would say so, and one of the two causes was the tool's own doing.
+
+### Fixed
+
+- **A second install captured the skill links of the first.** `reconcileSkillInstalls()` runs on every engine-touching CLI invocation and resolves its source from whichever copy is being invoked. It re-pointed any owned link whose destination differed — including a perfectly healthy one — so an ordinary second install captured the user's global Claude/Codex/OpenClaw skill links merely by being run once. That is a documented setup, not an exotic one: `docs/SDK.md` instructs users to `npm install @lincoln504/pi-research` INTO their project so the SDK imports resolve, and anything that then ran the project-local CLI moved the global skill into the project. Moving, cleaning or deleting the project later killed the skill with an opaque `Cannot find module …/scripts/run.mjs`. Reconcile now repairs only a link that is dangling or whose target has been gutted — the case it was written for, which is what an update that relocates the package actually produces. Choosing between two live installs is what the explicit `skill install` is for. Two existing tests asserted the old behaviour and were unfaithful in the same way: each described "package relocated by an update" while leaving the old directory on disk, so the link never dangled (`src/skill-install/skill-installer.ts`).
+- **`skill status` called a dead skill installed.** Detection tested that the link existed, never that it resolved, so a dangling symlink reported as `installed (symlink)` — leaving the harness's later "Cannot find module" as the only signal anything was wrong. A link or copy whose target is missing, or which lacks `SKILL.md` / `scripts/run.mjs`, is now reported as BROKEN with the command that repairs it (`src/skill-install/skill-installer.ts`, `src/cli.ts`).
+- **`status` reported a build that cannot search as ready.** npm 12 turns dependency install scripts off by default. `camoufox-js` needs `better-sqlite3` to launch a browser at all, and its binding is produced by exactly such a script — so the module imports fine and throws only at first use. `ready` was derived from credentials alone and said yes; `isBrowserAvailable()` only stats the camoufox binary and never sees it. Measured across every native dependency this package ships: better-sqlite3 is the ONLY one that fails that way — onnxruntime-node carries its binding inside its own tarball, and lancedb, impit and html-to-markdown resolve prebuilt platform packages, which is why the knowledge store kept answering while search was dead. `status` now opens an in-memory database to settle it, gates `ready` on the result, and prints the remedy. The old comment claiming "nothing else fails" was wrong and is corrected (`src/infrastructure/browser/config.ts`, `src/cli.ts`).
+- **A broken install was reported as a network outage.** With no binding, every browser worker dies identically and the run said browser workers may be unavailable, DuckDuckGo unreachable, or the system under extreme load. All three were false and none is actionable — a calling agent read it and gave up rather than reinstalling. A total search failure whose workers all died on a missing native module now says it is an incomplete install and names the flag that fixes it (`src/infrastructure/browser/browser-error-utils.ts`, `src/web-research/browser-search.ts`).
+
+### Changed
+
+- **README documents the npm 12 install flag** on the install commands themselves, and drops a claim that a run flags unreachable pages. Turnstile is named because it is the challenge readers actually hit, and a handful of inflated verbs are now plain ones.
+
+### Verified
+
+- 2938 unit tests over 233 files, lint, type-check over source and tests, dependency-cruiser.
+- The failure mode was reproduced and the remedy measured: a scripts-blocked install of 1.6.1 fails `better-sqlite3` at first use and passes every other native dependency. A live agent-skill run through the installed link completes clean with zero binding errors.
+
 ## [1.6.1] - 2026-08-23
 
 A report that contained no analysis was being delivered as a completed run, because

package/package.json

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

package/src/cli.ts

@@ -45,7 +45,7 @@ import { getConfig, getGlobalConfigDir, getGlobalEnvFilePath, getInterfaceEnvFil
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { buildModelRegistry, safeGetAvailable } from './core/llm/model-registry-factory.ts';
 import { RESEARCH_TOOL_NAMES } from './constants.ts';
-import { isBrowserAvailable } from './infrastructure/browser/config.ts';
+import { isBrowserAvailable, probeBrowserNativeDeps } from './infrastructure/browser/config.ts';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -796,19 +796,25 @@ async function cmdStatus(json?: boolean): Promise<number> {
   // (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.
-  // Every other native artifact survives that (onnxruntime, sharp, esbuild and
-  // webgpu all ship prebuilt platform packages), which is exactly what makes
-  // this one worth reporting: nothing else fails, and without this the first
-  // symptom is a scrape falling back mid-run. 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 anything.
+  // 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
+  // anything.
+  //
+  // The browser's NATIVE DEPENDENCIES are a separate and harsher question, and were
+  // previously assumed away here with "nothing else fails". Measured: better-sqlite3,
+  // which camoufox-js needs to launch at all, is built by a dependency install script
+  // and does NOT survive a scripts-blocked install. When it is missing every browser
+  // worker dies and SEARCH IS DEAD — not degraded — while the knowledge store keeps
+  // working because onnxruntime and lancedb both ship their binaries. That is not a
+  // capability note, so it gates `ready`: a build that cannot search cannot research.
   const browserInstalled = isBrowserAvailable();
+  const nativeDeps = probeBrowserNativeDeps();
   const summary = {
     package: '@lincoln504/pi-research',
     version: PKG_VERSION,
     cli: `node ${process.argv[1]}`,
-    ready: !det.problem,
+    ready: !det.problem && nativeDeps.ok,
     credentials: {
       source: det.source,
       apiKeyConfigured: det.apiKeyConfigured,
@@ -819,6 +825,11 @@ async function cmdStatus(json?: boolean): Promise<number> {
     },
     browser: {
       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).',
       // Same remedy the health check prints, so both surfaces name one command.
       fix: browserInstalled ? null : 'npx camoufox-js fetch',
       note: browserInstalled
@@ -837,7 +848,19 @@ async function cmdStatus(json?: boolean): Promise<number> {
 
   toStdout(`pi-research ${PKG_VERSION}\n`);
   toStdout(`ready: ${summary.ready ? 'yes' : 'no'}\n\n`);
-  toStdout(configBlock(det, summary.ready ? undefined : '— fix the problem above, then re-run.') + '\n');
+  // The hint points at the CONFIG block, so it belongs to a credential problem only.
+  // `ready` can now also be false because the browser's native deps are missing, and
+  // that is reported below with its own remedy — sending the reader back to a config
+  // block that has nothing wrong with it would be its own small lie.
+  toStdout(configBlock(det, det.problem ? '— fix the problem above, then re-run.' : undefined) + '\n');
+  if (!summary.browser.nativeDepsOk) {
+    // Printed BEFORE the browser-download note: a missing binary is a degradation the
+    // fetch path covers, while a missing binding means no search runs at all. The more
+    // severe problem has to be the one the reader sees first.
+    toStdout(`\nbrowser engine: BROKEN — native dependencies were never built, so no search can run.\n`);
+    toStdout(`  ${summary.browser.nativeDepsFix}\n`);
+    toStdout(`  Underlying error: ${summary.browser.nativeDepsError}\n`);
+  }
   if (!summary.browser.installed) {
     toStdout(`\nstealth browser: NOT INSTALLED — run: ${summary.browser.fix}\n`);
     toStdout(`  ${summary.browser.note}\n`);
@@ -940,16 +963,21 @@ async function cmdSkill(s: NonNullable<ParsedArgs['skill']>): Promise<number> {
     if (s.json) {
       toStdout(pretty({
         command: 'skill', action: 'status',
-        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, path: d.absSkillPath })),
+        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, broken: d.broken, path: d.absSkillPath })),
       }));
       return EXIT.OK;
     }
     toStdout(`pi-research agent skill — install status\n\n`);
     for (const d of agents) {
+      // A broken install must not read as a working one. It said "installed (symlink)"
+      // for a link whose target had been deleted, so the only sign anything was wrong
+      // came later, from the harness, as "Cannot find module …/scripts/run.mjs".
+      const kind = d.installed === 'owned-copy' ? 'copy' : 'symlink';
       const state = !d.present ? 'agent not detected'
         : d.installed === 'none' ? 'not installed'
         : d.installed === 'foreign' ? 'a different skill occupies this slot — left untouched'
-        : `installed (${d.installed === 'owned-copy' ? 'copy' : 'symlink'})`;
+        : d.broken ? `BROKEN ${kind} — target is missing or incomplete; re-run \`${BINARY_NAME} skill install\``
+        : `installed (${kind})`;
       const loc = d.installed === 'owned-symlink' || d.installed === 'owned-copy' ? `  → ${d.absSkillPath}` : '';
       toStdout(`  ${d.label.padEnd(18)} ${state}${loc}\n`);
     }

package/src/infrastructure/browser/browser-error-utils.ts

@@ -124,6 +124,27 @@ export function isPoolShutdownError(error: unknown): boolean {
     );
 }
 
+/**
+ * A native addon that is missing or unloadable, i.e. a BROKEN INSTALL rather than
+ * anything about the page, the network or the load on the machine.
+ *
+ * The case that produced this: npm 12 turns `allowScripts` OFF by default, so a
+ * plain `npm install` no longer runs dependency lifecycle scripts — including the
+ * one that fetches/builds `better-sqlite3`, which `camoufox-js` needs to launch a
+ * browser at all. Every browser worker then dies with "Could not locate the
+ * bindings file", every query fails, and the run reported that DuckDuckGo might be
+ * unreachable or the machine under extreme load. Neither was true, and the advice
+ * that follows from each is useless. An install fault has to say so.
+ */
+const NATIVE_BINDING_FAILURE =
+  /Could not locate the bindings file|ERR_DLOPEN_FAILED|NODE_MODULE_VERSION|was compiled against a different Node\.js version|invalid ELF header|Cannot find module '[^']*\.node'/;
+
+/** True when the failure is a missing/unloadable native addon — a broken install. */
+export function isNativeBindingError(error: unknown): boolean {
+  const msg = error instanceof Error ? error.message : String(error);
+  return NATIVE_BINDING_FAILURE.test(msg);
+}
+
 /** Playwright navigation failures whose cause is at the remote end — see below. */
 const BENIGN_NAVIGATION_FAILURE =
   /page\.goto: (?:Timeout \d+ *ms exceeded|net::|NS_ERROR_|SEC_ERROR_|MOZILLA_PKIX_ERROR_)/;

package/src/infrastructure/browser/config.ts

@@ -12,6 +12,7 @@ import { platform, homedir } from 'node:os';
 import type { Config } from '../../config.ts';
 import { getConfig } from '../../config.ts';
 import { getLogger } from '../../logger.ts';
+import { createRequire } from 'node:module';
 
 // ============================================================================
 // Binary Cache Management
@@ -310,6 +311,48 @@ export function resolveHeadlessMode(): boolean | 'virtual' {
  * 
  * Single point of control: all existing skipTests() checks use this function.
  */
+/**
+ * Whether the browser stack's NATIVE dependencies can actually load.
+ *
+ * `isBrowserAvailable()` answers a different question — is the camoufox binary on
+ * disk — and a browser can be fully downloaded and still unable to launch. camoufox-js
+ * requires `better-sqlite3`, whose binding is produced by a dependency INSTALL SCRIPT,
+ * and npm 12 turns those off by default. The module then imports fine and throws only
+ * when first used, so nothing notices until every browser worker dies mid-run with
+ * "Could not locate the bindings file" and the run reports a network problem it does
+ * not have.
+ *
+ * Measured, not assumed: of this package's native dependencies, only better-sqlite3
+ * fails a scripts-blocked install. onnxruntime-node ships its binding inside its own
+ * tarball, and lancedb, impit and html-to-markdown all resolve prebuilt platform
+ * packages, so the knowledge store keeps working while search is dead — exactly the
+ * split seen in the field.
+ *
+ * Opening an in-memory database is the only check that settles it: resolving the
+ * module or stat-ing a path does not, because the failure is in the binding lookup at
+ * first use. It costs a few milliseconds and is confined to diagnostics.
+ */
+export function probeBrowserNativeDeps(
+    /** Injected for tests. Production callers pass nothing. */
+    load: () => void = defaultNativeDepLoad,
+): { ok: true } | { ok: false; error: string } {
+    try {
+        load();
+        return { ok: true };
+    } catch (err) {
+        // First line only: the bindings error enumerates every path it tried, which is
+        // pages of noise in a status block. The rest is in the log if it is wanted.
+        return { ok: false, error: err instanceof Error ? err.message.split('\n')[0]!.trim() : String(err) };
+    }
+}
+
+function defaultNativeDepLoad(): void {
+    const require = createRequire(import.meta.url);
+    const Database = require('better-sqlite3') as new (p: string) => { close(): void };
+    const db = new Database(':memory:');
+    db.close();
+}
+
 export function isBrowserAvailable(): boolean {
     if (isFullMockMode()) return false;
     try {

package/src/infrastructure/file-lock-service.ts

@@ -694,12 +694,13 @@ export class FileLockService implements IService {
             const errnoError = error as NodeJS.ErrnoException;
             if (errnoError.code === 'EEXIST') {
               contentionCount++;
-              // When the contended lock becomes eligible for reclaim, if this tick can
-              // know it. Scoped per observation: a tick that could not read the lock
+              // Whether THIS tick judged the contended lock not-yet-eligible for the
+              // pid-less reclaim — i.e. we are waiting for a recovery we will be allowed
+              // to perform. Scoped per observation: a tick that could not read the lock
               // learned nothing, and an eligibility carried over from an earlier one is
               // no longer evidence of anything. See the stall check below for why the
               // stall bound must not fire before this moment.
-              let reclaimEligibleAt: number | null = null;
+              let awaitingReclaim = false;
               // Read lock content to verify ownership and liveness before considering stale
               try {
                 const rawContent = await fs.readFile(this.lockFilePath, 'utf-8');
@@ -720,17 +721,26 @@ export class FileLockService implements IService {
                 // A lock with no readable pid is judged purely on age (see
                 // _shouldReclaim), and its mtime never moves again — so it can never
                 // show progress and the stall bound is guaranteed to expire first.
-                // Record when it becomes reclaimable so the wait below can outlast the
-                // stall bound rather than abandoning the recovery at 20s.
+                // Mark this tick as awaiting that reclaim so the wait below can outlast
+                // the stall bound rather than abandoning the recovery at 20s.
+                //
+                // Judged from the SAME lockAge observation _shouldReclaim will use, not
+                // from a fresh Date.now() at the stall check: the two clocks disagreed
+                // for the few ms between the stat and that check, and a tick landing
+                // astride the window boundary judged the lock not-yet-reclaimable here
+                // yet no-longer-awaited there — giving up at the exact moment the
+                // window opened (ubuntu CI, 2026-08-24: rejected 10008ms into a
+                // 10000ms window). The complement of _shouldReclaim's strict > means
+                // one of the two branches now holds on every readable tick.
                 //
                 // Deliberately NOT extended to a live owner: there the heartbeat is the
                 // designed progress signal, its absence past lockTimeout is real evidence
                 // of a wedge, and reporting that to the caller promptly beats waiting out
                 // a two-to-four-minute live-owner threshold on a lock we may well never
                 // be handed.
-                reclaimEligibleAt = (parsed?.pid ?? null) === null
-                  ? stats.mtimeMs + this._unidentifiedStaleThreshold()
-                  : null;
+                awaitingReclaim = this.lockTimeout > 0
+                  && (parsed?.pid ?? null) === null
+                  && lockAge <= this._unidentifiedStaleThreshold();
 
                 if (lockUuid === this.lockUuid) {
                   // This is our own lock — a previous attempt was interrupted. Reclaim.
@@ -802,8 +812,6 @@ export class FileLockService implements IService {
               // on the spot rather than wait for anything, and the run semaphore's slot
               // files carry a TEN-MINUTE unidentified window, so honouring eligibility
               // there would turn "is this slot free right now" into a ten-minute block.
-              const awaitingReclaim =
-                this.lockTimeout > 0 && reclaimEligibleAt !== null && Date.now() < reclaimEligibleAt;
               if ((stalledFor >= this.lockTimeout && !awaitingReclaim) || waitedFor >= this.acquireCeilingMs) {
                 metrics.observe('state_lock_acquire_duration_ms', waitedFor, { status: 'timeout' });
                 metrics.increment('state_lock_acquire_total', 1, { status: 'timeout' });

package/src/skill-install/skill-installer.ts

@@ -325,6 +325,14 @@ export interface DetectedHarness extends HarnessDef {
   absSkillPath: string;
   /** Current install state of THIS skill at that path. */
   installed: 'none' | 'owned-symlink' | 'owned-copy' | 'foreign';
+  /**
+   * Ours, but not usable: the symlink dangles, or the directory it resolves to is
+   * missing SKILL.md / scripts/run.mjs. Reported because the alternative is what
+   * actually happened — `skill status` said "installed (symlink)" for a link whose
+   * target had been deleted, so the only signal the user got was the harness failing
+   * later with "Cannot find module …/scripts/run.mjs".
+   */
+  broken: boolean;
 }
 
 export function detectHarnesses(opts?: { home?: string }): DetectedHarness[] {
@@ -342,10 +350,28 @@ export function detectHarnesses(opts?: { home?: string }): DetectedHarness[] {
         else installed = 'foreign';
       }
     } catch { /* none */ }
-    return { ...h, present, absSkillsDir, absSkillPath, installed };
+    const broken = (installed === 'owned-symlink' || installed === 'owned-copy')
+      && !isUsableSkillDir(absSkillPath);
+    return { ...h, present, absSkillsDir, absSkillPath, installed, broken };
   });
 }
 
+/**
+ * The two files a skill directory is useless without: the manifest a harness reads to
+ * discover the skill, and the launcher it executes. A link or copy can exist while the
+ * thing it points at does not — the target was deleted, moved, or partially removed —
+ * and the harness then fails at invocation time with "Cannot find module …/run.mjs",
+ * which says nothing about the install being the problem. Checked rather than assumed
+ * so both `skill status` and the startup reconcile can tell a live install from a
+ * hollow one.
+ */
+function isUsableSkillDir(p: string): boolean {
+  try {
+    return fs.existsSync(path.join(p, 'SKILL.md'))
+        && fs.existsSync(path.join(p, 'scripts', 'run.mjs'));
+  } catch { return false; }
+}
+
 function isSymlinkPresent(p: string): boolean {
   try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; }
 }
@@ -695,12 +721,23 @@ export function reconcileSkillInstalls(opts: InstallOptions = {}): ReconcileResu
     // Only ever touch links we own; a foreign link at this path stays + tracked.
     if (!isOwnedSymlink(e.path)) { keep.push(e); continue; }
 
-    const targetLive = fs.existsSync(e.path); // existsSync follows the link
-    let dest: string | null = null;
-    try { dest = path.resolve(path.dirname(e.path), fs.readlinkSync(e.path)); } catch { /* unreadable */ }
-
-    const stale = source !== null && dest !== null && dest !== path.resolve(source);
-    if (!targetLive || stale) {
+    // A target that resolves but has been gutted (partial delete, interrupted
+    // install, pruned tree) is as dead as one that is gone — and it fails later,
+    // at invocation, with an error that never mentions the install. Treat both as
+    // needing repair.
+    const targetLive = fs.existsSync(e.path) && isUsableSkillDir(e.path); // existsSync follows the link
+
+    // A link pointing at a DIFFERENT but perfectly live pi-research install is left
+    // alone. Re-pointing it was a silent hijack: reconcile runs on every
+    // engine-touching CLI invocation, from whichever copy of the package is being
+    // invoked, so any second install captured the user's skill links just by being
+    // run once. docs/SDK.md tells users to `npm install @lincoln504/pi-research` INTO
+    // their project, so the second install is a documented, ordinary setup — and when
+    // that project was later moved or cleaned, the global skill died with an opaque
+    // "Cannot find module .../run.mjs". Self-healing only needs the dangling case
+    // (`!targetLive`), which is what an update that relocates the package produces;
+    // choosing between two live installs is what the explicit `skill install` is for.
+    if (!targetLive) {
       if (source !== null) {
         // Re-point to the current package source (handles update/reinstall).
         try {

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

@@ -6,7 +6,7 @@
 
 import { runWorkerSearch } from '../infrastructure/browser/task-execution-service.ts';
 import { getMaxWorkers, COLD_START_ALLOWANCE_MS } from '../infrastructure/browser/config.ts';
-import { isTaskTimeoutError } from '../infrastructure/browser/browser-error-utils.ts';
+import { isTaskTimeoutError, isNativeBindingError } from '../infrastructure/browser/browser-error-utils.ts';
 import { logger } from '../logger.ts';
 import { safeUnref } from '../utils/safe-unref.ts';
 import { normalizeUrl } from '../utils/url-utils.ts';
@@ -321,6 +321,24 @@ export async function performSearch(
             reason = `${timeoutCount} queries timed out and ${errorCount} queries failed`;
         }
 
+        // A missing native addon is a BROKEN INSTALL, and the generic advice below
+        // actively misleads: it sends the reader to check their network and their
+        // machine load when neither is involved and neither can be acted on. npm 12
+        // defaults `allowScripts` to off, so a plain install no longer builds
+        // camoufox-js's better-sqlite3 dependency and every browser worker dies
+        // identically. Say that instead, and say what fixes it.
+        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 — reinstall allowing them (npm install @lincoln504/pi-research ` +
+                `--allow-scripts, or npm approve-scripts --allow-scripts-pending), then retry.` +
+                (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : '')
+            );
+        }
+
         throw new Error(
             `Search completely failed: ${reason}. ` +
             `Browser workers may be unavailable, DuckDuckGo is unreachable, or the system is under extreme load.` +