@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/rules/ast-grep-rules/rules/redundant-unsafe-function.yml

@@ -9,6 +9,31 @@ note: |
   the `unsafe` keyword should be removed) or it is misplaced (an unsafe
   operation lives outside an `unsafe { … }` block and should be wrapped).
   Either case warrants review.
+
+  Exempt when a `/// # Safety` doc-comment section precedes the function:
+  Rust's own convention (rustdoc's `missing_safety_doc` lint, and
+  clippy's `undocumented_unsafe_blocks`) is that an `unsafe fn` states
+  its caller obligations in a `# Safety` doc section instead of wrapping
+  its whole body in a redundant `unsafe { ... }` block — the function
+  signature IS the unsafe boundary, the doc section is where the
+  contract lives.
+
+  2026-08-20 (review round, refs #1806): the first ship of this valve
+  used `follows: {stopBy: end, kind: line_comment, regex: '#\s*Safety'}`,
+  copying the `SAFETY:`-comment shape from `no-chained-type-assertions`
+  too literally. `stopBy: end` scans EVERY preceding sibling all the way
+  to the top of the file — one `# Safety` comment ANYWHERE earlier
+  (a stray file-top note, or a doc block that belongs to a DIFFERENT,
+  earlier function) exempted every `unsafe fn` after it. Probe: a
+  documented function followed by two undocumented ones scored 0 hits;
+  the two alone scored 2. Fixed by bounding the backward scan with
+  `stopBy: {not: {kind: line_comment}}` — it stops at the first
+  non-comment sibling, so only the CONTIGUOUS run of `///`/`//` lines
+  directly above the function is searched, never an earlier function's
+  doc block or an unrelated comment further up the file. (This valve
+  shipped with zero corpus hits either side in the original PR —
+  corpus silence isn't proof of correctness; the fixtures below are
+  the whole evidence, deliberately adversarial.)
 rule:
   all:
     - kind: function_item
@@ -19,3 +44,10 @@ rule:
         has:
           kind: unsafe_block
           stopBy: end
+    - not:
+        follows:
+          stopBy:
+            not:
+              kind: line_comment
+          kind: line_comment
+          regex: '#\s*Safety'

package/node_modules/pi-lens/rules/ast-grep-rules/rules/require-safety-comment-for-as-unknown-as.yml

@@ -0,0 +1,184 @@
+id: require-safety-comment-for-as-unknown-as
+language: TypeScript
+severity: error
+metadata:
+  category: pi-lens-self-scan
+message: "'x as unknown as T' with no nearby SAFETY: comment — state the invariant TypeScript can't check"
+note: |
+  Narrowed port of dmmulroy/anti-slop's
+  `require-safety-comment-for-type-assertion`
+  (src/rules/require-safety-comment-for-type-assertion.ts, MIT).
+  Upstream requires a `SAFETY:` comment before EVERY non-const type
+  assertion (`as`/angle-bracket), walking up through statement-owner
+  node kinds looking for a preceding comment. This port narrows the
+  target to `x as unknown as T` specifically — the two-hop cast through
+  `unknown`. The 2026-08-19 audit found 2,180 non-const assertions
+  repo-wide and ZERO `SAFETY:` comments; requiring one on every
+  assertion would mean authoring ~1,750 comments in one PR. `as unknown
+  as` is the form that actually launders evidence (routes through the
+  top type rather than a single verifiable hop), and it is the exact
+  shape AGENTS.md's defect shape 13 already asks for in prose: "when a
+  call site hands the policy an outcome it did NOT derive... justify it
+  in a comment at the call site." This rule makes that convention
+  checkable for its most evidence-destroying form.
+
+  2026-08-20 (refs #1727, #1777): promoted `hint` -> `error`. `error` is
+  the only tier that maps to semantic `blocking`
+  (`clients/dispatch/runners/ast-grep-napi.ts`), so AGENTS.md's severity
+  policy requires a documented zero-false-positive audit here. Two
+  changes make that audit come out clean.
+
+  1. STRUCTURAL SCOPING: test paths are excluded (`ignores:` below). In a
+     test, `x as unknown as T` is almost always a partial test double —
+     reaching into a private field or stubbing the two methods of a
+     surface the subject actually calls. The "invariant TypeScript can't
+     check" there is "this stub covers what the code under test touches",
+     which is the test's own subject matter, not a hidden runtime claim.
+     Four-corpus census (2026-08-20) confirms the shape concentrates in
+     test paths rather than assuming it:
+
+     | corpus | total | test-path | non-test | suppressed |
+     |---|---:|---:|---:|---:|
+     | pi-lens (`clients/`+`tests/`) | 305 | 289 | 16 | 95% |
+     | pi core (`packages/`) | 182 | 155 | 27 | 85% |
+     | opencode (`packages/`) | 194 | 154 | 40 | 79% |
+     | oh-my-pi (`packages/`) | 1803 | 1644 | 159 | 91% |
+
+     This is a FALSE-NEGATIVE bias, deliberately, and it is not small:
+     289 uncommented `as unknown as` sites in pi-lens's own `tests/`
+     now raise NO diagnostic at all, where each previously raised an
+     `error` through `no-chained-type-assertions.yml`'s `unknown` arm.
+     The same trade costs 1,644 sites on oh-my-pi. It is a path glob,
+     not a semantic check — ast-grep cannot verify a cast is really a
+     test double, only that it lives under a test path.
+
+  2. REPO-SIDE REMEDIATION: the 16 remaining `clients/` sites were read
+     individually and each was given a truthful `SAFETY:` comment
+     naming the specific invariant (an optional Node API absent from
+     `@types/node`, a two-phase-init field filled before first read, a
+     `Object.fromEntries` key-type loss, a process-global stash). None
+     was a comment written to silence the rule; where the cast had no
+     justification it was replaced instead
+     (`clients/runtime-context.ts`).
+
+  Post-narrowing census on pi-lens: 0 findings over `clients/` +
+  `tests/`. The rule is tagged `metadata.category: pi-lens-self-scan`,
+  so CI's `npm run astgrep:self-scan` lane keeps it at zero.
+
+  Placement contract: a `SAFETY:` comment may directly precede the cast,
+  its enclosing statement, or an object-literal member (`pair`) containing
+  the cast. Array elements and call arguments are also supported through the
+  direct-cast arm when the comment is immediately above the cast expression.
+  JSX attributes, class static blocks, and switch cases are not comment
+  anchors for this valve; place those comments on the enclosing statement.
+  Inline comments remain valid, for example `/* SAFETY: ... */ x as unknown
+  as T`. Upstream walks an arbitrary number of statement-owner levels looking
+  for ANY preceding comment in the file; this port only checks one level up
+  from the assertion and one level up from its immediate containing
+  statement or supported object member. There is NO dominance verification:
+  the rule proves a comment is adjacent, never that the comment is true or
+  that it describes this cast.
+
+  2026-08-20 (#1847, found in #1843's review): the "one level up from
+  its immediate containing statement" kind list omitted
+  `export_statement` and `public_field_definition`, so a `SAFETY:`
+  comment placed directly above an exported cast (`export const b =
+  (x as unknown as T).y;`) or a class-field cast (`bar: unknown = (x as
+  unknown as T).y;`) could not satisfy the valve — the rule is
+  `error`-tier and semantically `blocking`, so this left no escape for
+  those two shapes. Added both kinds. Verified the containing-statement
+  walk already covers casts nested deeper without a new kind: a cast
+  inside a `static {}` init block or an arrow-function body still
+  resolves to an ancestor `lexical_declaration`/`variable_declaration`
+  already in the list (probed with ast-grep's own `--rule` scan, not
+  reasoning about the grammar from memory), and a `SAFETY:` comment on
+  an `export const` nested inside a `namespace` block clears the valve
+  through the same `export_statement` kind — `stopBy: end` already
+  walks past the namespace wrapper to find it. `readonly`/`abstract`/
+  `static`/private-`#name` class fields all parse to the same
+  `public_field_definition` kind, so one entry covers all of them.
+
+  2026-08-20 (#1852 review, F1): the same defect shape one more time —
+  an enum member's initializer cast (`enum Foo { A = (x as unknown as
+  T).y }`) has no recognized ancestor either. The member's own kind is
+  `enum_assignment` (probed the same way: `ast-grep scan --rule` against
+  a real `enum`/`const enum`/`export enum` snippet rather than guessing
+  from the export/field precedent). One `enum_assignment` kind entry
+  covers plain, `const`, and `export` enums alike, the same way
+  `public_field_definition` covered every class-field modifier —
+  `enum_assignment` is the member-list node itself, unaffected by
+  keywords on the enclosing `enum_declaration`. `declare enum` members
+  have no initializer expression to cast, so there is nothing to probe
+  there.
+
+  Matched pair with `no-chained-type-assertions.yml`. As of 2026-08-20
+  the two PARTITION the assertion space instead of overlapping: this
+  rule owns `x as unknown as T` (with the `SAFETY:` escape valve); that
+  rule owns the concrete `x as A as B` chain, which has no escape valve
+  because it has no legitimate reading. Before the split both rules
+  matched the identical `as unknown as` site list (verified: 16/16
+  pi-lens, 182/182 pi, 194/194 opencode), so every uncommented site
+  raised two diagnostics for one defect.
+
+  2026-08-20 (#1834): both `follows` checks used `stopBy: end`, which
+  scans EVERY preceding sibling all the way to the top of the enclosing
+  block, not just the comment directly above the cast. A `SAFETY:`
+  comment attached to one cast silently exempted every LATER cast in the
+  same block, including casts on a different subject with no
+  justification of their own. Probe: `// SAFETY: ...` above `const a =
+  (y as unknown as string).length` followed by an undocumented `const b
+  = (x as unknown as string).length` scored 0 hits; `b`'s cast should
+  have been flagged. Fixed the same way as `redundant-unsafe-function`'s
+  identical valve (PR #1821, refs #1806): bound the backward scan with
+  `stopBy: {not: {kind: comment}}`, so it stops at the first non-comment
+  sibling and only ever searches the CONTIGUOUS comment run directly
+  above the cast (or its containing statement), never an earlier
+  statement's comment. The "Scope and known gap" note above already
+  described this contiguous-comment intent; the shipped pattern didn't
+  implement it.
+
+  2026-08-20 (#1870): the pair arm is bounded by the nearest `pair`. An
+  outer object member's SAFETY comment must not suppress a cast in a nested
+  member, and a nested member's comment must not suppress a parent cast.
+  The direct-cast arm remains the precise escape valve for comments adjacent
+  to casts in array elements and call arguments.
+ignores:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.test.mts"
+  - "**/*.test.cts"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+  - "**/tests/**"
+  - "**/test/**"
+  - "**/__tests__/**"
+rule:
+  pattern: $X as unknown as $Y
+  not:
+    any:
+      - follows:
+          kind: comment
+          regex: 'SAFETY\s*:'
+          stopBy: { not: { kind: comment } }
+      - inside:
+          stopBy: { kind: pair }
+          any:
+            - kind: pair
+          follows:
+            kind: comment
+            regex: 'SAFETY\s*:'
+            stopBy: { not: { kind: comment } }
+      - inside:
+          stopBy: end
+          any:
+            - kind: expression_statement
+            - kind: lexical_declaration
+            - kind: variable_declaration
+            - kind: return_statement
+            - kind: export_statement
+            - kind: public_field_definition
+            - kind: enum_assignment
+          follows:
+            kind: comment
+            regex: 'SAFETY\s*:'
+            stopBy: { not: { kind: comment } }

package/node_modules/pi-lens/rules/ast-grep-rules/rules/ts-void-zero.yml

@@ -5,6 +5,11 @@ message: void 0 for undefined - use undefined directly
 metadata:
   weight: 2
   category: slop
+note: |
+  Replacing `void 0` with `undefined` can change behavior when a local binding
+  shadows `undefined`. Shadowing `undefined` is itself a defect, and this fix
+  does not attempt to detect it.
 rule:
   kind: unary_expression
   pattern: "void 0"
+fix: undefined

package/node_modules/pi-lens/rules/ast-grep-rules/self-scan-baseline.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "Regenerate with `npm run astgrep:self-scan -- --update-baseline` AFTER triaging every new entry (fix the underlying finding, or confirm it's a legitimate exception and document why in the same PR). Never regenerate to silently swallow an unreviewed hit.",
+  "generatedAt": "2026-08-19T20:44:05.206Z",
+  "allowed": []
+}

package/node_modules/pi-lens/scripts/analyze-pi-lens-logs.mjs

@@ -202,6 +202,13 @@ function createState(files) {
 				aborted: 0,
 				timedOutSweeps: 0,
 				timedOutFilesTotal: 0,
+				// #1618: per-reason breakdown of the same total. Populated from each
+				// sweep's `unconfirmedByReason` metadata when present; a sweep logged
+				// by a pre-#1618 build carries no such field, so its files are
+				// bucketed under "budget (pre-#1618 build)" — the ABSENT field is
+				// itself the vintage signal, not an assumption that every one of
+				// those files really was a budget timeout.
+				unconfirmedByReason: counter(),
 				sweeps: [],
 				progress: [],
 			},
@@ -367,6 +374,27 @@ async function analyzeLatency(files, state) {
 					if (timedOut > 0) {
 						ws.timedOutSweeps += 1;
 						ws.timedOutFilesTotal += timedOut;
+						// #1618: attribute by the REAL per-reason tally when the build
+						// that wrote this log line has it — a service-destroyed file
+						// must never count toward "hit the per-file budget" the way it
+						// used to (the forensics tool that found #1618 in the first
+						// place read this exact field and mis-blamed budget exhaustion
+						// for what were mostly service-destroyed files).
+						const byReason = entry.metadata?.unconfirmedByReason;
+						if (byReason && typeof byReason === "object") {
+							for (const [reason, count] of Object.entries(byReason)) {
+								const n = Number(count) || 0;
+								if (n > 0) ws.unconfirmedByReason.inc(reason, n);
+							}
+						} else {
+							// Vintage-attribution fallback: no `unconfirmedByReason` means
+							// this line predates #1618 — the absent field IS the signal,
+							// not proof every file here was really a budget timeout.
+							ws.unconfirmedByReason.inc(
+								"budget (pre-#1618 build)",
+								timedOut,
+							);
+						}
 						state.smellTotals.inc("lsp-workspace-file-timeouts");
 						pushTop(
 							ws.sweeps,
@@ -1217,11 +1245,21 @@ function buildReport(state) {
 		"Full LSP workspace sweeps that logged a start but never a completion (hang/kill signature — the 8h-hang class #383 hardened)",
 		ws.progress.slice(0, limit),
 	);
+	// #1618: "hit the per-file budget" used to be this smell's blanket
+	// description regardless of WHY a file was unconfirmed — the exact
+	// mislabeling the forensics pass on this class found (81/111 "budget"
+	// files were actually service-destroyed). Render the real breakdown when
+	// available.
+	const unconfirmedReasonBreakdown = ws.unconfirmedByReason
+		.top(limit)
+		.map(({ key, count }) => `${key}=${count}`)
+		.join(", ");
 	addSmell(
 		smells,
 		"lsp-workspace-file-timeouts",
 		smellCount("lsp-workspace-file-timeouts"),
-		`Full LSP sweeps where files hit the per-file budget (${ws.timedOutFilesTotal} files across ${ws.timedOutSweeps} sweeps)`,
+		`Full LSP sweeps produced an unconfirmed file (${ws.timedOutFilesTotal} files across ${ws.timedOutSweeps} sweeps)` +
+			(unconfirmedReasonBreakdown ? ` — by reason: ${unconfirmedReasonBreakdown}` : ""),
 		ws.sweeps.slice(0, limit),
 	);
 
@@ -1257,6 +1295,11 @@ function buildReport(state) {
 				aborted: ws.aborted,
 				timedOutSweeps: ws.timedOutSweeps,
 				timedOutFilesTotal: ws.timedOutFilesTotal,
+				// #1618: the real per-reason breakdown of `timedOutFilesTotal`.
+				// "budget (pre-#1618 build)" means those log lines predate the
+				// per-reason tally entirely — an older build's absence of the field,
+				// not a claim those files really timed out.
+				unconfirmedByReason: ws.unconfirmedByReason.toJSON(),
 			},
 		},
 		cascade: {
@@ -1458,6 +1501,15 @@ function printReport(report) {
 		console.log(
 			`  started=${ws.started} completed=${ws.completed} incomplete=${ws.incomplete} aborted=${ws.aborted} fileTimeouts=${ws.timedOutFilesTotal} (in ${ws.timedOutSweeps} sweeps)`,
 		);
+		// #1618: never let a flat count alone read as "budget exhaustion" —
+		// print the real per-reason split (or its absence, which itself means
+		// every line here predates the tally).
+		const reasons = Object.entries(ws.unconfirmedByReason ?? {});
+		if (reasons.length) {
+			console.log(
+				`  by reason: ${reasons.map(([reason, count]) => `${reason}=${count}`).join(", ")}`,
+			);
+		}
 	}
 	const wl = report.worklog;
 	if (wl && (wl.byModel.length || wl.byRuleModel.length)) {

package/node_modules/pi-lens/scripts/download-grammars.js

@@ -39,6 +39,24 @@ export const SOURCE_OVERRIDES = {
         url: "https://unpkg.com/@tree-sitter-grammars/tree-sitter-yaml@0.7.1/tree-sitter-yaml.wasm",
     },
 };
+/**
+ * Grammars committed under `vendor/grammars/` rather than fetched.
+ *
+ * tree-sitter-cue: no published wasm exists — npm's `tree-sitter-cue` is a
+ * native binding, the `tree-sitter-wasms` aggregator has no CUE, and upstream
+ * cuts no releases — so we build it from a pinned commit (#1522).
+ */
+export const VENDORED_GRAMMARS = {
+    "tree-sitter-cue.wasm": {
+        repo: "https://github.com/eonpatapon/tree-sitter-cue",
+        commit: "dd7b90e0770ff18070c515937ba3c3d6d93db00e",
+        license: "MIT",
+        buildCommand: "npx tree-sitter-cli build --wasm",
+        sha256: "sha256:751f8cc8ccf72da760133e3d365562ff7bbf5b951e0b73568576fd159db7d601",
+    },
+};
+/** Directory the committed grammars live in, relative to the package root. */
+export const VENDORED_DIR = "vendor/grammars";
 /** The package a grammar's sidecar records (override or the global aggregator). */
 export function expectedPackage(filename, manifest) {
     return manifest.overrides?.[filename]?.package ?? SOURCE_OVERRIDES[filename]?.package ?? manifest.package;
@@ -210,6 +228,13 @@ async function regenerateManifest() {
         version: TREE_SITTER_WASMS_VERSION,
         grammars: sorted,
         ...(Object.keys(SOURCE_OVERRIDES).length ? { overrides: SOURCE_OVERRIDES } : {}),
+        // Re-emitted from the map above, not copied from the old manifest: a
+        // `--write-manifest` run on a tree-sitter-wasms bump must not silently
+        // drop the committed grammars' provenance, which would leave the guard
+        // with nothing to check.
+        ...(Object.keys(VENDORED_GRAMMARS).length
+            ? { vendored: VENDORED_GRAMMARS }
+            : {}),
     };
     writeFileSync(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
     console.error(`Wrote ${MANIFEST_PATH} (${GRAMMARS.length} grammars).`);

package/node_modules/pi-lens/scripts/grammars.lock.json

@@ -40,5 +40,14 @@
       "version": "0.7.1",
       "url": "https://unpkg.com/@tree-sitter-grammars/tree-sitter-yaml@0.7.1/tree-sitter-yaml.wasm"
     }
+  },
+  "vendored": {
+    "tree-sitter-cue.wasm": {
+      "repo": "https://github.com/eonpatapon/tree-sitter-cue",
+      "commit": "dd7b90e0770ff18070c515937ba3c3d6d93db00e",
+      "license": "MIT",
+      "buildCommand": "npx tree-sitter-cli build --wasm",
+      "sha256": "sha256:751f8cc8ccf72da760133e3d365562ff7bbf5b951e0b73568576fd159db7d601"
+    }
   }
 }

package/node_modules/pi-lens/scripts/install-selftest.mjs

@@ -19,6 +19,20 @@
  * build-script-provided assets (ast-grep CLI binary + tree-sitter grammars)
  * that pnpm/bun skip by default. It runs no model and needs no credentials.
  *
+ * WHAT IT NO LONGER COVERS (#1926)
+ * pi supplies `typebox` and `@earendil-works/pi-tui` from its own runtime, so
+ * they are optional peers and no install vendors them. This probe is not pi, so
+ * those specifiers cannot resolve here, and `dist/index.js` throws on the FIRST
+ * one it imports. A host-provided miss is therefore recorded as EXPECTED rather
+ * than failed. The cost is real and stated plainly: evaluation stops there, so
+ * the entry probe no longer proves the whole bundled graph resolves, which is
+ * what #285 and #335 asked it to prove. Any OTHER unresolved specifier still
+ * fails hard, and the per-module probes below (file-utils, complexity-client,
+ * bootstrap) still cover that graph directly. The surviving POSITIVE proof that
+ * the entry loads in full is the install-smoke `pi-load` job: it installs pi,
+ * installs pi-lens through pi, and confirms over RPC that pi-lens registered
+ * its commands.
+ *
  * USAGE
  *   bun  scripts/install-selftest.mjs     # faithful: pi's runtime is bun
  *   node scripts/install-selftest.mjs     # also works
@@ -28,10 +42,11 @@
  */
 
 import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
 import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 import * as path from "node:path";
-import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { HOST_PROVIDED_PACKAGES } from "./lib/host-provided-deps.mjs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const pkgRoot = path.resolve(here, "..");
@@ -42,6 +57,26 @@ const results = [];
 const record = (name, kind, ok, detail = "") =>
 	results.push({ name, kind, ok, detail });
 
+/**
+ * Which host-provided package, if any, a resolution error is about. Returns
+ * undefined for every other error, so an unrelated missing package still fails.
+ */
+function hostProvidedMiss(err) {
+	const text = `${err?.code || ""} ${err?.message || err}`;
+	if (
+		!/ERR_MODULE_NOT_FOUND|Cannot find (package|module)|ResolveMessage/.test(
+			text,
+		)
+	) {
+		return undefined;
+	}
+	return HOST_PROVIDED_PACKAGES.find((name) =>
+		new RegExp(
+			`['"\`]${name.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")}['"\`]`,
+		).test(text),
+	);
+}
+
 /** Import a module by URL and record whether its (eager) dep graph resolved. */
 async function probeImport(name, relPath) {
 	const url = new URL(
@@ -51,7 +86,24 @@ async function probeImport(name, relPath) {
 		await import(url.href);
 		record(name, "resolve", true);
 	} catch (err) {
-		record(name, "resolve", false, `${err?.code || ""} ${err?.message || err}`.trim());
+		// #1926: pi supplies these; outside pi they cannot resolve, and the entry
+		// throws on the first one. Expected, not a regression. Anything else is.
+		const host = hostProvidedMiss(err);
+		if (host) {
+			record(
+				name,
+				"expected",
+				true,
+				`stopped at host-provided '${host}' — pi supplies it; graph beyond this point unproven here (#1926)`,
+			);
+			return;
+		}
+		record(
+			name,
+			"resolve",
+			false,
+			`${err?.code || ""} ${err?.message || err}`.trim(),
+		);
 	}
 }
 
@@ -61,27 +113,53 @@ function probeResolve(spec) {
 		require.resolve(spec);
 		record(spec, "resolve", true);
 	} catch (err) {
-		record(spec, "resolve", false, `${err?.code || ""} ${err?.message || err}`.trim());
+		record(
+			spec,
+			"resolve",
+			false,
+			`${err?.code || ""} ${err?.message || err}`.trim(),
+		);
 	}
 }
 
 // --- 1. The documented failure-point modules (eager bare imports) ----------
 await probeImport("dist/index.js (entry)", "dist/index.js");
-await probeImport("clients/file-utils.js (→ minimatch)", "dist/clients/file-utils.js");
-await probeImport("clients/complexity-client.js (→ tree-sitter)", "dist/clients/complexity-client.js");
-await probeImport("clients/bootstrap.js (→ all analyzers)", "dist/clients/bootstrap.js");
+await probeImport(
+	"clients/file-utils.js (→ minimatch)",
+	"dist/clients/file-utils.js",
+);
+await probeImport(
+	"clients/complexity-client.js (→ tree-sitter)",
+	"dist/clients/complexity-client.js",
+);
+await probeImport(
+	"clients/bootstrap.js (→ all analyzers)",
+	"dist/clients/bootstrap.js",
+);
 
 // --- 2. Direct bare-specifier resolution -----------------------------------
-for (const spec of [
+// Host-provided packages are subtracted, not listed as exceptions: pi resolves
+// them from its own runtime, so nothing installs them and probing one here is
+// guaranteed to fail (#1926). The subtraction reads the same list the bundler
+// and the packaging tests use, so it cannot drift.
+const BARE_SPECIFIERS = [
 	"minimatch",
 	"typebox",
 	"js-yaml",
 	"vscode-jsonrpc",
 	"web-tree-sitter",
 	"@ast-grep/napi",
-]) {
+].filter((spec) => !HOST_PROVIDED_PACKAGES.includes(spec));
+
+for (const spec of BARE_SPECIFIERS) {
 	probeResolve(spec);
 }
+record(
+	"host-provided specifiers skipped",
+	"expected",
+	true,
+	`${HOST_PROVIDED_PACKAGES.join(", ")} — pi supplies these (#1926)`,
+);
 
 // --- 3. Spawned-binary tools (the universal net) ----------------------------
 // For every tool that ships its binary in a per-platform npm package
@@ -121,11 +199,21 @@ try {
 			});
 			record(label, "tool", true, bin);
 		} catch (err) {
-			record(label, "tool", false, `${bin} failed to run: ${err?.message || err}`);
+			record(
+				label,
+				"tool",
+				false,
+				`${bin} failed to run: ${err?.message || err}`,
+			);
 		}
 	}
 } catch (err) {
-	record("spawned-tool probe", "tool", false, `installer load failed: ${err?.message || err}`);
+	record(
+		"spawned-tool probe",
+		"tool",
+		false,
+		`installer load failed: ${err?.message || err}`,
+	);
 }
 
 // tree-sitter grammars — download-grammars.js postinstall writes them into

package/node_modules/pi-lens/scripts/lib/host-provided-deps.mjs

@@ -0,0 +1,75 @@
+/**
+ * Single source of truth for the packages `scripts/bundle-dist.mjs` keeps out of
+ * the dist bundle, split by the REASON they stay external. #1926.
+ *
+ * HOST_PROVIDED_PACKAGES
+ *   pi ships these inside its own runtime (`@earendil-works/pi-coding-agent`'s
+ *   node_modules). They must be declared as OPTIONAL peer dependencies plus dev
+ *   dependencies, never as runtime `dependencies`, because a runtime dependency
+ *   makes `npm install --omit=dev` — the command pi runs for a `git:` install —
+ *   vendor a private second copy into the extension's own node_modules. Node
+ *   then resolves the bare specifier to that copy and evaluates a whole extra
+ *   module graph at import. That is #1926: vendoring `typebox` and
+ *   `@earendil-works/pi-tui` cost 720ms of the 838ms git-install import, and
+ *   removing the copies took the PI_TIMING module import from 941ms to ~180ms.
+ *
+ *   The three entries are NOT interchangeable at runtime. pi resolves the bare
+ *   specifiers `typebox` and `@earendil-works/pi-tui` for an extension, so
+ *   VALUE imports of those work with no copy on disk — verified by hiding both
+ *   from the dogfood install and re-running under PI_TIMING (#1926), and by
+ *   `@tintinweb/pi-subagents`, which declares pi-tui as a peer and ships no
+ *   copy. `@earendil-works/pi-coding-agent` is different: it is not resolvable
+ *   from an extension at all, so pi-lens imports it TYPE-ONLY and inlines the
+ *   runtime helpers it needs. `tests/host-sdk-type-only.test.ts` enforces that
+ *   separate rule (#1334 S6); do not read this list as permission to
+ *   value-import the host SDK.
+ *
+ * LAZY_NATIVE_PACKAGES
+ *   Native addon / wasm, dynamic-imported by absolute file:// URL at call time.
+ *   They stay external because esbuild cannot inline a .node or .wasm, and they
+ *   cost nothing at load because nothing imports them statically.
+ *
+ * `tests/packaging.test.ts` pins both invariants against package.json and
+ * against the built dist entry, so this list cannot drift from what ships.
+ */
+
+/**
+ * Host-provided packages the extension VALUE-imports. pi resolves these bare
+ * specifiers at runtime, so the compiled entry cannot load without them.
+ * Outside pi — a bare `node dist/index.js` in a CI smoke check — nothing
+ * supplies them, so a job that wants a FULL load has to install them first, the
+ * way pi does. `scripts/supply-host-provided-deps.mjs` does that.
+ */
+export const HOST_PROVIDED_RUNTIME_PACKAGES = Object.freeze([
+	"typebox",
+	"@earendil-works/pi-tui",
+]);
+
+/**
+ * Host-provided packages the extension imports TYPE-ONLY. pi does not resolve
+ * these for an extension at all, which is why every runtime helper pi-lens
+ * needs from the host SDK is inlined instead; `tests/host-sdk-type-only.test.ts`
+ * enforces that (#1334 S6). Never install one of these to make a load succeed:
+ * the transitive tree has nested paths that exceed Windows MAX_PATH.
+ */
+export const HOST_PROVIDED_TYPE_ONLY_PACKAGES = Object.freeze([
+	"@earendil-works/pi-coding-agent",
+]);
+
+/** Everything pi supplies, so pi-lens must never declare it a dependency. */
+export const HOST_PROVIDED_PACKAGES = Object.freeze([
+	...HOST_PROVIDED_RUNTIME_PACKAGES,
+	...HOST_PROVIDED_TYPE_ONLY_PACKAGES,
+]);
+
+/** Native/wasm packages dynamic-imported by absolute path at call time. */
+export const LAZY_NATIVE_PACKAGES = Object.freeze([
+	"@ast-grep/napi",
+	"web-tree-sitter",
+]);
+
+/** Everything esbuild must NOT inline into dist/index.js. */
+export const BUNDLE_EXTERNALS = Object.freeze([
+	...HOST_PROVIDED_PACKAGES,
+	...LAZY_NATIVE_PACKAGES,
+]);