@lincoln504/pi-research 1.6.6 → 1.6.8

package/README.md

@@ -44,21 +44,20 @@ npm install -g @lincoln504/pi-research
 pi-research skill install
 ```
 
-On npm ≥11.19 (and npm 12), dependency install scripts are skipped by default. This
-package needs none of them: better-sqlite3 13 ships prebuilt bindings for every
-supported platform inside its own tarball, and the stealth browser (~500MB)
-self-provisions on its first use instead of at install time — so the first scrape
-takes a few minutes. Nothing needs approving. (On older npm, which still runs
-scripts, a Windows machine without Visual Studio Build Tools can fail while npm
-needlessly recompiles better-sqlite3; upgrading npm fixes that too.)
+No extra setup is needed. The package uses no install scripts: it ships
+ready-made bindings for every platform, and the stealth browser (~500MB)
+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.
 
 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).
 
 ### How it works
 
-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.
+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:
+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:
 
 ![Prompt-driven multi-round research in the pi TUI](https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/02-prompt-research.gif)
 
@@ -73,7 +72,7 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 
 - **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 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.
+- **Read-only by design.** The research agent cannot run shell commands or write, edit, or delete anything, which is 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 range from a quick pass to a large-scale investigation.
 
 ### Requirements / limitations
@@ -82,6 +81,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.
+- Local knowledge-store embeddings need `@huggingface/transformers`, which is an **optional dependency**: if its native image chain (sharp) cannot install on your machine, npm skips it with a warning, the install still succeeds, and everything except local embeddings works. The store disables embeddings gracefully with a message telling you how to restore them.
 - 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.6", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.6.8", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli.mjs

@@ -4196,10 +4196,11 @@ function isNativeStackUnavailableError(err) {
   const msg2 = (err instanceof Error ? `${err.message} ${err.stack ?? ""}` : String(err)).toLowerCase();
   const code = typeof err === "object" && "code" in err ? String(err.code) : "";
   if (code === "ERR_DLOPEN_FAILED") return true;
-  if ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && (msg2.includes("onnxruntime") || msg2.includes("lancedb"))) {
+  if (code === "TRANSFORMERS_UNAVAILABLE") return true;
+  if ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && (msg2.includes("onnxruntime") || msg2.includes("lancedb") || msg2.includes("@huggingface/transformers"))) {
     return true;
   }
-  return msg2.includes("cannot find native binding") || msg2.includes("onnxruntime_binding.node") || /cannot find module '[^']*onnxruntime/.test(msg2) || /cannot find module '[^']*lancedb/.test(msg2) || msg2.includes("knowledgestoreservice is not a constructor");
+  return msg2.includes("cannot find native binding") || msg2.includes("onnxruntime_binding.node") || /cannot find module '[^']*onnxruntime/.test(msg2) || /cannot find module '[^']*lancedb/.test(msg2) || /cannot find (?:package|module) ['"]@huggingface[/\\]transformers['"]/i.test(msg2) || msg2.includes("knowledgestoreservice is not a constructor");
 }
 function getModelCacheDir() {
   const xdgCache = process.env["XDG_CACHE_HOME"];
@@ -4292,13 +4293,37 @@ var init_embedder_utils = __esm({
 });
 
 // src/knowledge/transformers-loader.ts
+function isTransformersMissingError(err) {
+  if (!err || typeof err !== "object") return false;
+  const code = "code" in err ? String(err.code) : "";
+  const msg2 = err instanceof Error ? err.message : String(err);
+  return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && /@huggingface[/\\]transformers/.test(msg2);
+}
+function transformersUnavailableError(cause) {
+  const err = new Error(
+    "Optional dependency '@huggingface/transformers' is not installed, so local embeddings are unavailable. npm skips this package when its native image chain cannot install (most often a failing sharp platform binary). The knowledge store runs without embeddings until it is present \u2014 reinstall this package to re-resolve its optional dependencies (pi install npm:@lincoln504/pi-research), or install it directly (npm install @huggingface/transformers).",
+    { cause }
+  );
+  err.code = TRANSFORMERS_UNAVAILABLE;
+  return err;
+}
 async function getTransformers() {
-  return _transformers ??= await import("@huggingface/transformers");
+  if (_transformers) return _transformers;
+  try {
+    _transformers = await import("@huggingface/transformers");
+  } catch (err) {
+    if (isTransformersMissingError(err)) {
+      throw transformersUnavailableError(err);
+    }
+    throw err;
+  }
+  return _transformers;
 }
-var _transformers;
+var TRANSFORMERS_UNAVAILABLE, _transformers;
 var init_transformers_loader = __esm({
   "src/knowledge/transformers-loader.ts"() {
     "use strict";
+    TRANSFORMERS_UNAVAILABLE = "TRANSFORMERS_UNAVAILABLE";
   }
 });
 

package/docs/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.8] - 2026-08-31
+
+### Changed
+
+- README npm install note rewritten for clarity (no behavior or claim changes): the three tangled topics (script skipping on npm ≥11.19, better-sqlite3's bundled prebuilds, the browser's first-use download) are now three plain sentences with an explicit do and don't, and the em dashes are gone. This is the README the package site renders, so the entry exists to timestamp that refresh.
+
+## [1.6.7] - 2026-08-31
+
+Two threads from the issue tracker collide here: #10 ("Installation via NPM fails")
+turned out to be an install-time sharp build failure we could — and now did — design
+away, while the skew guard shipped across 1.5.x–1.6.6 rested on a premise about pi's
+module loading that is not how pi works.
+
+### Fixed
+
+- **`pi install` no longer fails outright on machines where sharp's native image chain cannot install (#10).** The failure chain, reproduced and pinned: `@huggingface/transformers` (the local-embeddings backend) declared sharp `^0.34.5` as a regular dependency; when npm skipped sharp's platform binary (`@img/sharp-*` optionals — the npm/cli#4828 pruning family on existing trees for npm 10.3.0–11.2.x, or any interrupted install, which the re-resolve then will NOT heal because skipped optionals stay inert), sharp's install script fell back to a source build that itself is broken (node-addon-api is only a devDependency), and the whole install died with `npm error code 1` — the extension never arrived. `@huggingface/transformers` is now an **optional dependency** (the same pattern `@lancedb/lancedb` already uses for it): npm drops a failing optional subtree with a warning and the install succeeds; research, scraping, and the CLI all work without embeddings. The absence is a first-class state at runtime too: `getTransformers()` reclassifies the missing-module rejection as a typed `TRANSFORMERS_UNAVAILABLE` error carrying remediation (`src/knowledge/transformers-loader.ts`), `isNativeStackUnavailableError()` recognizes it (`src/knowledge/embedder-utils.ts`), and the knowledge store therefore memoizes DISABLED on first touch instead of re-running the full init + 5-attempt backoff storm (~15s) on every store use. A transformers-INTERNAL failure (its own onnxruntime import, a corrupt install) still routes through the pre-existing onnxruntime/lancedb arms — a broken install of a PRESENT package is not "the optional was skipped". Retry storms, probe behavior, and startup were verified: the WebGPU probe subprocess already treats a missing module as "no WebGPU" and is unreachable before the env init anyway.
+
+### Removed
+
+- **The pi-ai/pi-coding-agent "skew guard" is gone** (`src/core/pi-ai-skew.ts`; shipped in 1.6.5 as fail-fast, reworked in 1.6.6 to walk node_modules ancestors). The premise does not survive contact with pi's loader: pi resolves EVERY `@earendil-works/*` and `typebox` specifier in extension code to the HOST's own copies via jiti `virtualModules`/`alias` (verified in the 0.84.2 and 0.84.4 loader source — coverage includes the exact four specifiers this package imports), so the on-disk copies the guard compared are never loaded in-host. Under the host the guard measured dependencies nobody executes; its FATAL 'stale' refusal would have blocked a healthy extension after every host upgrade the moment the managed tree's inert copies lagged — and the 1.6.6 ancestor-walk made that state reachable on the primary `pi install npm:` layout (pi's own install code uses `--legacy-peer-deps` precisely because it expects extensions to declare these packages as peers, not dependencies). Host-version compatibility stays where it belongs: `checkPiCompatibility()` against the running host's VERSION — refuse below the 0.84.0 floor, warn once above the tested line — which is now the only startup check. The standalone CLI/SDK never ran the guard (it lived solely in the extension entry), so removal changes nothing there. What actually caused the original 2026-08-30 named-export crash remains unproven — in-host specifier mixing should have been impossible under 0.84.2's alias table — and is recorded here honestly rather than preserved as a false safety net.
+
+### Verified
+
+- 2993 unit tests over 236 files (11 new: the transformers-absent typed error and its classification — ESM and CJS not-found forms, transformers-internal failures passing through untouched, unrelated-package precision, and the DISABLED-memoization handoff to `isNativeStackUnavailableError`), plus lint, all four type-checks (TS6 and TS7 native, src and tests), dependency-cruiser, the audit gate, the full integration suite (57 passed / 8 skipped parallel, 103 serial), and the tarball manifest gate (235 files — one fewer with the deleted guard module). CLI boot verified end-to-end with the entire transformers/sharp/@img subtree physically absent from the install tree.
+
 ## [1.6.6] - 2026-08-31
 
 Issue #9 reported deep-research runs stalling for minutes inside planning salvage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
@@ -117,7 +117,6 @@
     "@earendil-works/pi-ai": ">=0.84.0 <1",
     "@earendil-works/pi-coding-agent": ">=0.84.0 <1",
     "@earendil-works/pi-tui": ">=0.84.0 <1",
-    "@huggingface/transformers": "4.2.0",
     "@kreuzberg/html-to-markdown-node": "^3.7.2",
     "@lancedb/lancedb": "0.37.1",
     "apache-arrow": "21.1.0",
@@ -135,6 +134,7 @@
     "youtubei.js": "^18.0.0"
   },
   "optionalDependencies": {
+    "@huggingface/transformers": "4.2.0",
     "webgpu": "^0.4.0"
   },
   "overrides": {

package/src/index.ts

@@ -12,7 +12,6 @@ import { createResearchTool, createHealthTool } from './tool.ts';
 import { createResearchKnowledgeSearchTool } from './tools/research-knowledge-search.ts';
 import { logger } from './logger.ts';
 import { checkPiCompatibility } from './core/pi-version.ts';
-import { checkPiAiSkew } from './core/pi-ai-skew.ts';
 import { randomUUID } from 'node:crypto';
 import { shutdownManager } from './utils/shutdown-manager.ts';
 import { healthRegistry } from './healthcheck/index.ts';
@@ -102,11 +101,14 @@ export default async function (pi: ExtensionAPI) {
   // host auto-building its ModelRuntime. This in-host check is the real
   // enforcement point: when running as an extension the host's version is NOT
   // constrained by npm's resolution of our own package.json range.
-  // Two thresholds, not one — see src/core/pi-version.ts. Below the floor the APIs
-  // we call do not exist, so we refuse. Above the last TESTED line we warn and
-  // continue: pi is pre-1.0, a minor bump can break anything under semver (0.83.0
-  // already extended the ResourceLoader contract), and our own dependency range
-  // cannot constrain the host at all when running as an extension.
+  //
+  // This is the ONLY version check at startup, and it needs to be: pi's extension
+  // loader aliases every @earendil-works/* and typebox specifier to the HOST's own
+  // copies (virtualModules/alias in the loader), so the copies in our install tree
+  // are never loaded in-host and comparing them against the host version — as the
+  // 1.5.x–1.6.6 skew guard did — measures dependencies nobody executes. The 1.6.6
+  // form of that guard false-fataled healthy installs after every host upgrade and
+  // was removed; see docs/CHANGELOG.md [1.6.7].
   const compat = checkPiCompatibility(PI_VERSION);
   if (compat.fatal) {
     throw new Error(compat.message ?? `[pi-research] Unsupported pi-coding-agent version "${PI_VERSION}".`);
@@ -115,19 +117,6 @@ export default async function (pi: ExtensionAPI) {
     logger.warn(compat.message);
   }
 
-  // The gate above classifies the HOST version but cannot see the copies THIS
-  // extension resolves from its own node_modules — the 2026-08-30 incident
-  // (host 0.84.4 vs extension-resolved pi-ai 0.84.2) passed it as 'ok' while
-  // every researcher died at provider load. Detect that skew here and refuse
-  // to start with the actual remediation instead.
-  const skew = checkPiAiSkew();
-  if (skew.fatal) {
-    throw new Error(skew.message ?? '[pi-research] pi-ai version skew.');
-  }
-  if (skew.message) {
-    logger.warn(skew.message);
-  }
-
   // Re-register the beforeExit safety net (deactivate() strips event listeners during reload).
   // This ensures the ONNX pipeline is disposed even after extension reloads.
   registerBeforeExitSafetyNet();

package/src/knowledge/embedder-utils.ts

@@ -73,6 +73,9 @@ export function isEmbedderUnreachable(err: unknown): boolean {
  * Matched signatures (observed in the wild):
  *   - onnxruntime-node:  "Cannot find module '.../bin/napi-v6/darwin/x64/onnxruntime_binding.node'"
  *   - @lancedb/lancedb:  "Cannot find native binding. npm has a bug related to optional dependencies"
+ *   - @huggingface/transformers (optional dep skipped at install time, #10): the typed
+ *                        TRANSFORMERS_UNAVAILABLE error from transformers-loader.ts, or its
+ *                        raw form "Cannot find package '@huggingface/transformers'"
  *   - jiti-masked module-eval failure of the above surfaces as:
  *                        "KnowledgeStoreService is not a constructor"
  */
@@ -89,8 +92,10 @@ export function isNativeStackUnavailableError(err: unknown): boolean {
   // `err` is already known truthy (guarded above), so no `err &&` here.
   const code = (typeof err === 'object' && 'code' in err) ? String((err as { code?: unknown }).code) : '';
   if (code === 'ERR_DLOPEN_FAILED') return true;
+  // The typed error from transformers-loader.ts — unambiguous by construction.
+  if (code === 'TRANSFORMERS_UNAVAILABLE') return true;
   if ((code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') &&
-      (msg.includes('onnxruntime') || msg.includes('lancedb'))) {
+      (msg.includes('onnxruntime') || msg.includes('lancedb') || msg.includes('@huggingface/transformers'))) {
     return true;
   }
 
@@ -99,6 +104,7 @@ export function isNativeStackUnavailableError(err: unknown): boolean {
     msg.includes('onnxruntime_binding.node') ||
     /cannot find module '[^']*onnxruntime/.test(msg) ||
     /cannot find module '[^']*lancedb/.test(msg) ||
+    /cannot find (?:package|module) ['"]@huggingface[/\\]transformers['"]/i.test(msg) ||
     msg.includes('knowledgestoreservice is not a constructor')
   );
 }

package/src/knowledge/transformers-loader.ts

@@ -18,14 +18,71 @@
  * (isNativeStackUnavailableError) and degrades the store to DISABLED. Help, version,
  * status, and browser-only research then work with no binding present.
  *
+ * The package itself is an OPTIONAL dependency (it can be skipped entirely at
+ * install time when its native chain cannot build — sharp's platform binary is
+ * the historic offender, #10). A genuinely absent module is therefore a SUPPORTED
+ * state, not a crash: getTransformers() reclassifies it as a typed
+ * TRANSFORMERS_UNAVAILABLE error carrying remediation, which the knowledge store's
+ * native-unavailable classifier memoizes as DISABLED instead of re-running the
+ * init + backoff storm on every store touch. A transformers-INTERNAL load failure
+ * (its own onnxruntime import, a corrupt install) is re-thrown untouched — that is
+ * the pre-existing native-stack classification's job.
+ *
  * Modules that need transformers *types* should keep `import type { … } from
  * '@huggingface/transformers'` (type imports are erased and never hoisted); only
  * runtime value access (pipeline, env, …) must go through getTransformers().
  */
 
+/** Error.code on the typed error thrown when the optional module is not installed. */
+export const TRANSFORMERS_UNAVAILABLE = 'TRANSFORMERS_UNAVAILABLE';
+
+/**
+ * True when `err` is Node's "the module itself is not installed" rejection for
+ * OUR specifier — i.e. the optional dependency was skipped at install time.
+ * Deliberately narrow: a transformers-INTERNAL missing module (onnxruntime
+ * binding, corrupt install) resolves to a DIFFERENT file path and must stay
+ * unclassified here so the native-stack classifier handles it instead.
+ */
+export function isTransformersMissingError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const code = 'code' in err ? String((err as { code?: unknown }).code) : '';
+  const msg = err instanceof Error ? err.message : String(err);
+  // Node's ESM form is "Cannot find package '@huggingface/transformers' imported
+  // from …"; the CJS/child-process form is "Cannot find module '…'".
+  return (
+    code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND'
+  ) && /@huggingface[/\\]transformers/.test(msg);
+}
+
+/**
+ * Build the typed, remediation-carrying error for an absent optional package.
+ * Exported for tests; the code is what isNativeStackUnavailableError() keys on.
+ */
+export function transformersUnavailableError(cause: unknown): Error {
+  const err = new Error(
+    "Optional dependency '@huggingface/transformers' is not installed, so local embeddings are unavailable. "
+    + 'npm skips this package when its native image chain cannot install (most often a failing sharp platform binary). '
+    + 'The knowledge store runs without embeddings until it is present — reinstall this package to re-resolve its '
+    + 'optional dependencies (pi install npm:@lincoln504/pi-research), or install it directly '
+    + '(npm install @huggingface/transformers).',
+    { cause },
+  );
+  (err as { code?: string }).code = TRANSFORMERS_UNAVAILABLE;
+  return err;
+}
+
 let _transformers: typeof import('@huggingface/transformers') | undefined;
 
 /** Resolve the transformers module, memoizing after the first load. */
 export async function getTransformers(): Promise<typeof import('@huggingface/transformers')> {
-  return (_transformers ??= await import('@huggingface/transformers'));
+  if (_transformers) return _transformers;
+  try {
+    _transformers = await import('@huggingface/transformers');
+  } catch (err) {
+    if (isTransformersMissingError(err)) {
+      throw transformersUnavailableError(err);
+    }
+    throw err;
+  }
+  return _transformers;
 }

package/src/core/pi-ai-skew.ts

@@ -1,351 +0,0 @@
-/**
- * pi-ai module-graph skew detection.
- *
- * The version gate in pi-version.ts classifies the HOST pi-coding-agent
- * version against our supported window — but it cannot see the failure that
- * actually took pi-research down on 2026-08-30: as an extension we resolve
- * `@earendil-works/*` from our OWN node_modules, and when those copies lag the
- * host (host 0.84.4, extension-resolved pi-ai 0.84.2), newer host-era modules
- * and older extension-era modules meet in one process graph. The visible
- * symptom was researchers dying at provider load with
- * "The requested module './simple-options.js' does not provide an export named
- * 'clampThinkingBudgetToAnswerRoom'" (first exported in pi-ai 0.84.3), with
- * the knowledge store's triage/extraction LLM calls failing the same way —
- * every LLM path, wrapped as unrelated-looking "Provider error" strings.
- *
- * Neither npm nor pi enforces agreement here: our declared range
- * (">=0.84.0 <1") cannot constrain the host, and a dev-symlinked or
- * prefix-installed extension keeps whatever node_modules it was installed
- * with while the host updates independently. The only enforcement point is
- * in-process, at load — this module.
- *
- * Detection is deliberately filesystem-based rather than module-resolution-
- * based: the @earendil-works packages' exports maps are import-only, so
- * `createRequire(...).resolve()` fails with ERR_PACKAGE_PATH_NOT_EXPORTED,
- * and resolution would find the same (possibly stale) copy either way. Instead
- * we walk directories to package.json files directly, reproducing the node_modules
- * walk Node's bare-specifier resolution performs:
- *
- *   - EXTENSION side: from this module's own directory, walk ancestors and at
- *     each level read node_modules/@earendil-works/{pi-ai,pi-coding-agent}/package.json;
- *     the FIRST hit is the copy our bare imports actually bind. The package's own
- *     node_modules wins when present (git installs clone + `npm install` inside the
- *     checkout; the dev repo has its own), but on the PRIMARY layout — `pi install
- *     npm:` — pi runs one flat managed npm tree at ~/.pi/agent/npm/ where the
- *     extension sits at node_modules/@lincoln504/pi-research with NO nested copies
- *     (measured) and its @earendil-works deps hoist to the managed root. A
- *     nested-only lookup misses those entirely and would false-warn "missing" on
- *     every healthy startup — so the walk must continue past the package root,
- *     exactly like Node's does. The package root (nearest package.json) is still
- *     recorded as the remedy target for genuinely-broken installs.
- *   - HOST side: from the process entry script (process.argv[1], realpath'd —
- *     Node resolves the main entry by default, so an nvm bin symlink anchors
- *     inside the host package) up to the package.json whose name IS
- *     '@earendil-works/pi-coding-agent', then its nested pi-ai. In a pi run
- *     that is the host's own tree; standalone (our CLI/SDK, tests) the walk
- *     finds no such package and the check no-ops rather than guessing.
- *
- * The comparison relies on the pi monorepo's lockstep versioning — every
- * observed release ships pi-coding-agent and pi-ai (and the other
- * @earendil-works/* packages) at the same version — so a mismatch against
- * the host's pi-coding-agent version is a reliable skew signal for pi-ai too.
- * A STALE extension copy (older than the host) is FATAL: that is the proven
- * crash direction. A NEWER extension copy only warns: untested, but no known
- * failure mode. Internal disagreement between the extension's own pi-ai and
- * pi-coding-agent warns as well — a half-updated node_modules.
- */
-
-import { readFileSync, realpathSync } from 'node:fs';
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { compareVersions, parsePiVersion } from './pi-version.ts';
-
-/** Minimal package.json shape this module reads. */
-interface PkgJson {
-  name?: string;
-  version?: string;
-}
-
-function readPkgJson(file: string): PkgJson | null {
-  try {
-    return JSON.parse(readFileSync(file, 'utf8')) as PkgJson;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Walk up from `startFile` to the nearest package.json.
- * When `name` is given, keep walking past non-matching package.json files
- * (scoped packages nest: pi-coding-agent/dist/bundle/cli.js must climb three
- * levels) and stop at the first match; returns null when never found.
- */
-function findPackageRoot(startFile: string, name?: string): { dir: string; pkg: PkgJson } | null {
-  let dir = path.dirname(path.resolve(startFile));
-  for (let i = 0; i < 16; i++) {
-    const pkg = readPkgJson(path.join(dir, 'package.json'));
-    if (pkg && (name === undefined || pkg.name === name)) {
-      return { dir, pkg };
-    }
-    const up = path.dirname(dir);
-    if (up === dir) return null;
-    dir = up;
-  }
-  return null;
-}
-
-/** A resolved @earendil-works copy: its version and the install root that provided it. */
-export interface ResolvedSdkCopy {
-  version: string;
-  /** The directory whose node_modules produced this copy — the `cd` target for the install remedy. */
-  installRoot: string;
-}
-
-/**
- * Resolve `@earendil-works/<pkg>` from `startDir` exactly as Node's bare-specifier
- * resolution binds it: walk ancestors, and at each level take the FIRST
- * `<dir>/node_modules/@earendil-works/<pkg>/package.json` found. Covers the nested
- * copies of a git checkout, the dev repo's own node_modules, and — critically — the
- * flat managed tree `pi install npm:` produces, where the copies hoist to the
- * managed root ABOVE the package and a nested-only lookup would miss them.
- */
-function resolveSdkCopy(startDir: string, pkg: string): ResolvedSdkCopy | null {
-  let dir = path.resolve(startDir);
-  for (let i = 0; i < 32; i++) {
-    const pkgDir = path.join(dir, 'node_modules', '@earendil-works', pkg);
-    const p = readPkgJson(path.join(pkgDir, 'package.json'));
-    if (p?.version) return { version: p.version, installRoot: dir };
-    const up = path.dirname(dir);
-    if (up === dir) return null;
-    dir = up;
-  }
-  return null;
-}
-
-export interface PiAiSkewInput {
-  /** Host pi-coding-agent version (its package.json), or null when not running under pi. */
-  hostVersion: string | null;
-  /** Extension-resolved pi-ai version, or null when our node_modules lacks it. */
-  extPiAi: string | null;
-  /** Extension-resolved pi-coding-agent version, or null. */
-  extPiCodingAgent: string | null;
-  /** Where the pi-ai copy resolved FROM (the install root whose node_modules has it).
-   *  Lets the remedy `cd` into the tree that actually owns a stale copy — the flat
-   *  managed tree of `pi install npm:`, not the package dir. Falls back to extRoot. */
-  piAiRoot?: string;
-  /** Same, for the pi-coding-agent copy. */
-  piCodingAgentRoot?: string;
-}
-
-export type PiAiSkewLevel = 'ok' | 'standalone' | 'incomplete' | 'stale' | 'newer' | 'internal';
-
-export interface PiAiSkewResult {
-  level: PiAiSkewLevel;
-  /** True when the extension must refuse to start (proven crash direction). */
-  fatal: boolean;
-  message: string | null;
-}
-
-/**
- * Classify a skew state. Pure — no filesystem access — so the policy is
- * testable without fixtures, mirroring checkPiCompatibility's design.
- */
-export function classifyPiAiSkew(input: PiAiSkewInput, extRoot?: string): PiAiSkewResult {
-  const { hostVersion, extPiAi, extPiCodingAgent } = input;
-
-  // Standalone CLI/SDK/tests: no host pi package above us — nothing to skew
-  // against; our own imports are the only copies in play.
-  if (!hostVersion) {
-    return { level: 'standalone', fatal: false, message: null };
-  }
-
-  // The remedy must `cd` into the tree that OWNS the copy being replaced: the
-  // package's own checkout when the copy resolved nested there, or — on the flat
-  // `pi install npm:` managed tree — the managed root its deps hoisted to.
-  const fixRootOf = (copyRoot: string | undefined) => copyRoot ?? extRoot;
-  const remedyFor = (copyRoot: string | undefined) => {
-    const root = fixRootOf(copyRoot);
-    return root
-      ? `Fix: cd ${root} && npm install (align this install's @earendil-works copies with host pi ${hostVersion}), then reload pi.`
-      : `Fix: reinstall this extension so its node_modules matches host pi ${hostVersion}, then reload pi.`;
-  };
-  // Default remedy when no specific copy is implicated (absent-copy warns).
-  const remedy = remedyFor(undefined);
-
-  if (!extPiAi || !extPiCodingAgent) {
-    // A PRESENT copy that already lags the host is the proven crash direction
-    // even in a half-hoisted layout (the 2026-08-30 failure had exactly this
-    // shape: stale nested pi-ai beside a hoisted pi-coding-agent) — classify it
-    // stale/fatal, not the softer incomplete warn. Only a genuinely-absent
-    // copy (nothing to compare) stays warn.
-    const presentVersion = extPiAi ?? extPiCodingAgent;
-    const presentPkg = extPiAi ? 'pi-ai' : 'pi-coding-agent';
-    const present = presentVersion ? parsePiVersion(presentVersion) : null;
-    const host = parsePiVersion(hostVersion);
-    if (present && host && compareVersions(present, host) < 0) {
-      const presentRemedy = remedyFor(extPiAi ? input.piAiRoot : input.piCodingAgentRoot);
-      return {
-        level: 'stale',
-        fatal: true,
-        message:
-          `[pi-research] Extension node_modules has @earendil-works/${presentPkg} ${presentVersion}, which LAGS host pi ${hostVersion} ` +
-          `(${extPiAi ? 'pi-coding-agent' : 'pi-ai'} is not resolvable here to compare against) — a copy lagging the host crashes every LLM call at provider load ` +
-          `(ESM export errors like the missing 'clampThinkingBudgetToAnswerRoom' of pi-ai 0.84.2-vs-0.84.3+). ${presentRemedy}`,
-      };
-    }
-    return {
-      level: 'incomplete',
-      fatal: false,
-      message:
-        `[pi-research] This extension cannot resolve @earendil-works/` +
-        `${!extPiAi ? 'pi-ai' : 'pi-coding-agent'} from its install location (walked node_modules up the tree) — LLM calls may fail at module load. ${remedy}`,
-    };
-  }
-
-  const host = parsePiVersion(hostVersion);
-  const ai = parsePiVersion(extPiAi);
-  const ca = parsePiVersion(extPiCodingAgent);
-  if (!host || !ai || !ca) {
-    // Unparseable versions: warn, never brick — this guard exists to make
-    // failures LOUD, not to invent new startup failures.
-    return {
-      level: 'incomplete',
-      fatal: false,
-      message: `[pi-research] Could not parse pi-ai skew versions (host=${hostVersion}, pi-ai=${extPiAi}, pi-coding-agent=${extPiCodingAgent}); skipping skew check.`,
-    };
-  }
-
-  const aiOlder = compareVersions(ai, host) < 0;
-  const caOlder = compareVersions(ca, host) < 0;
-
-  // Internal disagreement (a half-updated node_modules) is the root state and
-  // the more precise diagnosis, so it is classified BEFORE the direction
-  // checks — otherwise it is unreachable (ai !== ca implies one of them
-  // differs from the host). Severity still follows the proven crash
-  // direction: fatal when either copy lags the host.
-  if (compareVersions(ai, ca) !== 0) {
-    const anyOlder = aiOlder || caOlder;
-    const base =
-      `[pi-research] Extension node_modules is internally inconsistent (pi-ai ${extPiAi} vs ` +
-      `pi-coding-agent ${extPiCodingAgent}) — a half-updated install against host pi ${hostVersion}. `;
-    // Aim the remedy at the tree owning the LAGGING copy — that is the one to update.
-    const laggingRemedy = remedyFor(aiOlder ? input.piAiRoot : input.piCodingAgentRoot);
-    if (anyOlder) {
-      return {
-        level: 'internal',
-        fatal: true,
-        message:
-          base +
-          `A copy lagging the host crashes every LLM call at provider load ` +
-          `(ESM export errors like the missing 'clampThinkingBudgetToAnswerRoom' ` +
-          `of pi-ai 0.84.2-vs-0.84.3+). ${laggingRemedy}`,
-      };
-    }
-    return {
-      level: 'internal',
-      fatal: false,
-      message: base + `Untested direction — if LLM calls fail at module load, this is the first suspect. ${remedy}`,
-    };
-  }
-
-  if (aiOlder || caOlder) {
-    // The 2026-08-30 incident: host 0.84.4 + extension pi-ai 0.84.2. Newer
-    // host-era modules import symbols the stale copies never exported, and
-    // every researcher/knowledge LLM call dies at provider load with a
-    // confusing ESM named-export error. Refusing to start with THIS message
-    // is strictly better than five silent researcher deaths.
-    const staleRemedy = remedyFor(aiOlder ? input.piAiRoot : input.piCodingAgentRoot);
-    return {
-      level: 'stale',
-      fatal: true,
-      message:
-        `[pi-research] Fatal version skew: host pi ${hostVersion} but this extension resolves ` +
-        `pi-ai ${extPiAi} / pi-coding-agent ${extPiCodingAgent}. Mixed-version module graphs crash ` +
-        `every LLM call at provider load (ESM export errors like the missing ` +
-        `'clampThinkingBudgetToAnswerRoom' of pi-ai 0.84.2-vs-0.84.3+). ${staleRemedy}`,
-    };
-  }
-
-  const aiNewer = compareVersions(ai, host) > 0;
-  const caNewer = compareVersions(ca, host) > 0;
-  if (aiNewer || caNewer) {
-    return {
-      level: 'newer',
-      fatal: false,
-      message:
-        `[pi-research] Extension resolves pi-ai ${extPiAi} / pi-coding-agent ${extPiCodingAgent}, ` +
-        `newer than host pi ${hostVersion}. Untested direction — if LLM calls fail at module load, ` +
-        `this mismatch is the first suspect. ${remedy}`,
-    };
-  }
-
-  return { level: 'ok', fatal: false, message: null };
-}
-
-/**
- * Extension-side resolution, exported for fixture tests: resolves both SDK copies
- * from `fromFile`'s location the way Node would bind them, plus the package root
- * (the remedy target of last resort for genuinely-broken installs).
- */
-export interface ExtensionCopies {
-  extRoot: string | null;
-  piAi: string | null;
-  piCodingAgent: string | null;
-  piAiRoot: string | null;
-  piCodingAgentRoot: string | null;
-}
-
-export function resolveExtensionCopies(fromFile: string): ExtensionCopies {
-  // jiti hands us a file:// URL; real-path strings also accepted.
-  const anchor = fromFile.startsWith('file:') ? fileURLToPath(fromFile) : fromFile;
-  const ext = findPackageRoot(anchor);
-  // Walk from the MODULE's directory (not the package root): Node checks
-  // <dir>/node_modules at every ancestor of the importing file, so the package's
-  // own node_modules is covered AND the walk continues past it into whatever
-  // install root the package lives in — the flat managed tree `pi install npm:`
-  // produces, a project's hoisted tree, or the monorepo root.
-  const startDir = path.dirname(path.resolve(anchor));
-  const ai = resolveSdkCopy(startDir, 'pi-ai');
-  const ca = resolveSdkCopy(startDir, 'pi-coding-agent');
-  return {
-    extRoot: ext?.dir ?? null,
-    piAi: ai?.version ?? null,
-    piCodingAgent: ca?.version ?? null,
-    piAiRoot: ai?.installRoot ?? null,
-    piCodingAgentRoot: ca?.installRoot ?? null,
-  };
-}
-
-/**
- * Collect the real skew state from this process and classify it.
- *
- * Never throws: any read/walk failure degrades to null inputs (classified as
- * 'standalone'/'incomplete'), because a broken guard must not take the
- * extension down with it.
- */
-export function checkPiAiSkew(fromFile: string = import.meta.url): PiAiSkewResult {
-  const copies = resolveExtensionCopies(fromFile);
-
-  // Host side: the process entry script, realpath'd. In a pi run this anchors
-  // inside the host's own package; anywhere else the named walk finds nothing.
-  let hostVersion: string | null = null;
-  try {
-    const entry = realpathSync(process.argv[1] ?? '');
-    const host = findPackageRoot(entry, '@earendil-works/pi-coding-agent');
-    hostVersion = host?.pkg.version ?? null;
-  } catch {
-    // Entry missing/unreadable (standalone context) — hostVersion stays null
-    // and classifyPiAiSkew treats the host side as undetectable.
-  }
-
-  return classifyPiAiSkew(
-    {
-      hostVersion,
-      extPiAi: copies.piAi,
-      extPiCodingAgent: copies.piCodingAgent,
-      piAiRoot: copies.piAiRoot ?? undefined,
-      piCodingAgentRoot: copies.piCodingAgentRoot ?? undefined,
-    },
-    copies.extRoot ?? undefined,
-  );
-}