pi-lens 4.3.0 → 4.4.0

package/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-TLGFBM3F.js";
+import "../chunk-C2AUYXQH.js";
+import "../chunk-I3R7GKDR.js";
+import "../chunk-FC4RP4I2.js";
+import "../chunk-DFVMIKMQ.js";
+import "../chunk-TO6WL3GM.js";
+import "../chunk-7F72PXY2.js";
+import "../chunk-RPD5K5NC.js";
+import "../chunk-ZMOL6RQC.js";
+import "../chunk-I7SPGOWI.js";
+import "../chunk-AS44CFQ4.js";
+import "../chunk-7FBF7NPR.js";
+import "../chunk-HHYAELLJ.js";
+import "../chunk-V5PXFSZK.js";
+import "../chunk-YLF3PPT5.js";
+import "../chunk-JOLITGCC.js";
+import "../chunk-E2WFBRHM.js";
+import "../chunk-6VCD4VKZ.js";
+import "../chunk-F3P7VQ7H.js";
+import "../chunk-LSMJ6KBE.js";
+import "../chunk-3MED75HT.js";
+import "../chunk-3I5QFT3N.js";
+import "../chunk-TVN5N6GY.js";
+import "../chunk-ARFCXG7S.js";
+import "../chunk-OAXNDZJ7.js";
+import "../chunk-XIMYZ3JA.js";
+import "../chunk-B3I2UUT4.js";
+import "../chunk-DIULIWKU.js";
+import "../chunk-VDBPVIKD.js";
+import "../chunk-5W3R6LFT.js";
+import "../chunk-LW6XKDZQ.js";
+import "../chunk-Z54ZSOBZ.js";
+import "../chunk-TGPXLY2J.js";
+import "../chunk-QOZXJ4NA.js";
+import "../chunk-V7R425XG.js";
+import "../chunk-PAK6IDME.js";
+import "../chunk-GUOGVTCQ.js";
+import "../chunk-AJVLWNFN.js";
+import "../chunk-YGVYKNSN.js";
+import "../chunk-LNAKEO63.js";
+import "../chunk-Z3CCVDUB.js";
+import "../chunk-PWFHBTSF.js";
+import "../chunk-2BEMIWEW.js";
+import "../chunk-OQGFCZJ4.js";
+import "../chunk-RUOG5D2C.js";
+import "../chunk-U3VGR4VU.js";
+import "../chunk-NTUJEGDZ.js";
+import "../chunk-EOKRQ3SA.js";
+import "../chunk-WONERJTP.js";
+import "../chunk-22AVIGXS.js";
+import "../chunk-GVXA6CCE.js";
+import "../chunk-6QIUX4EP.js";
+import "../chunk-VHQLPIRJ.js";
+import "../chunk-VN2AXLEX.js";
+import "../chunk-BW5KFIQC.js";
+import "../chunk-QYF5S6P6.js";
+import "../chunk-5ZEJHV35.js";
+import "../chunk-DQ2NZ7C4.js";
+import "../chunk-VNMT7C64.js";
+import "../chunk-2EECBNC5.js";
+import "../chunk-N3YQJI6O.js";
+import "../chunk-O6TQT6RI.js";
+import "../chunk-5THXD6X5.js";
+import "../chunk-UK3CMEAL.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-NMABWBZN.js";
+import "../chunk-ABBOA7UD.js";
+import "../chunk-Q5U6FMDI.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/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-OQGFCZJ4.js";
+import "../chunk-RUOG5D2C.js";
+import "../chunk-U3VGR4VU.js";
+import "../chunk-NTUJEGDZ.js";
+import "../chunk-EOKRQ3SA.js";
+import "../chunk-WONERJTP.js";
+import "../chunk-22AVIGXS.js";
+import "../chunk-GVXA6CCE.js";
+import "../chunk-6QIUX4EP.js";
+import "../chunk-VHQLPIRJ.js";
+import "../chunk-VN2AXLEX.js";
+import "../chunk-BW5KFIQC.js";
+import "../chunk-QYF5S6P6.js";
+import "../chunk-5ZEJHV35.js";
+import "../chunk-DQ2NZ7C4.js";
+import "../chunk-VNMT7C64.js";
+import "../chunk-2EECBNC5.js";
+import "../chunk-N3YQJI6O.js";
+import "../chunk-O6TQT6RI.js";
+import "../chunk-5THXD6X5.js";
+import "../chunk-UK3CMEAL.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-ABBOA7UD.js";
+import "../chunk-Q5U6FMDI.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/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/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/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/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/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).
 
@@ -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… |

package/docs/configuration.md

@@ -24,7 +24,8 @@ everything LSP-related lives under an `lsp` namespace inside them.
         "name": "My Custom LSP",
         "extensions": [".myext"],
         "command": "my-lsp-server",
-        "args": ["--stdio"]
+        "args": ["--stdio"],
+        "covers": ["shellcheck"]
       }
     },
     "serverOverrides": {
@@ -45,6 +46,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/docs/environment-variables.md

@@ -219,10 +219,60 @@ 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_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`

package/docs/features.md

@@ -2,7 +2,7 @@
 
 ### LSP Support
 
-pi-lens includes **46 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server is not installed, pi-lens offers an interactive install prompt.
+pi-lens includes **48 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server is not installed, pi-lens offers an interactive install prompt.
 
 **LSP Idle Management:** LSP servers shut down after 240 seconds of inactivity (no files modified) to free resources. The timer resets when you resume editing, preventing cold-start penalties during active development.
 
@@ -19,7 +19,7 @@ pi-lens includes **46 language server definitions** (including four cross-cuttin
 - **`capabilities`** — shows which operations are supported by the active LSP server(s) for a file, read directly from the cached `initialize` response (no round-trip).
 - **Symbol column resolution** — passing `symbol: "myFunc"` instead of an exact `character` position resolves the correct column automatically. Use `symbol: "foo#2"` for the second occurrence of `foo` on the line.
 
-LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Typst (tinymist), Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
+LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Typst (tinymist), Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Shuck (zsh-aware shell language server), Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
 
 ### Formatters
 
@@ -109,6 +109,10 @@ the full behavior and honest limits.
 
 pi-lens builds a review graph (`file → symbol → dependency`) during session and uses it at turn end to render an impact cascade: which files were affected by a change and how diagnostics propagated through the dependency graph. Nodes track kind, language, and export status; edges track contains/imports/calls/references.
 
+### Knip at turn end and linked worktrees
+
+knip follows git ignore rules (`.gitignore` and `.git/info/exclude`) and nothing else, so linked worktrees that live inside the project (for example `.worktrees/*`) are walked as project files: on a pi-lens clone with six of them, 83 percent of the project paths knip saw were worktree files, and a scan took 10.9 s cold and 3.1 s warm instead of 2.6 s and 0.6 s. pi-lens drops their issues from the verdict, runs knip in the worktree that owns an edit, and stops waiting for a root whose last two scans both outlasted the turn_end budget (the knip row then reads `reason: "scan-exceeds-budget"` and the ledger counts `turn-end-knip-nested-worktrees`). It does not edit your repository: to remove the cost, add `/.worktrees/` (or your worktree directory) to the project's `.gitignore`.
+
 ### Read-Before-Edit Guard
 
 pi-lens enforces a **read-before-edit** policy on all file writes and edits. Before allowing a `write` or `edit` tool call on an existing file, it verifies that the agent has previously read sufficient context:
@@ -118,7 +122,7 @@ pi-lens enforces a **read-before-edit** policy on all file writes and edits. Bef
 - **Out-of-range block** — blocks if the edit target lines fall outside the ranges previously read, ensuring the agent cannot modify code it hasn't seen
 - **Snapshot validation** — covered edit ranges are hash-checked against the lines the agent actually saw at read time; stale-range edits are rejected even when range coverage exists. Hash capture covers reads up to 3 000 lines
 
-Coverage is tracked across multiple reads: two reads of lines 1–100 and 101–200 together satisfy a full-file write. Symbol-expanded reads (small reads silently widened to the enclosing symbol via tree-sitter) count toward coverage at the symbol level. Markdown files generate a warning instead of blocking (edits outside the section-expanded read range are warned, not silently passed). Plain-text (`.txt`) and log (`.log`) files remain fully exempt.
+Coverage is tracked across multiple reads: two reads of lines 1–100 and 101–200 together satisfy a full-file write. Symbol-expanded reads (small reads widened to the enclosing symbol via tree-sitter, labelled with a leading note) count toward coverage at the symbol level. Markdown files generate a warning instead of blocking (edits outside the section-expanded read range are warned, not silently passed). Plain-text (`.txt`) and log (`.log`) files remain fully exempt.
 
 Override for a single edit: `/lens-allow-edit <path>`
 
@@ -294,7 +298,7 @@ Late-joiners are a non-problem in-process — extensions activate at `session_st
 
 ### Opportunistic Read Expansion
 
-When the agent reads a small slice of a file (≤ 60 lines), pi-lens transparently expands the read to the full enclosing symbol (function, method, or class) using the tree-sitter AST. The agent receives the full symbol as context, and the read guard records symbol-level coverage so edits anywhere within that symbol pass without requiring the agent to have read every line individually. Expansion runs within a 200 ms budget and falls back silently on unsupported file types or parse failures.
+When the agent reads a small slice of a file (≤ 100 lines), pi-lens expands the read to the full enclosing symbol (function, method, or class) using the tree-sitter AST, or to the enclosing heading section of a Markdown file. The result starts with a `[pi-lens: read widened ...]` note naming the requested and the returned lines; a `limit` above 100 reads the exact range. Expansion is off with the read guard (`--no-read-guard` or `readGuard.enabled=false`). The agent receives the full symbol as context, and the read guard records symbol-level coverage so edits anywhere within that symbol pass without requiring the agent to have read every line individually. Expansion runs within a 200 ms budget and falls back silently on unsupported file types or parse failures.
 
 Supported: TypeScript, TSX, JavaScript, JSX, Python, Go, Rust, Ruby, Java, Kotlin, Dart, Elixir, C, C++, C#, PHP, Swift, Lua, OCaml, Zig, Bash.
 

package/docs/globalconfig.md

@@ -33,6 +33,7 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
 | `--lens-compact-tool-line` | `ui.compactToolLine` | `false` |
 | `--lens-compact-lsp-status` | `ui.compactLspStatus` | `false` |
 | `--lens-hide-lsp-status` | `ui.hideLspStatus` | `false` |
+| `--lens-compact-widget` | `ui.compactWidget` | `false` |
 | `--no-lazy-tools` | `tools.lazy` | `true` |
 | `--lens-turn-end-madge` | `turnEnd.madge.enabled` | `false` |
 | `--no-knip` | `knip.enabled` | `true` |