@herbertgao/pi-extensions 2026.10.1 → 2026.10.3

package/node_modules/pi-lens/dist/mcp/worker.js

@@ -1,46 +1,105 @@
 #!/usr/bin/env node
-/**
- * pi-lens MCP `fresh`-mode worker.
- *
- * The review-loop honesty guarantee: the MCP server is long-lived, so after a
- * commit + rebuild it still holds the OLD code in memory. This worker is a
- * short-lived child the server forks per `fresh` analysis — a brand-new `node`
- * process loads the *freshly built* `analyze.js` (and its dispatch graph) from
- * disk, so the measurement reflects the latest commit, not the server's stale
- * image. stdout carries exactly one JSON `McpAnalyzeResult`; diagnostics go to
- * stderr.
- */
-import { analyzeFile } from "../clients/mcp/analyze.js";
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  analyzeFile
+} from "../chunk-ZZUFZUQZ.js";
+import "../chunk-ZOEYVXSV.js";
+import "../chunk-KJN4IOEJ.js";
+import "../chunk-FC4RP4I2.js";
+import "../chunk-YLN4K6WD.js";
+import "../chunk-J3FZR3YY.js";
+import "../chunk-5JHXUETW.js";
+import "../chunk-3MRXIJ6I.js";
+import "../chunk-TA5L5KWQ.js";
+import "../chunk-FGALODG3.js";
+import "../chunk-OC7LYAU5.js";
+import "../chunk-NFXP47RV.js";
+import "../chunk-MGIWSROG.js";
+import "../chunk-WSEWKCXU.js";
+import "../chunk-MQA2YBAH.js";
+import "../chunk-TQFBZVCG.js";
+import "../chunk-WATC3IQR.js";
+import "../chunk-OYOB3ZFG.js";
+import "../chunk-XHSCVSOL.js";
+import "../chunk-V5MEBST3.js";
+import "../chunk-3MED75HT.js";
+import "../chunk-IMSQR4WO.js";
+import "../chunk-MTDRLSI7.js";
+import "../chunk-OZJINN4O.js";
+import "../chunk-3JSEWUWI.js";
+import "../chunk-XIMYZ3JA.js";
+import "../chunk-IQZXOZ7S.js";
+import "../chunk-LNOMA3MP.js";
+import "../chunk-U52SAGRM.js";
+import "../chunk-5W3R6LFT.js";
+import "../chunk-UEAHAMEI.js";
+import "../chunk-Z54ZSOBZ.js";
+import "../chunk-KJCWXUUS.js";
+import "../chunk-QOZXJ4NA.js";
+import "../chunk-6XX5HCLK.js";
+import "../chunk-S6AMWKPC.js";
+import "../chunk-F5VLZHUW.js";
+import "../chunk-AXKPQ6ZI.js";
+import "../chunk-7BX5DWSA.js";
+import "../chunk-IUKPRZER.js";
+import "../chunk-Z3CCVDUB.js";
+import "../chunk-XGUL4SLQ.js";
+import "../chunk-2BEMIWEW.js";
+import "../chunk-LD7WFTRX.js";
+import "../chunk-IUR76K6A.js";
+import "../chunk-T4QZ6FEH.js";
+import "../chunk-D6YF5HKX.js";
+import "../chunk-CMU4RMJB.js";
+import "../chunk-O7HZX7CA.js";
+import "../chunk-VYKKMYVT.js";
+import "../chunk-BNKLYOOO.js";
+import "../chunk-USHG4DLH.js";
+import "../chunk-H5EV3VMF.js";
+import "../chunk-T54VJRAD.js";
+import "../chunk-BW5KFIQC.js";
+import "../chunk-QYF5S6P6.js";
+import "../chunk-64LU2OVH.js";
+import "../chunk-N2IRDBZI.js";
+import "../chunk-Z6BB4JLQ.js";
+import "../chunk-2EECBNC5.js";
+import "../chunk-7ELY2CSM.js";
+import "../chunk-34OCDWOS.js";
+import "../chunk-3PNFWVHT.js";
+import "../chunk-VSMJK3ZJ.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-UGSMCQ4D.js";
+import "../chunk-ABBOA7UD.js";
+import "../chunk-G3RLJYA2.js";
+import "../chunk-NXL4FFQQ.js";
+
+// dist/mcp/worker.js
 function arg(name) {
-    const prefix = `--${name}=`;
-    const found = process.argv.find((value) => value.startsWith(prefix));
-    return found ? found.slice(prefix.length) : undefined;
+  const prefix = `--${name}=`;
+  const found = process.argv.find((value) => value.startsWith(prefix));
+  return found ? found.slice(prefix.length) : void 0;
 }
 async function main() {
-    const file = arg("file");
-    const cwd = arg("cwd") ?? process.cwd();
-    if (!file) {
-        process.stderr.write("worker: --file is required\n");
-        process.exit(2);
+  const file = arg("file");
+  const cwd = arg("cwd") ?? process.cwd();
+  if (!file) {
+    process.stderr.write("worker: --file is required\n");
+    process.exit(2);
+  }
+  let flags;
+  const flagsRaw = arg("flags");
+  if (flagsRaw) {
+    try {
+      flags = JSON.parse(flagsRaw);
+    } catch {
+      process.stderr.write("worker: --flags must be valid JSON\n");
+      process.exit(2);
     }
-    let flags;
-    const flagsRaw = arg("flags");
-    if (flagsRaw) {
-        try {
-            flags = JSON.parse(flagsRaw);
-        }
-        catch {
-            process.stderr.write("worker: --flags must be valid JSON\n");
-            process.exit(2);
-        }
-    }
-    const result = await analyzeFile(file, cwd, { flags });
-    // Flush before exiting — a bare process.exit can truncate a piped write. The
-    // explicit exit is needed because spawned LSP/runner handles would otherwise
-    // keep the event loop alive.
-    process.stdout.write(JSON.stringify(result), () => process.exit(0));
+  }
+  const result = await analyzeFile(file, cwd, { flags });
+  process.stdout.write(JSON.stringify(result), () => process.exit(0));
 }
 main().catch((err) => {
-    process.stderr.write(`worker failed: ${err.message}\n`);
-    process.exit(1);
+  process.stderr.write(`worker failed: ${err.message}
+`);
+  process.exit(1);
 });

package/node_modules/pi-lens/dist/probes/installer.js

@@ -0,0 +1,135 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  GITHUB_TOOLS,
+  TOOLS,
+  _peekEnsureInFlightForTesting,
+  acquireManagedInstallGate,
+  checkAllTools,
+  checkProbeCache,
+  ensureTool,
+  findManagedToolBinary,
+  flushProbeCache,
+  getAllToolStatuses,
+  getInstallAttempt,
+  getInstallFailureReason,
+  getLastEnsureResolutionSource,
+  getManagedToolsDir,
+  getRefreshableManagedNpmTools,
+  getRefreshableManagedTools,
+  getToolEnvironment,
+  getToolInstallStrategy,
+  getToolPath,
+  getToolVerificationTimeout,
+  installTool,
+  invalidateManagedToolResolution,
+  isCommandAvailable,
+  isKnownToolId,
+  isLspTransportRequiredError,
+  isManagedToolPresent,
+  isSpawnableCommand,
+  isToolInstalled,
+  npmToolNeedsPostinstall,
+  packageEntryVerification,
+  parsePinnedVersion,
+  pickReleaseAsset,
+  pipCommandCandidates,
+  pipScriptsDir,
+  refreshManagedTool,
+  resetPathWalkMemo,
+  resetProbeCacheStateForTesting,
+  resetResolvedPathCache,
+  resolveArchiveKind,
+  resolveArchiveUrl,
+  resolveDerivedHashiCorpReleaseAsset,
+  resolveGitHubArchiveBinaryCandidates,
+  resolveGitHubAsset,
+  resolveGitHubAssetLauncher,
+  resolveGitHubInstalledBinaryName,
+  resolveManagedNpmBinPath,
+  resolvePlatformPackageBinary,
+  swapExtractedDir,
+  updateProbeCache,
+  userBaseProbeResult,
+  verifyNpmPackageEntry,
+  verifyToolBinary,
+  wasLastResolveTransient
+} from "../chunk-LD7WFTRX.js";
+import "../chunk-IUR76K6A.js";
+import "../chunk-T4QZ6FEH.js";
+import "../chunk-D6YF5HKX.js";
+import "../chunk-CMU4RMJB.js";
+import "../chunk-O7HZX7CA.js";
+import "../chunk-VYKKMYVT.js";
+import "../chunk-BNKLYOOO.js";
+import "../chunk-USHG4DLH.js";
+import "../chunk-H5EV3VMF.js";
+import "../chunk-T54VJRAD.js";
+import "../chunk-BW5KFIQC.js";
+import "../chunk-QYF5S6P6.js";
+import "../chunk-64LU2OVH.js";
+import "../chunk-N2IRDBZI.js";
+import "../chunk-Z6BB4JLQ.js";
+import "../chunk-2EECBNC5.js";
+import "../chunk-7ELY2CSM.js";
+import "../chunk-34OCDWOS.js";
+import "../chunk-3PNFWVHT.js";
+import "../chunk-VSMJK3ZJ.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-ABBOA7UD.js";
+import "../chunk-G3RLJYA2.js";
+import "../chunk-NXL4FFQQ.js";
+export {
+  GITHUB_TOOLS,
+  TOOLS,
+  _peekEnsureInFlightForTesting,
+  acquireManagedInstallGate,
+  checkAllTools,
+  checkProbeCache,
+  ensureTool,
+  findManagedToolBinary,
+  flushProbeCache,
+  getAllToolStatuses,
+  getInstallAttempt,
+  getInstallFailureReason,
+  getLastEnsureResolutionSource,
+  getManagedToolsDir,
+  getRefreshableManagedNpmTools,
+  getRefreshableManagedTools,
+  getToolEnvironment,
+  getToolInstallStrategy,
+  getToolPath,
+  getToolVerificationTimeout,
+  installTool,
+  invalidateManagedToolResolution,
+  isCommandAvailable,
+  isKnownToolId,
+  isLspTransportRequiredError,
+  isManagedToolPresent,
+  isSpawnableCommand,
+  isToolInstalled,
+  npmToolNeedsPostinstall,
+  packageEntryVerification,
+  parsePinnedVersion,
+  pickReleaseAsset,
+  pipCommandCandidates,
+  pipScriptsDir,
+  refreshManagedTool,
+  resetPathWalkMemo,
+  resetProbeCacheStateForTesting,
+  resetResolvedPathCache,
+  resolveArchiveKind,
+  resolveArchiveUrl,
+  resolveDerivedHashiCorpReleaseAsset,
+  resolveGitHubArchiveBinaryCandidates,
+  resolveGitHubAsset,
+  resolveGitHubAssetLauncher,
+  resolveGitHubInstalledBinaryName,
+  resolveManagedNpmBinPath,
+  resolvePlatformPackageBinary,
+  swapExtractedDir,
+  updateProbeCache,
+  userBaseProbeResult,
+  verifyNpmPackageEntry,
+  verifyToolBinary,
+  wasLastResolveTransient
+};

package/node_modules/pi-lens/dist/workers/project-snapshot-persist-worker.js

@@ -0,0 +1,22 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  fingerprintProjectSnapshotJson
+} from "../chunk-2BEMIWEW.js";
+import {
+  serveGzipStageWorker
+} from "../chunk-UOPVJQ4N.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-NXL4FFQQ.js";
+
+// dist/clients/project-snapshot-persist-worker.js
+function semanticSnapshotFingerprint(request, body) {
+  return fingerprintProjectSnapshotJson(body, request.generatedAt);
+}
+serveGzipStageWorker((request) => ({
+  id: request.id,
+  generation: request.generation,
+  stagePath: request.stagePath
+}), {
+  semanticFingerprint: semanticSnapshotFingerprint,
+  skipIfFingerprints: (request) => request.priorFingerprints
+});

package/node_modules/pi-lens/dist/workers/review-graph-persist-worker.js

@@ -0,0 +1,15 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  serveGzipStageWorker
+} from "../chunk-UOPVJQ4N.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-NXL4FFQQ.js";
+
+// dist/clients/review-graph/persist-worker.js
+serveGzipStageWorker((request) => ({
+  id: request.id,
+  cwd: request.cwd,
+  generation: request.generation,
+  stagePath: request.stagePath,
+  elements: request.elements
+}));

package/node_modules/pi-lens/docs/agent-guide.md

@@ -102,7 +102,7 @@ not clean**:
 
 | Label you may see | What it means | What you must NOT do |
 |---|---|---|
-| **`unconfirmed`** | A push-only/silent-on-clean LSP server returned empty; emptiness could not be *proven* clean. | Don't report the file as clean. |
+| **`unconfirmed`** | An LSP result that could not be *proven* clean: a push-only/silent-on-clean server returned empty; an auxiliary scanner did not answer in time; or the file has no project root for a server that needs one (rust-analyzer, csharp-ls/OmniSharp, FSAutocomplete) and the line names the missing marker. | Don't report the file as clean. |
 | **`cold` (not applicable / unavailable this run)** | A heavyweight analyzer (knip/jscpd/madge/gitleaks/govulncheck/trivy/dead-code) didn't contribute. | Don't fold its silence into "no issues." |
 | **`partial` / `truncated` / file-cap** | A walk/scan hit a file cap or coverage limit; results are a partial view. | Don't treat as whole-project coverage. |
 | **`stale`** | A cached diagnostic's file changed on disk since the scan. Secrets findings demote to `🔑 ACTION NEEDED` advisory with the line number withheld, never silently dropped; govulncheck keeps the CVE and drops only the cached line. | Don't trust the stale value or its line number. Re-scan to confirm. |
@@ -128,6 +128,10 @@ is blocking when `semantic === "blocking"`, else it falls back to severity):
   a blocker does, but it is not "no action required" like an advisory either —
   the finding is unverified, not dismissed. Re-run a secrets scan to confirm
   or clear it.
+- **⏱️ Late runner diagnostics** — a slow (collect-later) runner's findings arrive at
+  turn end on the advisory channel, so they never gate `git commit`/`git push`;
+  when one is blocking it reads "blocking: fix before continuing" instead of
+  "no action required", and a runner that timed out or errored says so separately.
 - **Advisory** — informational (🟡 warnings, 📜 license notes, style/hygiene).
   Address when relevant; they do not gate completion.
 
@@ -147,7 +151,9 @@ Don't try to route around it — clear the blockers, then commit. The guard is s
 pi-lens monitors that you **read a file before editing it** (`clients/read-guard.ts`).
 Edits fail or warn when:
 
-1. **Zero-read** — you never read the file this conversation.
+1. **Zero-read** — you never read the file this conversation, or your write
+   record of it expired after 30 idle minutes (the block says "the earlier
+   write record ... expired"). Read it again.
 2. **Stale** — the file changed on disk since you read it (content-hash checked).
 3. **Out-of-range** — your edit target wasn't covered by any read.
 
@@ -163,8 +169,11 @@ Helpful mechanics you can rely on:
 
 - **Coverage accumulates** across reads — two reads (lines 1–100 and 101–200) together
   cover a full-file write.
-- **Symbol expansion** — small reads (≤ ~60 lines) are silently widened to the
-  enclosing function/method/class, and coverage is recorded at symbol level.
+- **Symbol expansion** — small reads (≤ 100 lines) are widened to the enclosing
+  function/method/class (or Markdown section), and coverage is recorded at
+  symbol level. The result starts with a `[pi-lens: read widened ...]` note
+  naming the requested and the returned lines; ask for `limit` above 100 for
+  the exact range. It is off with the read guard (`--no-read-guard`).
 - `read_symbol` / `read_enclosing` reads count as edit coverage for that symbol range.
 - Markdown warns instead of blocking; `.txt`/`.log` are exempt.
 - Escape hatch (human): `/lens-allow-edit <path>` arms one exemption.

package/node_modules/pi-lens/docs/agent-tools.md

@@ -39,6 +39,48 @@ actually sent: `usage tokens=<n> elapsed-ms=<n> bytes=<n> truncated=<true|false>
 A rejected call (e.g. MCP's "Unknown or disabled tool") is rendered through the
 same gate rather than bypassing it.
 
+**MCP argument handling (#3749).** The MCP `tools/call` dispatcher compares the
+call's argument keys with the `inputSchema` the tool advertises in `tools/list`
+(`findIgnoredArguments`, `mcp/tool-arguments.ts`), once, for every tool. An
+undeclared top-level key is never silently dropped (keys inside a nested
+object argument such as `callHierarchyItem`, `rule` or `flags` are not checked):
+
+- the result's first line is ``Ignored unknown argument(s) for <tool>: `key`
+  (did you mean `nearest`?). They had no effect on this call.`` (the suggestion
+  appears only when a declared key is near), followed by the tool's own result;
+- the result carries `structuredContent: { ignoredArguments: [...],
+  ignoredArgumentCount: N }` (at most 8 keys, each cut at 64 characters; the
+  count is exact);
+- when an ignored key leaves the call without something it needed, the tool
+  does not run and the result is an error whose first line is the same
+  sentence, followed by `Not run: ...`. That is the case when a
+  schema-`required` input is missing (``Not run: required argument(s) `file`
+  missing.``), or when the ignored key is a declared parameter the call did not
+  send, written another way: a case or punctuation variant, a plural, or a key
+  whose last word is the parameter (`filePath`, `file_path` and `Path` for the
+  optional `path` of `pilens_diagnostics`: ``Not run: `filePath` looks like a
+  mistyped `path`, which was not sent.``). The exact predicate is named in
+  [public-api-stability.md](public-api-stability.md). Anything looser (a typo,
+  an abbreviation, `files` for `maxLspFiles`, or a count, flag or output key
+  such as `maxFiles`, `includeFiles`, `outFile` or `cwdPath` where `cwd` is
+  declared) stays a warning;
+- each such call adds one count to the `mcp-ignored-arguments` degradation
+  group (subject: the tool name), visible in `pilens_health`.
+
+Unknown keys are still not rejected outright: a caller that passes an extra key
+that is not a declared parameter written another way (or that comes with the
+parameter it resembles) keeps getting its answer, with the report above. Hard rejection is a change to the
+public MCP input contract and is owned by the stability policy
+([public-api-stability.md](public-api-stability.md)). A schema declares only
+what the tool reads, so `cwd` on a tool whose handler never reads it
+(`pilens_health`, `pilens_latency`, `pilens_session_end`, `pilens_rebuild`;
+the dispatcher uses it only to decide whether the tool is enabled) is reported
+as an ignored key, a warning, because nothing it resembles is missing. The
+retired `pilens_lsp_diagnostics` name is checked against `pilens_diagnostics`'s
+schema; the retired `pilens_ast_grep_dump` name has no schema and is not
+checked. A non-object `arguments` is a JSON-RPC `-32602` error; absent, `null`
+and `[]` mean no arguments.
+
 ## Per-edit
 
 - **`lens_diagnostics`** — Session-cache or LSP-probe diagnostic state, selected

package/node_modules/pi-lens/docs/ast-grep_rules_catalog.md

@@ -2,7 +2,7 @@
 
 <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
 
-pi-lens bundles **482 enabled** ast-grep rules (298 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
+pi-lens bundles **483 enabled** ast-grep rules (299 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
 
 See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `rules/ast-grep-rules/rules/` (pi-lens), `rules/ast-grep-rules/coderabbit/rules/` (vendored).
 
@@ -231,7 +231,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `prefer-structured-clone-js` | warning | no | pi-lens | Use structuredClone() instead of JSON.parse(JSON.stringify()) for deep cloning |
 | `strict-equality-js` | warning | yes | pi-lens | Use === instead of == |
 | `strict-inequality-js` | warning | yes | pi-lens | Use !== instead of != |
-| `throw-new-error-js` | error | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
+| `throw-new-error-js` | warning | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
 | `unchecked-throwing-call-js` | error | no | pi-lens | $CALL without try/catch — throws on invalid input |
 | `weak-rsa-key-js` | error | no | pi-lens | Weak RSA key size — use at least 2048 bits |
 
@@ -436,10 +436,11 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `redundant-usestate-type` | info | yes | pi-lens | `useState<TYPE>(...)` where TYPE is a primitive redundant — TS can infer it from the initial value |
 | `unnecessary-react-hook` | warning | no | pi-lens | Function with a `use*` name does not call any other React hook — rename to a plain function |
 
-### TypeScript (134)
+### TypeScript (135)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
+| `advisory-registry-subset` | info | no | pi-lens | Hand-enumerated registry subset — explain the excluded ids or use the registry |
 | `array-callback-return` | error | no | pi-lens | return statements must be enforced in callbacks of array methods |
 | `consistent-existence-index-check` | warning | no | pi-lens | Use .includes() instead of .indexOf() for existence checks |
 | `detect-angular-sce-disabled-typescript` | warning | no | CodeRabbit | $sceProvider is set to false. Disabling Strict Contextual escaping (SCE) in an AngularJS application could provide additional attack surfac… |
@@ -546,7 +547,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `strict-equality` | warning | yes | pi-lens | Use === instead of == |
 | `strict-inequality` | warning | yes | pi-lens | Use !== instead of != |
 | `switch-without-default` | warning | no | pi-lens | switch has no default clause — values matching no case are silently ignored; add a default (even one that throws) |
-| `throw-new-error` | error | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
+| `throw-new-error` | warning | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
 | `ts-array-concat-spread` | warning | no | pi-lens | arr.concat([...items]) - use arr.push(...items) or [...arr, ...items] |
 | `ts-array-every-some` | warning | no | pi-lens | arr.map(x => x.prop).every(Boolean) - use arr.every(x => !!x.prop) |
 | `ts-boolean-return-if-else` | warning | no | pi-lens | if/else returning true/false - simplify to return the condition directly |

package/node_modules/pi-lens/docs/configuration.md

@@ -10,6 +10,14 @@ There are **two** pi-lens config files:
 Both files have the same shape, with one exception noted below the example:
 everything LSP-related lives under an `lsp` namespace inside them.
 
+The editor-facing JSON Schema is published at
+[`docs/schema/pi-lens-config-v1.json`](schema/pi-lens-config-v1.json). LSP
+server entries also accept canonical argv arrays, optional `name` (defaulting
+to the map id), `enabled`, `role` (`language` or `auxiliary`), `args`, and
+`rootMarkers`. These new fields are experimental; reserved role, root-policy,
+and timing semantics are inert until their planned catalog slices land, so this
+schema slice does not change server launch behavior.
+
 ```jsonc
 {
   "$schema": "https://raw.githubusercontent.com/apmantza/pi-lens/master/docs/schema/pi-lens-config-v1.json",
@@ -23,8 +31,8 @@ everything LSP-related lives under an `lsp` namespace inside them.
       "my-server": {
         "name": "My Custom LSP",
         "extensions": [".myext"],
-        "command": "my-lsp-server",
-        "args": ["--stdio"]
+        "command": ["my-lsp-server", "--stdio"],
+        "covers": ["shellcheck"]
       }
     },
     "serverOverrides": {
@@ -45,6 +53,24 @@ names include `ast_grep_search`, `ast_grep_replace`, `ast_grep_outline`,
 lifecycle tools `session_start`, `turn_end`, and `session_end` remain enabled
 because their host protocols require them.
 
+### `lsp.servers.<id>.covers` — declaring which runners a custom server subsumes
+
+A custom server entry accepts an optional `covers` array naming dispatch
+runner ids the server subsumes: while that server is a file's selected primary
+language server, the runners it names defer to the warm lane instead of also
+running as CLI scans. `covers: ["shellcheck"]` on a shell LSP, for example,
+makes the ShellCheck runner report a skip (`covered-by-primary`) for the files
+that server covers instead of double-reporting the same findings.
+
+- Values are runner ids (`shellcheck`, `shfmt`, `taplo`, … — the dispatch
+  registry's ids). A member pi-lens does not recognize is dropped with a
+  `PILENS_CFG_0005` warning naming the entry; the server itself still
+  registers and runs its language-server lane.
+- An empty `covers` array claims nothing and is recorded as configured.
+- Across files, the nearest tier that sets the field supplies the whole
+  array — a project value replaces the user-level value for that server;
+  fields are never united across tiers.
+
 **Some settings are global-only.** A handful of switches — `lsp.enabled`
 (`--no-lsp`), `tests.enabled`, `delta.enabled` and the other session-wide
 toggles — are decided once for the machine, not per project, so writing one in a

package/node_modules/pi-lens/docs/custom-rules.md

@@ -1,6 +1,6 @@
 # Custom Rules
 
-pi-lens picks up project-local rules automatically alongside its built-ins.
+pi-lens picks up project-local and user-level rules automatically alongside its built-ins.
 Drop YAML files in the right directory and they are active on the next file dispatch — no config required.
 
 > For the full list of bundled rules per language, see the generated catalogs:
@@ -20,7 +20,30 @@ your-project/
         my-rule.yml        ← ast-grep rule, overrides built-in with same id
 ```
 
-Project ast-grep rules are fingerprinted by relative path and contents, so in-place edits, renames, additions, and removals take effect within one tool call even when mtimes are preserved. Tree-sitter rules retain their directory-mtime cache.
+Both rule families are fingerprinted by relative path and contents, so in-place edits, renames, additions, and removals are picked up without a restart, even when mtimes are preserved.
+
+### When an edit takes effect
+
+A per-file dispatch reads the rule corpus fresh every time: its cache key is a
+content fingerprint of every rule file the language's rule set is built from,
+so an edit, addition, or removal is live on the next dispatched file.
+
+Whole-project surfaces — a project scan and a structural search — reuse a
+corpus fingerprint computed once per turn, so a rule edit lands on the next
+turn, or immediately if any file is dispatched in between (a dispatch
+republishes the fresh fingerprint for the rest of that turn). This is what
+keeps a warm scan at the cost of a string comparison instead of re-reading
+every rule file on every call.
+
+### User-level rules
+
+Rules shared across projects live under the relocatable machine-data directory:
+`<PI_LENS_HOME>/rules/` (or the platform default pi-lens directory when
+`PI_LENS_HOME` is unset). Use the same `tree-sitter-queries/` and
+`ast-grep-rules/` layout shown above. Precedence is project > user > bundled;
+when rule IDs collide, the higher tier wins and the lower definition is
+shadowed from execution. User rules are part of the same fingerprints as
+project rules, so they follow the same timing above.
 
 ---
 

package/node_modules/pi-lens/docs/environment-variables.md

@@ -104,12 +104,14 @@ without changing the steady-state behaviour of an interactive session.
 
 ### `PI_LENS_STARTUP_SCAN_VERDICT_TTL_MS`
 
-How long (ms) a persisted `too-many-source-files` startup-scan verdict is
-trusted before the source-file count is re-walked (default 24h). The verdict
-is cached in the project snapshot so repeated `pi -p` runs in a very large
-repo skip the counting walk entirely; a repo that shrinks below the threshold
-recovers when the TTL expires. Other verdicts use content-based freshness and
-ignore this setting.
+How long (ms) a persisted size-skip startup-scan verdict (`too-many-source-files`
+or `too-many-entries`) is trusted before the project is re-walked (default
+24h). The verdict is cached in the project snapshot so repeated `pi -p` runs in
+a very large repo skip the counting walk entirely; a repo that shrinks below
+the threshold recovers when the TTL expires. The verdict also records the
+bounds that produced it (`maxProjectFiles`, `PI_LENS_STARTUP_SCAN_MAX_ENTRIES`),
+so raising either one invalidates it at once and the next session re-walks.
+Other verdicts use content-based freshness and ignore this setting.
 
 ## Scale and limits
 
@@ -144,6 +146,24 @@ Minimum wall-clock budget (ms) for every dispatch runner; the effective timeout
 is `max(runner budget, floor)`. **Default:** `0` (no floor). Also settable via
 the `dispatch.runnerTimeoutFloorMs` config key, which wins when both are set.
 
+### `PI_LENS_WORD_INDEX_MEMO_BACKSTOP_MS`
+
+Backstop (ms) for the word index's serialized memo, which is also its
+incremental-serialize cache: it is kept while a run edits (so each per-edit
+persist stays O(dirty tokens)) and released once per run at `agent_settled`.
+The backstop releases it when no persist has refreshed it for this long, for a
+host that never emits `agent_settled` and for a stalled run. It is re-armed by
+every serialize and never keeps the process alive. **Default:** `600000` (10
+minutes). `0`, a negative or a non-numeric value means the default (a backstop
+that fired at once would switch the memo off), and a value above `2147483647`
+(about 24.8 days, Node's largest timer delay) is clamped to it. The default is
+deliberately conservative: the maintainer's
+`latency.log` held only two intra-run gaps between `project_snapshot_persist`
+records (5.8 s), too few to derive a percentile. A release leaves one
+`word_index_memo_released` row in `latency.log` (`trigger`: `settle`,
+`post_settle_persist` or `backstop`). Releasing costs the next persist a full
+re-serialize.
+
 ## Install control
 
 ### `PI_LENS_DISABLE_LSP_INSTALL`
@@ -219,10 +239,68 @@ Several in-memory caches release their contents after a period of inactivity so
 long-running session does not retain hydrated state indefinitely. Each has an
 env-tunable window; all default to 20 minutes (`1200000` ms).
 
+### V8 heap ceiling for long pi sessions
+
+If a long pi session with pi-lens approaches the memory available on its host,
+set a V8 old-space ceiling before launching pi:
+
+```sh
+NODE_OPTIONS=--max-old-space-size=700 pi
+```
+
+`700` MB is a diagnosis-based starting point, not a universal project limit. In
+the #1999 investigation, the capped and uncapped runs had the same settled live
+heap (about 240 MB), while the cap reduced peak RSS from about 1,870 MB to
+961 MB at the same point and did not add wall time in that run. GC CPU cost was not measured separately, so treat the value as a starting point to tune on your own workload. The measured
+long-session parent heaps were otherwise about 1.3–1.8 GiB, so increase the
+ceiling for a workload that needs more headroom. A ceiling that is too low can
+make Node abort with an out-of-memory crash; it does not reduce the live state
+that the workload requires.
+
+This setting applies to that pi launch only. To make it persistent for a shell,
+export it first, then launch pi:
+
+```sh
+export NODE_OPTIONS=--max-old-space-size=700
+pi
+```
+
+To observe what the session is using, inspect `memory_sample` records in
+`~/.pi-lens/latency.log`. Compare `process.heapUsedBytes` with the settled
+`process.heapSettledBytes`, and check `process.externalNonBufferBytes` for
+external memory that is not ArrayBuffer memory. The latest asynchronous
+persist-worker readings are under
+`subsystems.persistWorkers.reviewGraph` and
+`subsystems.persistWorkers.projectSnapshot`. If `/lens-health` exposes the
+same memory fields in a future pi-lens version, use those current readings
+there as well; the current `/lens-health` output does not render them. The
+complete field definitions are in
+[`pi-lens-monitor.md`](pi-lens-monitor.md#memory-samples).
+
+### `PI_LENS_LSP_IDLE_EVICT_MS`
+
+Shared idle window (ms) after which every language-service client whose registry
+`idleEviction` is `transparent` releases its hydrated program and shuts down,
+rebuilding transparently on the next request. Servers declared `resident` or
+`unmeasured` are never evicted. Which servers are declared which way, and the
+nightly measurement behind each declaration, is in
+[`lsp-idle-eviction.md`](lsp-idle-eviction.md).
+When unset or invalid, `PI_LENS_TS_IDLE_EVICT_MS` (below) is read.
+**Default:** 20 minutes (`1200000`).
+
+### `PI_LENS_EPHEMERAL_LSP_IDLE_EVICT_MS`
+
+Idle window (ms) for language-service clients whose workspace is inside a
+temporary or ephemeral Git checkout. This overrides the shared window above
+for those roots; when unset or invalid, the default is 60 seconds (`60000`).
+The nightly idle-eviction measurement temporarily sets this variable alongside
+`PI_LENS_LSP_IDLE_EVICT_MS` so both root policies are measured.
+
 ### `PI_LENS_TS_IDLE_EVICT_MS`
 
-Idle window (ms) after which TypeScript language-service clients release their
-hydrated program and shut down, rebuilding transparently on the next request.
+The original, TypeScript-named spelling of the same window, retained for
+compatibility with existing configuration. It has exactly the semantics above
+and is ignored when `PI_LENS_LSP_IDLE_EVICT_MS` holds a valid value.
 **Default:** 20 minutes (`1200000`).
 
 ### `PI_LENS_WORD_INDEX_IDLE_EVICT_MS`