@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

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`
@@ -67,7 +100,14 @@ constraints:                  # metavariable regex constraints work
 
 ⚠ **`has`/`inside` default to the immediate child/parent (`stopBy: neighbor`).** For a
 recursive descendant/ancestor search add `stopBy: end`. This is the #1 migration
-gotcha — see the `has` note below.
+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)
 
@@ -100,123 +140,54 @@ The parser is a real YAML parser, so unquoted special chars throw and the rule i
 ✅ Docs: docs/custom-rules.md
 ```
 
-## Hard-won gotchas (NAPI runner specifics — verified)
-
-```
-⚠ `has`/`inside` default to DIRECT child/parent — add `stopBy: end` for a recursive search.
-   This cuts BOTH ways, so think about where the target node actually lives:
-   - Target is a grandchild+ → you MUST add `stopBy: end` or the `has` never matches.
-     `switch-without-default` = `switch_statement` not has `switch_default`: the default
-     lives under `switch_body`, so without `stopBy: end` it matches nothing and every
-     switch (even ones WITH a default) is flagged. Same for `nested-ternary` catching a
-     parenthesized `a ? (b ? c : d) : e`.
-   - Target is the direct child → leave it at `neighbor` (default). Adding `stopBy: end`
-     OVER-reports: `throw_statement` has `string` + `stopBy: end` flags `throw new
-     Error("x")` (the string is nested), and `expression_statement` has `new_expression`
-     + `stopBy: end` flags `fn(new Error())` as a discarded error. Keep these direct.
-   napi's `has` never matches the node itself, so a self-referential `kind: X` has
-   `kind: X` (with `stopBy: end`) correctly flags only genuinely-nested X.
-
-✅ Prefer `regex` on the matched node's OWN text over `has` when you only need to
-   inspect the node — avoids recursive-descendant false positives:
-     kind: export_statement
-     regex: '^export\s+(let|var)\b'      # precise; no has-recursion FP
-   (NAPI evaluates `regex` with JS RegExp on node.text() — keep it LINEAR so the
-   detector can't itself ReDoS.)
-
-⚠ String-literal regexes match SOURCE text, not the runtime string value.
-   Inspect the exact node text before writing constraints:
-     ast-grep run --kind string --lang ts sample.ts --json=compact
-   Example: source `"\\|"` is node text `"\\\\|"` in JSON; to match a
-   source-level escaped backslash (`\\`) followed by a non-backslash, the rule
-   regex needs FOUR regex backslashes, preferably in a YAML block scalar:
-     regex: >-
-       ^["'`]\\\\[^\\A-Za-z0-9$]
-   This is how `incomplete-string-escaping` catches both `"\\|"` and
-   `'\\"'`. Avoid shell here-doc probes for this class — shell/JSON escaping
-   can silently eat a backslash and make the rule look broken.
-
-⚠ `-js` twins: remember there are TWO execution surfaces.
-   - ast-grep CLI/LSP language-gates by `language:`. A `language: TypeScript`
-     rule is not enough for standalone `.js` coverage, so shipped user-facing
-     TS/JS rules that should fire under the ast-grep LSP usually need a `-js`
-     twin with `language: JavaScript` plus its own fixture.
-   - the in-process NAPI fallback (`ast-grep-napi.ts`) parses the target file's
-     own grammar and currently runs both TS and JS rules on every jsts file. A
-     grammar-agnostic twin can therefore duplicate in fallback mode.
-   - **Decide explicitly:** if the rule must cover `.js` through the ast-grep
-     CLI/LSP baseline, ship the twin and test both. If a rule is NAPI-only or
-     fallback duplication is unacceptable, fix runner dedup/normalization before
-     relying on a single TypeScript rule for JS coverage.
-   - **Grammar-divergent bodies** still need separate variants regardless:
-     e.g. `no-flag-argument` uses `required_parameter` in TS and
-     `assignment_pattern` in JS.
-
-✅ Node-kind facts (tree-sitter-typescript grammar — NOT the TS compiler / Roslyn):
-   - let / const  → `lexical_declaration`     (var is NOT here)
-   - var          → `variable_declaration`
-   - a regex literal's pattern text  → `regex_pattern`
-   - x[i] index access  → `subscript_expression`   (NOT element_access_expression)
-   - obj.prop access    → `member_expression`      (NOT property_access_expression)
-   - !x / -x / typeof x → `unary_expression`
-   - a ? b : c          → `ternary_expression`
-
-❌ Wrong-grammar kind names = silent dead rule. `element_access_expression`,
-   `property_access_expression`, `binary_operator`, etc. are TS-compiler/Roslyn names, not
-   tree-sitter's. napi REJECTS the whole rule ("invalid kind matcher") so it never runs.
-   Verify a kind exists before shipping:
-     node -e 'import("@ast-grep/napi").then(s=>{const r=s.ts.parse("x[i]").root();
-       const f=(n,k)=>{let c=n.kind()===k?1:0;for(const x of n.children())c+=f(x,k);return c};
-       console.log(f(r,"subscript_expression"))})'   # >0 means the kind is real
-
-✅ Test through the REAL runner from the repo root — it loads the actual shipped
-   rules from rules/ast-grep-rules/rules. Assert on diagnostic `rule` ids:
-     const res = await runner.run(ctx);  // ctx.filePath = temp .ts, cwd = repo
-   For pattern/kind/regex-only rules (CLI-identical semantics) `ast-grep scan` is fine.
-
-✅ Before shipping any text/regex detector, FP-scan the codebase:
-     ast-grep scan -r <rule>.yml clients tools
-   Real safe variants bite (e.g. ReDoS: (ba+)+ is safe — a mandatory prefix makes
-   the partition unique; flag only a single quantified atom inside the group).
-```
-
-## Matching things a pattern can't express (#305)
-
-```
-❌ A parameter default is NOT a `$X = false` pattern. `pattern: $FLAG = false` parses as
-   an `assignment_expression` (statement context) and never matches a function parameter.
-   Match the PARAM NODE + its child literal instead, capturing the name for reuse:
-     # TS grammar
-     - kind: required_parameter
-       all:
-         - has: { field: pattern, pattern: $FLAG }
-         - has: { any: [ { kind: "true" }, { kind: "false" } ] }
-     # JS grammar (assignment_pattern, with fields left/right)
-     - kind: assignment_pattern
-       all:
-         - has: { field: left, pattern: $FLAG }
-         - has: { field: right, any: [ { kind: "true" }, { kind: "false" } ] }
-
-✅ Metavar consistency works ACROSS sibling clauses of an `all` — a metavar bound in one
-   `has` must match the SAME text everywhere it reappears. Use it to CORRELATE nodes, which
-   is what makes a structural rule precise:
-     all:
-       - has: { stopBy: end, kind: required_parameter, has: { field: pattern, pattern: $FLAG } }
-       - has: { stopBy: end, any: [ { pattern: "if ($FLAG) $$$" }, { pattern: "if (!$FLAG) $$$" } ] }
-   This fires ONLY when the function branches on the SAME param it declared boolean — a
-   boolean default that's never branched on, or a branch on a different var, won't match.
-
-❌ Two `has:` keys in one mapping silently OVERWRITE (YAML: last key wins). For multiple
-   descendant constraints use `all:` with a LIST of `has` entries, never repeated `has:`.
-
-✅ Prefer a high-precision structural guard over an unbounded denylist. Message-chain
-   (Demeter) floods on fluent/promise/builder chains; rather than denylist every fluent
-   method name, REQUIRE the chain's first calls to be accessors (`get*`/`is*`/`has*`) via
-   `constraints` regex — promise/fluent/builder methods aren't accessor-named, so they're
-   excluded by construction. Precision over recall.
+## Reference doc — read before writing a NAPI-runner-specific or hard-to-express rule
+
+`reference.md` (same directory) covers: ReDoS-safe regex authoring, node-text
+string-escape quirks, `has`/`inside` `stopBy` defaults (and when to override
+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

@@ -0,0 +1,170 @@
+# pi-lens ast-grep Rule Reference
+
+Deep-dive companion to `SKILL.md`. Read this when you're debugging a rule
+that isn't matching (or over-matching) the way you expect: ReDoS-safe regex
+authoring, string-escape quirks in node text, `has`/`inside` `stopBy`
+defaults and when to override them, boolean-parameter matching across two
+grammars, and precision-over-recall heuristics for denylist-shaped rules.
+
+## Hard-won gotchas (NAPI runner specifics — verified)
+
+```
+⚠ `has`/`inside` default to DIRECT child/parent — add `stopBy: end` for a recursive search.
+   This cuts BOTH ways, so think about where the target node actually lives:
+   - Target is a grandchild+ → you MUST add `stopBy: end` or the `has` never matches.
+     `switch-without-default` = `switch_statement` not has `switch_default`: the default
+     lives under `switch_body`, so without `stopBy: end` it matches nothing and every
+     switch (even ones WITH a default) is flagged. Same for `nested-ternary` catching a
+     parenthesized `a ? (b ? c : d) : e`.
+   - Target is the direct child → leave it at `neighbor` (default). Adding `stopBy: end`
+     OVER-reports: `throw_statement` has `string` + `stopBy: end` flags `throw new
+     Error("x")` (the string is nested), and `expression_statement` has `new_expression`
+     + `stopBy: end` flags `fn(new Error())` as a discarded error. Keep these direct.
+   napi's `has` never matches the node itself, so a self-referential `kind: X` has
+   `kind: X` (with `stopBy: end`) correctly flags only genuinely-nested X.
+
+✅ Prefer `regex` on the matched node's OWN text over `has` when you only need to
+   inspect the node — avoids recursive-descendant false positives:
+     kind: export_statement
+     regex: '^export\s+(let|var)\b'      # precise; no has-recursion FP
+   (NAPI evaluates `regex` with JS RegExp on node.text() — keep it LINEAR so the
+   detector can't itself ReDoS.)
+
+⚠ String-literal regexes match SOURCE text, not the runtime string value.
+   Inspect the exact node text before writing constraints:
+     ast-grep run --kind string --lang ts sample.ts --json=compact
+   Example: source `"\\|"` is node text `"\\\\|"` in JSON; to match a
+   source-level escaped backslash (`\\`) followed by a non-backslash, the rule
+   regex needs FOUR regex backslashes, preferably in a YAML block scalar:
+     regex: >-
+       ^["'`]\\\\[^\\A-Za-z0-9$]
+   This is how `incomplete-string-escaping` catches both `"\\|"` and
+   `'\\"'`. Avoid shell here-doc probes for this class — shell/JSON escaping
+   can silently eat a backslash and make the rule look broken.
+
+⚠ `-js` twins: remember there are TWO execution surfaces.
+   <!-- verified: clients/dispatch/runners/ast-grep-napi.ts:205-216,450-455, c170d94b -->
+   - ast-grep CLI/LSP language-gates by `language:`. A `language: TypeScript`
+     rule is not enough for standalone `.js` coverage, so shipped user-facing
+     TS/JS rules that should fire under the ast-grep LSP usually need a `-js`
+     twin with `language: JavaScript` plus its own fixture.
+   - the in-process NAPI fallback (`ast-grep-napi.ts` — pi-lens source checkout
+     only, not present in the installed package) already DEDUPES by grammar
+     (#657): `ruleLanguageForFile` (`ast-grep-napi.ts:205-216`) maps each file
+     extension to its actual grammar, and the matcher (`:450-455`) skips any
+     `language:`-tagged rule whose tag doesn't match that grammar. A TS rule
+     and its JS twin no longer double-fire on the same file in fallback mode.
+   - **`-js` twins are needed only when the rule body itself is
+     grammar-divergent** (different node kinds/fields between the TS and JS
+     grammars). A grammar-agnostic body doesn't need a twin for fallback
+     coverage — the dedup above already scopes it correctly; ship a twin only
+     when standalone `.js` coverage through the ast-grep CLI/LSP baseline is
+     required (see the first bullet).
+   - **Grammar-divergent bodies** still need separate variants regardless:
+     e.g. `no-flag-argument` uses `required_parameter` in TS and
+     `assignment_pattern` in JS.
+
+✅ Node-kind facts (tree-sitter-typescript grammar — NOT the TS compiler / Roslyn):
+   - let / const  → `lexical_declaration`     (var is NOT here)
+   - var          → `variable_declaration`
+   - a regex literal's pattern text  → `regex_pattern`
+   - x[i] index access  → `subscript_expression`   (NOT element_access_expression)
+   - obj.prop access    → `member_expression`      (NOT property_access_expression)
+   - !x / -x / typeof x → `unary_expression`
+   - a ? b : c          → `ternary_expression`
+
+❌ Wrong-grammar kind names = silent dead rule. `element_access_expression`,
+   `property_access_expression`, `binary_operator`, etc. are TS-compiler/Roslyn names, not
+   tree-sitter's. napi REJECTS the whole rule ("invalid kind matcher") so it never runs.
+   Verify a kind exists before shipping:
+     node -e 'import("@ast-grep/napi").then(s=>{const r=s.ts.parse("x[i]").root();
+       const f=(n,k)=>{let c=n.kind()===k?1:0;for(const x of n.children())c+=f(x,k);return c};
+       console.log(f(r,"subscript_expression"))})'   # >0 means the kind is real
+
+✅ Test through the REAL runner from the pi-lens source checkout's repo root — it loads the actual shipped
+   rules from rules/ast-grep-rules/rules. Assert on diagnostic `rule` ids:
+     const res = await runner.run(ctx);  // ctx.filePath = temp .ts, cwd = repo  (pi-lens source checkout only — not present in the installed package)
+   For pattern/kind/regex-only rules (CLI-identical semantics) `ast-grep scan` is fine.
+
+✅ Before shipping any text/regex detector, FP-scan the codebase:
+     ast-grep scan -r <rule>.yml clients tools
+   Real safe variants bite (e.g. ReDoS: (ba+)+ is safe — a mandatory prefix makes
+   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)
+
+```
+❌ A parameter default is NOT a `$X = false` pattern. `pattern: $FLAG = false` parses as
+   an `assignment_expression` (statement context) and never matches a function parameter.
+   Match the PARAM NODE + its child literal instead, capturing the name for reuse:
+     # TS grammar
+     - kind: required_parameter
+       all:
+         - has: { field: pattern, pattern: $FLAG }
+         - has: { any: [ { kind: "true" }, { kind: "false" } ] }
+     # JS grammar (assignment_pattern, with fields left/right)
+     - kind: assignment_pattern
+       all:
+         - has: { field: left, pattern: $FLAG }
+         - has: { field: right, any: [ { kind: "true" }, { kind: "false" } ] }
+
+✅ Metavar consistency works ACROSS sibling clauses of an `all` — a metavar bound in one
+   `has` must match the SAME text everywhere it reappears. Use it to CORRELATE nodes, which
+   is what makes a structural rule precise:
+     all:
+       - has: { stopBy: end, kind: required_parameter, has: { field: pattern, pattern: $FLAG } }
+       - has: { stopBy: end, any: [ { pattern: "if ($FLAG) $$$" }, { pattern: "if (!$FLAG) $$$" } ] }
+   This fires ONLY when the function branches on the SAME param it declared boolean — a
+   boolean default that's never branched on, or a branch on a different var, won't match.
+
+❌ Two `has:` keys in one mapping silently OVERWRITE (YAML: last key wins). For multiple
+   descendant constraints use `all:` with a LIST of `has` entries, never repeated `has:`.
+
+✅ Prefer a high-precision structural guard over an unbounded denylist. Message-chain
+   (Demeter) floods on fluent/promise/builder chains; rather than denylist every fluent
+   method name, REQUIRE the chain's first calls to be accessors (`get*`/`is*`/`has*`) via
+   `constraints` regex — promise/fluent/builder methods aren't accessor-named, so they're
+   excluded by construction. Precision over recall.
+```

package/node_modules/pi-lens/skills/pi-lens-write-tree-sitter-rule/SKILL.md

@@ -6,7 +6,7 @@ description: Use when writing a new pi-lens tree-sitter query rule YAML file —
 # Writing a pi-lens tree-sitter Rule
 
 Drop path: `rules/tree-sitter-queries/<language>/<id>.yml`  
-Language dir is **lowercase**: `typescript` `javascript` `tsx` `python` `go` `rust` `java` `csharp` `kotlin` `ruby` `cpp` `c` `css`
+Language dir is **lowercase**: `typescript` `javascript` `tsx` `python` `go` `rust` `java` `csharp` `kotlin` `php` `ruby` `cpp` `c` `css`
 
 Project rules merge with built-ins (both run). To disable a language's built-ins: rename dir to `<lang>-disabled/`.
 
@@ -115,6 +115,8 @@ predicates:
    treeSitterRunner.run() via makeRealRunnerCtx (tests/support/real-runner-ctx.ts) —
    runQueryOnFile bypasses dispatch (skip_test_files, tiers, delta, rule cache).
    Template: tests/clients/dispatch/runners/tree-sitter-skip-test-files.test.ts.
+   (These test paths exist only in a pi-lens source checkout — the installed
+   npm package ships no tests/ directory.)
 
 ✅ JS files also run typescript/ rules (shared grammar) — one rule in
    rules/tree-sitter-queries/typescript/ covers BOTH .ts and .js. No -js copy needed.

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

@@ -7,6 +7,55 @@ 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
+- Added per-server `requestHeadersCommand` support for deriving fail-closed HTTP headers from the exact outbound request on every Streamable HTTP or SSE call. Thanks @kgreen18 for PR #353.
+- Added `settings.warnOnLargeDirectTools` to suppress the advisory for 75 or more resolved direct tools. Thanks @Roshvan for issue #358.
+
+### Changed
+- Refined request-header command result handling types without changing runtime behavior.
+
+### Fixed
+- Matched adapter-owned config and state paths to the host agent directory when Pi is rebranded, including its environment override and config directory. Thanks @mindplay-dk for issue #356.
+- Avoided O(tools²) cross-server tool-name collision scans at startup by skipping collision candidates when selectors are absent and sharing one indexed candidate set when `includeTools` or `excludeTools` is configured. Thanks @mjlbach for PR #357 and @cataldoc for issue #354.
+
 ## [2.25.0] - 2026-08-13
 
 ### Added