@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

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

@@ -62,6 +62,8 @@ Use these instead of writing raw YAML:
 
 `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
 ast_grep_search pattern="console.log($MSG)" lang="typescript" insideKind="function_declaration"

package/node_modules/pi-lens/skills/pi-lens-write-ast-grep-rule/SKILL.md

@@ -13,7 +13,7 @@ Same `id` as a built-in overrides it. Multiple rules per file: separate with `--
 ```yaml
 id: no-foo-bar
 language: TypeScript        # PascalCase — see languages below
-severity: warning           # error | warning | info
+severity: warning           # error | warning | hint | info — pick by evidence, see below
 message: "Avoid foo.bar() — use baz() instead"
 note: |
   Longer explanation / fix guidance here.
@@ -21,6 +21,39 @@ rule:
   pattern: foo.bar($ARG)
 ```
 
+**Pick the severity by the evidence behind the rule, not by feel:**
+
+- **`error`** — only with a documented zero-false-positive audit in the `note`.
+  Only `error` maps to semantic `blocking` and stops a turn.
+- **`warning`** — a real finding with a known, bounded false-positive rate.
+- **`hint` / `info`** — style opinions. They render as advisory text, never
+  block, and lose the report budget to warnings when a report is capped.
+
+Full policy and the `error`-promotion procedure: AGENTS.md's "Severity policy
+(#1777)" section. Read it before shipping anything above `warning`.
+
+## Before promoting to error
+
+Three things must all be true, and the rule's `note` must record them:
+
+1. **A multi-corpus false-positive census**, not a single-tree count. Run the
+   rule over pi-lens's `clients/`/`tests/` plus at least one real external
+   codebase of the kind the rule targets, classify every hit, and put the
+   table in the note.
+2. **Structural narrowing before exemption.** Suppress a legitimate idiom
+   with a relational constraint (`inside`/`has`/`follows`, scoped path
+   globs), not with prose telling readers to ignore the hit. Narrow first —
+   don't reach for a lower tier as the easy way out. `no-non-null-assertion`
+   was demoted to `hint` (`0124608a`), then reverted back to `warning` once
+   the same false positives were closed with a structural exclusion instead
+   (`b3e1fd79`).
+3. **Self-scan wiring.** Tag the rule `metadata.category: pi-lens-self-scan`
+   so `npm run astgrep:self-scan` holds this tree at zero in CI. An `error`
+   rule that never runs against pi-lens's own source is an unaudited claim.
+
+If the post-narrowing residual is still tens of legitimate hits, stop and
+report the numbers instead of shipping at `error`.
+
 ## Language values
 
 `TypeScript` `JavaScript` `Python` `Go` `Rust` `Java` `C` `Cpp` `CSharp` `Kotlin` `Ruby` `Php`
@@ -69,6 +102,13 @@ constraints:                  # metavariable regex constraints work
 recursive descendant/ancestor search add `stopBy: end`. This is the #1 migration
 gotcha — see the `has` note in `reference.md`.
 
+⚠ **`stopBy: end` alone is not a boundary.** It's a search-depth control — how far
+the walk searches — not a stop condition; the `any:` kind list only decides what
+CAN satisfy the match, not where the walk halts. To scope a relation to the
+nearest enclosing function (or any other boundary), give `stopBy` its own rule.
+See "Scoping to the nearest enclosing X" in `reference.md` (#1794 F1 — this bug
+shipped twice in one window).
+
 ## YAML quoting — REQUIRED (js-yaml will reject the rule otherwise)
 
 The parser is a real YAML parser, so unquoted special chars throw and the rule is
@@ -104,13 +144,50 @@ The parser is a real YAML parser, so unquoted special chars throw and the rule i
 
 `reference.md` (same directory) covers: ReDoS-safe regex authoring, node-text
 string-escape quirks, `has`/`inside` `stopBy` defaults (and when to override
-them), the `-js` twin dedup behavior (#657), boolean-parameter matching
-across the TS/JS grammars, and precision-over-recall heuristics for
+them), scoping a relation to the nearest enclosing node with a `stopBy`
+boundary rule, the `-js` twin dedup behavior (#657), boolean-parameter
+matching across the TS/JS grammars, and precision-over-recall heuristics for
 denylist-shaped rules. Read it when a rule isn't matching (or over-matching)
 the way you expect, or before shipping a `regex`/`has`-heavy rule.
 
+## Testing a suppression
+
+Every relational suppression (a `has`/`inside`/`not` exclusion for a
+legitimate idiom) needs two fixtures per bound metavariable, not one:
+
+1. **A same-binding valid case** — the idiom the exclusion is meant to
+   suppress, with the metavariable bound consistently (same receiver, same
+   key).
+2. **A mutation-guard invalid case** — the same shape with the binding
+   broken: a different key, a different receiver, or a boundary-crossing
+   lookalike (the guard lives in the wrong scope). This proves the
+   exclusion checks the BINDING, not just the pattern's presence somewhere
+   in the file.
+
+`rules/ast-grep-rules/rule-tests/no-non-null-assertion-test.yml` is the model: alongside the
+get-after-has/pop-after-length valid cases, it fixtures a different-key
+guard, a different-map guard, and an outer-function guard that must NOT
+suppress an inner closure — each one red if the corresponding binding check
+is deleted.
+
+Corpus silence is not evidence. A valve with zero corpus hits needs
+adversarial fixtures MORE, not less — `redundant-unsafe-function` targets
+Rust, so it has no pi-lens corpus to census against, and its `# Safety`
+valve still shipped an unbounded backward scan that over-suppressed real
+detections, caught only by adversarial fixtures in review (`00284bcc`). A
+documented blind spot (an idiom the rule knowingly can't distinguish from a
+bug) becomes an `invalid`-direction fixture with a comment naming the gap,
+never silence.
+
+Regenerate the catalog doc with `npm run docs:rule-catalogs` after adding or
+changing a rule — never hand-edit the generated catalog.
+
 ## Validating a candidate rule against the REAL engine (not the warm MCP cache)
 
+Live-binary discipline (AGENTS.md shape 16) applies here too: verify parsing
+and match behavior against a real `ast-grep` run before you write it into a
+rule note or a test fixture — a hand-written fixture pins a guess, not a fact.
+
 ```
 
 # inspect how a PATTERN parses → find the node kind you actually need

package/node_modules/pi-lens/skills/pi-lens-write-ast-grep-rule/reference.md

@@ -92,6 +92,47 @@ grammars, and precision-over-recall heuristics for denylist-shaped rules.
    the partition unique; flag only a single quantified atom inside the group).
 ```
 
+## Scoping to the nearest enclosing X (#1794 F1)
+
+`stopBy` controls how far the ancestor/descendant walk searches. It is not a
+stop CONDITION. An `any:` kind list inside `inside`/`has` decides which
+nodes the walk is ALLOWED to match — it does not tell the walk where to
+halt. `stopBy: end` alone searches every ancestor up to the file root, so a
+guard several scopes out can suppress a finding inside an unrelated closure.
+
+To scope a relation to the nearest enclosing function (or any other
+boundary), give `stopBy` its OWN rule — the same kind list used as the
+match target — so the walk stops at the first satisfying ancestor and can
+never escalate past it:
+
+```yaml
+inside:
+  stopBy:                       # the BOUNDARY: halts the walk here
+    any:
+      - kind: function_declaration
+      - kind: method_definition
+      - kind: arrow_function
+      - kind: function_expression
+  any:                          # the MATCH TARGET: same list, different job
+    - kind: function_declaration
+    - kind: method_definition
+    - kind: arrow_function
+    - kind: function_expression
+  has:
+    stopBy: end
+    pattern: $M.has($K)
+```
+
+This is the fix for #1794 F1: an earlier `no-non-null-assertion` exclusion
+used `stopBy: end` with only the `any:` kind list as the match target, so a
+`.has()`/`.length` guard in an OUTER function suppressed a closure's `!`
+several scopes in. The same defect shape — `stopBy: end` mistaken for a
+boundary — shipped twice in the same 2026-08-20 window: once here, and once
+in `redundant-unsafe-function`'s `# Safety` valve (an unbounded backward
+comment scan, fixed in `00284bcc`). See
+`rules/ast-grep-rules/rules/no-non-null-assertion.yml` for the full working
+rule.
+
 ## Matching things a pattern can't express (#305)
 
 ```

package/node_modules/pi-mcp-adapter/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.27.0] - 2026-08-20
+
+### Highlights
+- MCP servers can now come from packages, runtime extension APIs, or the usual config files.
+- Static bearer tokens can use the OS credential store, with a stdin-only CLI for safer token management.
+- Long-lived sessions recover better when remote MCP servers are slow, refreshed, or reconnected.
+- OAuth flows clean up their callback listener when idle and work better inside nested terminal UI prompts.
+- Search, metadata cache writes, direct-tool counts, and UI stream pruning now do less repeated work.
+
+### Added
+- `/pi-mcp` now works as an alias for `/mcp` when a host reserves `/mcp`. Thanks to [@inxeoz](https://github.com/inxeoz) for #391.
+- `registerMcpServer({ pi, name, definition })` lets other extensions register and dispose session-scoped MCP servers at runtime. Registrations are proxy-tool-only, never persisted, and duplicate names fail closed. Thanks to [@bendavis78](https://github.com/bendavis78) and [@fmoda3](https://github.com/fmoda3) for the runtime API request in #376/#382.
+- Pi packages can ship prefixed MCP server definitions with `pi.mcp` manifest entries, without asking users to edit MCP config files. Thanks to [@bendavis78](https://github.com/bendavis78) for #376 and [@fmoda3](https://github.com/fmoda3) for the manifest design.
+- Static bearer tokens can opt into OS credential-store lookup with URL-bound records by setting `bearerTokenStore: true`. The new `pi-mcp-adapter token set|status|remove <server>` CLI reads tokens from stdin and never accepts a token as an argument. Thanks to [@AlexanderBartash](https://github.com/AlexanderBartash) for issue #366.
+
+### Changed
+- Search ranking now reuses normalized MCP tool fields and keyword tokens per catalog.
+- Per-request header commands collect process cleanup data in one snapshot per pass, reducing cold HTTP connect overhead.
+- Metadata cache saves write compact JSON while preserving atomic replacement and cross-process merges.
+- High-frequency UI stream event-log pruning tracks the latest checkpoint event ID instead of rescanning retained patches.
+- The MCP panel reuses direct-tool counts and token totals across renders while keeping toggle and reconnect updates immediate.
+
+### Fixed
+- Short-lived `mcpScript` workers no longer emit false unmanaged file-descriptor warnings on Node 24. Thanks to [@blalor](https://github.com/blalor) for PR #407.
+- OAuth callback listeners are released after idle auth flows, and MCP pickers stay hidden while nested OAuth input is active. Thanks to [@trevorleibert-mixpanel](https://github.com/trevorleibert-mixpanel) for PRs #403 and #404.
+- Request-header command cleanup can scan large process lists without overflowing `spawnSync`'s 1 MiB default buffer, which previously caused spurious `HTTP request headers command cleanup failed: ps exited with code unknown` refresh failures on busy hosts. Thanks to [@rtfpessoa](https://github.com/rtfpessoa) for PR #399.
+- Slow but healthy remote keep-alive servers are no longer marked failed when a bounded tools/list refresh times out. Thanks to [@brightmeowso](https://github.com/brightmeowso) for #400.
+- Cached metadata reconstruction now reuses one selector candidate index, avoiding repeated scans of large cached catalogs at startup.
+- MCP status consumers no longer see a connected catalog before Pi's model-facing tool surface is current. The first connected status snapshot now waits for direct-tool synchronization. Thanks to [@dmorn](https://github.com/dmorn) for PR #380.
+- JSON-string MCP tool-call arguments are normalized before approval and transport, preserving all fields and embedded quotes. Thanks to [@sebbean](https://github.com/sebbean) for PR #377.
+- Session tool approvals are scoped to the approved argument payload instead of every later call to the same tool. Thanks to [@spaceshipmike](https://github.com/spaceshipmike) for #367.
+- MCP panel commands no longer hang in RPC, JSON, and print modes when terminal-only custom UI is unavailable. Thanks to [@shixin-guo](https://github.com/shixin-guo) for PR #365.
+- Compact MCP rows now show a bounded tool-input preview and skip leading blank output lines in collapsed result previews.
+- MCP gateway requests nested inside proxy `args` are recovered instead of silently showing status, and invalid nested gateway requests now fail with guidance. Thanks to [@ibrmora](https://github.com/ibrmora) for #363.
+- Remote keep-alive tool catalogs refresh before user input, adapter-triggered turns, and health checks. Expired Streamable HTTP sessions reconnect so long-lived Pi sessions can discover replacement catalogs without restarting. Thanks to [@dmorn](https://github.com/dmorn) for #369 and PR #370.
+
 ## [2.26.0] - 2026-08-14
 
 ### Added