@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-win32-isabsolute-for-qualification.yml

@@ -1,6 +1,8 @@
 id: no-win32-isabsolute-for-qualification
 language: TypeScript
 severity: warning
+metadata:
+  category: pi-lens-self-scan
 message: "Use isFullyQualified for path qualification instead of win32.isAbsolute"
 note: |
   Qualification must follow the input path's shape. Use clients/path-utils.ts

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

@@ -12,6 +12,7 @@
  *   ~/.pi-lens/actionable-warnings*.log  JSONL advisory pipeline (inject/suppress)
  *   ~/.pi-lens/ast-grep-tools*.log   JSONL MCP ast-grep search/replace telemetry
  *   ~/.pi-lens/logs/*.jsonl          JSONL diagnostic findings
+ *   ~/.pi-lens/projects/<slug>/worklog.jsonl  JSONL fix worklog (rule/tool/model/provider, #1448)
  */
 
 import fs from "node:fs";
@@ -69,6 +70,7 @@ async function main() {
 		analyzeSessionStart(files.sessionStart, state),
 		analyzeActionableWarnings(files.actionableWarnings, state),
 		analyzeAstGrepTools(files.astGrepTools, state),
+		analyzeWorklog(files.worklog, state),
 	]);
 
 	const report = buildReport(state);
@@ -139,6 +141,13 @@ function discoverLogFiles(logRoot, archived) {
 		.filter((name) => name.endsWith(".jsonl"))
 		.map((name) => path.join(logsDir, name));
 
+	// worklog.jsonl lives per-project under projects/<slug>/ (getProjectDataDir),
+	// not at the log root — walk one level to find every project's file (#1448).
+	const projectsDir = path.join(logRoot, "projects");
+	const worklogs = safeReaddir(projectsDir)
+		.map((slug) => path.join(projectsDir, slug, "worklog.jsonl"))
+		.filter((file) => fs.existsSync(file));
+
 	const byPrefix = (prefix) =>
 		allRootFiles.filter((file) => {
 			const base = path.basename(file);
@@ -156,6 +165,7 @@ function discoverLogFiles(logRoot, archived) {
 		actionableWarnings: byPrefix("actionable-warnings"),
 		astGrepTools: byPrefix("ast-grep-tools"),
 		diagnostics: dailyLogs,
+		worklog: worklogs,
 	};
 }
 
@@ -192,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: [],
 			},
@@ -263,6 +280,14 @@ function createState(files) {
 			errors: [],
 			slow: [],
 		},
+		worklog: {
+			// key: "<rule>||<model>" (model "" when the entry predates #1448 or the
+			// runtime didn't know it) -> { total, autoFixed }
+			byRuleModel: new Map(),
+			byModel: counter(),
+			byModelAutoFixed: counter(),
+			byProvider: counter(),
+		},
 	};
 }
 
@@ -349,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,
@@ -737,6 +783,39 @@ async function analyzeAstGrepTools(files, state) {
 	}
 }
 
+/**
+ * Per-model rollup (#1448): rule × model counts and auto-fixed vs
+ * agent-required rates, from worklog.jsonl's optional `model`/`provider`
+ * fields. Entries predating #1448 (or written outside a live agent turn)
+ * have neither field — bucketed under the empty-string model/provider key so
+ * "unattributed" volume stays visible rather than silently dropped.
+ */
+async function analyzeWorklog(files, state) {
+	for (const file of files) {
+		await forEachJsonLine(file, "worklog", state, (entry) => {
+			const ts = dateOf(entry.timestamp);
+			if (!inWindow(ts)) return;
+			state.seen.inc("worklog");
+			const rule = entry.rule ?? "unknown";
+			const model = entry.model ?? "";
+			const provider = entry.provider ?? "";
+			const key = `${rule}||${model}`;
+			const row = state.worklog.byRuleModel.get(key) ?? {
+				rule,
+				model,
+				total: 0,
+				autoFixed: 0,
+			};
+			row.total += 1;
+			if (entry.autoFixed) row.autoFixed += 1;
+			state.worklog.byRuleModel.set(key, row);
+			state.worklog.byModel.inc(model || "(unknown)");
+			if (entry.autoFixed) state.worklog.byModelAutoFixed.inc(model || "(unknown)");
+			state.worklog.byProvider.inc(provider || "(unknown)");
+		});
+	}
+}
+
 async function forEachJsonLine(file, bucket, state, visitor) {
 	await forEachLine(file, async (line) => {
 		if (!line.trim()) return;
@@ -1166,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),
 	);
 
@@ -1206,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: {
@@ -1259,6 +1353,17 @@ function buildReport(state) {
 			errors: state.astGrep.errors.slice(0, limit),
 			slow: state.astGrep.slow.slice(0, limit),
 		},
+		worklog: {
+			byModel: state.worklog.byModel.top(limit * 2),
+			byProvider: state.worklog.byProvider.top(limit * 2),
+			byRuleModel: [...state.worklog.byRuleModel.values()]
+				.map((row) => ({
+					...row,
+					autoFixedRate: row.total ? row.autoFixed / row.total : 0,
+				}))
+				.sort((a, b) => b.total - a.total)
+				.slice(0, limit * 3),
+		},
 	};
 }
 
@@ -1396,7 +1501,33 @@ 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)) {
+		console.log("\nWorklog per-model rollup (#1448)");
+		console.log(
+			`  by model: ${wl.byModel.map((x) => `${x.key}=${x.count}`).join(", ")}`,
+		);
+		if (wl.byProvider.length)
+			console.log(
+				`  by provider: ${wl.byProvider.map((x) => `${x.key}=${x.count}`).join(", ")}`,
+			);
+		console.log("  rule × model (auto-fixed vs agent-required):");
+		for (const row of wl.byRuleModel.slice(0, limit))
+			console.log(
+				`    ${String(row.total).padStart(5)}  ${row.rule} [${row.model || "(unknown)"}]  autoFixed=${row.autoFixed} (${(row.autoFixedRate * 100).toFixed(0)}%)`,
+			);
+	}
+
 	const timeouts = Object.entries(report.latency.phaseTimeouts ?? {});
 	if (timeouts.length) {
 		console.log("\nPhase timeouts");

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/skills/pi-lens-ast-grep/SKILL.md

@@ -52,12 +52,17 @@ Use `$$$` when you don't need the captured value; `$$$NAME` when you do.
 
 Use these instead of writing raw YAML:
 
-| Parameter | What it does |
-|---|---|
-| `insideKind` | Only match inside an ancestor of this node kind |
-| `hasKind` | Only match nodes that contain a descendant of this kind |
-| `follows` | Only match nodes preceded by a sibling matching this pattern |
-| `precedes` | Only match nodes followed by a sibling matching this pattern |
+| Parameter | Tool | What it does |
+|---|---|---|
+| `insideKind` | both | Only match inside an ancestor of this node kind (searches ALL ancestors, `stopBy: end`) |
+| `hasKind` | both | Only match nodes whose **immediate child** has this kind (`stopBy: neighbor` — NOT recursive) |
+| `hasDescendantKind` | both | Only match nodes containing this kind **anywhere in their descendants** (`stopBy: end`) — use this instead of `hasKind` when the target isn't a direct child |
+| `follows` | both | Only match nodes preceded by a sibling matching this pattern |
+| `precedes` | both | Only match nodes followed by a sibling matching this pattern |
+
+`hasKind` and `hasDescendantKind` are mutually exclusive on both tools — combining them errors.
+
+⚠ `insideKind` searches ALL ancestors (`stopBy: end`) with no boundary of its own — on a deeply nested file it can escalate past the enclosing function you meant and match against an unrelated outer scope; scope with `paths` or a raw YAML `rule:` with its own `stopBy` boundary if that matters.
 
 ```
 # console.log only inside functions
@@ -152,13 +157,9 @@ Use these as starting points, then scope `paths` tightly.
 
 | Task | Pattern / params |
 |---|---|
-| Find pi lifecycle handlers | `pattern: pi.on($EVENT, $HANDLER)` |
-| Find timers | `pattern: setTimeout($CALLBACK, $$$REST)` or `setInterval($CALLBACK, $$$REST)` |
-| Find immediate/deferred work | `pattern: setImmediate($CALLBACK)` |
-| Find promise callbacks | `pattern: $PROMISE.then($CALLBACK)` / `.catch($CALLBACK)` / `.finally($CALLBACK)` |
 | Find object-literal function dependency by name | `pattern: { resetLSPService: $FN, $$$REST }` |
-| Find fire-and-forget async calls | `pattern: void $CALL` |
 | Find empty catches | `pattern: try { $$$BODY } catch ($ERR) { }` |
+| Find fire-and-forget async calls | `pattern: void $CALL` |
 
 For lifecycle bugs, search first, then use the returned `details.matchLocations[].readSlice` handle for bounded context.
 

package/node_modules/pi-lens/skills/pi-lens-lsp-navigation/SKILL.md

@@ -13,39 +13,39 @@ Use `lsp_diagnostics` before builds/tests or after touching several files:
 
 | Need | Tool call |
 |---|---|
-| Check one file | `lsp_diagnostics({ filePath: "src/file.ts" })` |
-| Check a folder | `lsp_diagnostics({ filePath: "src/", severity: "error" })` |
-| Check exact touched files | `lsp_diagnostics({ filePaths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
-| Slow server (Rust, Java) | `lsp_diagnostics({ filePaths: files, waitMs: 2000 })` |
-| Include warnings | `lsp_diagnostics({ filePaths: files, severity: "all" })` |
+| Check one file | `lsp_diagnostics({ path: "src/file.ts" })` |
+| Check a folder | `lsp_diagnostics({ path: "src/", severity: "error" })` |
+| Check exact touched files | `lsp_diagnostics({ paths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
+| Slow server (Rust, Java) | `lsp_diagnostics({ paths: files, waitMs: 2000 })` |
+| Include warnings | `lsp_diagnostics({ paths: files, severity: "all" })` |
 
-Prefer explicit `filePaths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
+Prefer explicit `paths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
 
 ## Navigation (Code Intelligence)
 
 | Question | Operation | Parameters |
 |---|---|---|
-| Where is this defined? | `definition` | filePath, line, character |
-| Where is this symbol's *type* defined? | `typeDefinition` | filePath, line, character |
-| Where is this declared (vs defined)? | `declaration` | filePath, line, character |
-| Find all usages | `references` | filePath, line, character |
-| What type is this? | `hover` | filePath, line, character |
-| Call signature | `signatureHelp` | filePath, line, character (at arg position) |
-| Symbols in this file | `documentSymbol` | filePath |
-| Find symbol across project | `workspaceSymbol` | query + filePath (strongly recommended) |
-| Quick fixes available | `codeAction` | filePath, line, character, endLine, endCharacter |
-| Rename symbol safely | `rename` | filePath, line, character, newName |
-| Who implements this? | `implementation` | filePath, line, character |
-| Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | filePath, line, character |
-| What does this call? | `prepareCallHierarchy` → `outgoingCalls` | filePath, line, character |
-| What commands does the server offer? | `capabilities` | (optional filePath) — lists advertised commands |
+| Where is this defined? | `definition` | path, line, character |
+| Where is this symbol's *type* defined? | `typeDefinition` | path, line, character |
+| Where is this declared (vs defined)? | `declaration` | path, line, character |
+| Find all usages | `references` | path, line, character |
+| What type is this? | `hover` | path, line, character |
+| Call signature | `signatureHelp` | path, line, character (at arg position) |
+| Symbols in this file | `documentSymbol` | path |
+| Find symbol across project | `workspaceSymbol` | query + path (strongly recommended) |
+| Quick fixes available | `codeAction` | path, line, character, endLine, endCharacter |
+| Rename symbol safely | `rename` | path, line, character, newName |
+| Who implements this? | `implementation` | path, line, character |
+| Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | path, line, character |
+| What does this call? | `prepareCallHierarchy` → `outgoingCalls` | path, line, character |
+| What commands does the server offer? | `capabilities` | (optional path) — lists advertised commands |
 | Run a server command (e.g. organize imports) | `executeCommand` | command (+ commandArguments); dry-run unless `apply:true` |
 
 ## Call Hierarchy Pattern
 
 ```
 // Step 1
-lsp_navigation(operation="prepareCallHierarchy", filePath="src/api.ts", line=42, character=10)
+lsp_navigation(operation="prepareCallHierarchy", path="src/api.ts", line=42, character=10)
 // → returns callHierarchyItem
 
 // Step 2
@@ -56,7 +56,7 @@ lsp_navigation(operation="outgoingCalls", callHierarchyItem=<item from step 1>)
 ## Operational Notes
 
 - **`definition` returns nothing?** The file may not be open/indexed yet. Read it first, then retry.
-- **`workspaceSymbol` empty?** Always pass `filePath`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
+- **`workspaceSymbol` empty?** Always pass `path`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
 - **`references`** — query from the *definition site* for full cross-file coverage; usage-site queries can be partial.
 - **`signatureHelp`** — only valid at call-site argument positions; declaration positions return empty.
 - **`workspaceDiagnostics`** — tracked push snapshot only, not an active check. Use `lsp_diagnostics` when you need fresh results.