@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/pi-lens/dist/clients/lsp/launch.js

@@ -15,7 +15,7 @@ import { getGlobalPiLensDir } from "../file-utils.js";
 import { isFullyQualified } from "../path-utils.js";
 import { findGlobalBinary } from "../package-manager.js";
 import { redactSecrets } from "../redact/secrets.js";
-import { classifySpawnFailure, SpawnFailureError, } from "../safe-spawn.js";
+import { classifySpawnFailure, SpawnFailureError } from "../safe-spawn.js";
 import { getRubyVersionDirNamesAsync } from "./ruby-drive-dirs.js";
 const isWindows = process.platform === "win32";
 /**
@@ -176,7 +176,10 @@ export function isCmdShimValid(cmdPath) {
     try {
         const content = fs.readFileSync(cmdPath, "utf-8");
         // npm cmd shim pattern: "%~dp0\..\<relpath>" or "%~dp0/<relpath>"
-        // biome-ignore format: regex char-class \- must stay escaped — formatter strips it
+        // The `-` ends the char class, where it is a literal and needs no escape.
+        // oxfmt formats this repository (#1844) and rewrites no regex literal, so
+        // this line needs no suppression; the directive oxfmt honors, if one is
+        // ever needed here, is `// prettier-ignore`.
         const match = content.match(/"%~dp0[/\\]\.\.[/\\]((?:[\w./@-]|\\)+\.(?:mjs|cjs|js))"/i);
         if (!match)
             return true; // non-npm shim — let it through
@@ -205,7 +208,8 @@ function bypassPs1OnWindows(ps1Path, args) {
     // npm-generated PS1 pattern: "$basedir/../<package>/bin/cli.js"
     try {
         const content = fs.readFileSync(ps1Path, "utf-8");
-        // biome-ignore format: regex char-class \- must stay escaped — formatter strips it
+        // Same char class as isCmdShimValid above, and the same note: the trailing
+        // `-` is a literal, and oxfmt leaves regex literals alone.
         const match = content.match(/"\$basedir[/\\]\.\.[/\\]((?:[\w./@-]|\\)+\.(?:mjs|cjs|js))"/i);
         if (match) {
             const relPath = match[1].replace(/[/\\]/g, path.sep);
@@ -263,6 +267,10 @@ function trySpawn(command, args, cwd, env, needsShell) {
         // shell:true justified: Windows .cmd/.bat LSP binaries (e.g. typescript-language-server.cmd)
         // cannot be spawned via execFile — cmd.exe must interpret the script wrapper.
         const shellCommand = `"${command}" ${args.map(escapeCmdArg).join(" ")}`;
+        // #2015 class-sweep exemption: this is a LONG-LIVED language-server launch,
+        // not a bounded probe - killing it on a timeout would be wrong, and its
+        // lifetime is owned by the LSP lifecycle, not the spawner. Exempt from the
+        // verifyToolBinary/probe tree-kill migration.
         proc = nodeSpawn(shellCommand, [], {
             cwd,
             env,

package/node_modules/pi-lens/dist/clients/lsp/pending-aux-coverage.js

@@ -0,0 +1,152 @@
+/**
+ * #2001/#2002 — collect-later coverage store for slow auxiliary LSP servers.
+ *
+ * When a `with-auxiliary` touch's aux-grace window expires without a
+ * publication from an auxiliary scanner (opengrep on Windows measures ~8s per
+ * scan against a 2s grace), that scanner's eventual findings were silently
+ * cached inside its LSP client and never surfaced to the agent: the auxiliary
+ * contributed ZERO agent-visible coverage on most edits.
+ *
+ * This module is the bounded hand-off between the two halves of the fix:
+ *
+ *   - PRODUCER (`clients/lsp/index.ts`'s aux-grace wait): after the outcomes
+ *     are decided, every auxiliary with no publication evidence for this
+ *     content (`cut_off` or `silent`, minus #1493's published-this-content
+ *     exemption) marks its (filePath, serverId) pair here. DEFERRED servers
+ *     are never marked — they never received the content, so their cache
+ *     still describes the PREVIOUS revision (#1459).
+ *   - CONSUMER (`clients/runtime-turn.ts` at turn_end): drains the store,
+ *     probes each pair through the read-only
+ *     `LSPService.readCachedDiagnosticsForServers` seam, freshness-gates the
+ *     result against `markedAtMs`, and delivers survivors as the registered
+ *     `runtime-turn:late-auxiliary-findings` gated surface. A pair whose
+ *     client is alive but has STILL published nothing is re-armed until
+ *     readLateAuxRearmTtlMs() (env-overridable via
+ *     `PI_LENS_LATE_AUX_REARM_TTL_MS`) after the LAST re-arm, so a scan
+ *     finishing between two turn ends is not lost and a demonstrably alive
+ *     but slow scanner keeps its window open; `markedAtMs` itself never
+ *     moves — it stays the immutable freshness baseline the delivery gate
+ *     stats against. Past the TTL, or when the client is gone, the entry is
+ *     dropped silently (best-effort by design).
+ *
+ * Bounds: at most MAX_PENDING_ENTRIES (file, server) pairs, insertion-order
+ * eviction of the OLDEST pair when the cap is exceeded (shape 9 discipline —
+ * the axis that grows is the pair count, so that is the axis that is capped).
+ * Keys fold through `normalizeEphemeralMapKey`: this is a hot single-process
+ * index whose keys are produced by this same process's touch path, so the
+ * cheap ephemeral normalizer is the lifetime-appropriate choice per the
+ * PathKeyedMap guidance — no realpath walk on the per-edit path.
+ */
+import { normalizeEphemeralMapKey } from "../path-utils.js";
+/** Maximum pending (filePath, serverId) pairs; oldest evicted beyond this. */
+export const MAX_PENDING_AUX_ENTRIES = 50;
+/**
+ * Default for how long a marked pair keeps being re-probed at successive
+ * turn ends when the client is alive but has published nothing yet. Covers
+ * opengrep's measured ~8s worst case many times over without pinning state
+ * forever. Overridable via `PI_LENS_LATE_AUX_REARM_TTL_MS`.
+ */
+export const DEFAULT_LATE_AUX_REARM_TTL_MS = 5 * 60_000;
+/**
+ * Read the `PI_LENS_LATE_AUX_REARM_TTL_MS` env override at call time (not
+ * module load time) so tests and users can tune without a rebuild — same
+ * shape as `readEnvAuxGraceMs` in clients/lsp/index.ts. Absent, non-numeric,
+ * or negative values fall back to {@link DEFAULT_LATE_AUX_REARM_TTL_MS}.
+ */
+export function readLateAuxRearmTtlMs() {
+    const raw = process.env.PI_LENS_LATE_AUX_REARM_TTL_MS;
+    if (raw === undefined)
+        return DEFAULT_LATE_AUX_REARM_TTL_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_LATE_AUX_REARM_TTL_MS;
+    return parsed;
+}
+/**
+ * Whether a pending pair is past its re-arm TTL and should be retired at the
+ * next drain. The TTL anchors on {@link PendingAuxCoverageEntry.lastRearmedAtMs}
+ * when present (each successful probe extends the window), else on
+ * `markedAtMs`. `nowMs` is injectable so tests are deterministic.
+ */
+export function isPendingAuxiliaryPastRearmTtl(pair, nowMs = Date.now()) {
+    const anchor = pair.lastRearmedAtMs ?? pair.markedAtMs;
+    return nowMs - anchor >= readLateAuxRearmTtlMs();
+}
+const pending = new Map();
+function pairKey(filePath, serverId) {
+    return `${normalizeEphemeralMapKey(filePath)}\u0000${serverId}`;
+}
+/**
+ * Mark (or re-arm) one file's pending auxiliary coverage for `serverIds`.
+ * An existing pair keeps its ORIGINAL `markedAtMs`; only genuinely new pairs
+ * stamp the current time. Insertion order updates on re-mark so a re-armed
+ * pair is not the next one evicted at the cap.
+ *
+ * `rearmedAtMs` is the turn-end consumer's re-arm form: it stamps
+ * `lastRearmedAtMs` (the TTL anchor) WITHOUT moving the freshness baseline,
+ * so each successful probe extends the wait window while the delivery gate
+ * keeps comparing mtimes against the original mark. The producer form (no
+ * `rearmedAtMs`) marks a NEWER revision, so it resets any prior re-arm stamp
+ * along with the baseline — the new pair's TTL starts from its own mark.
+ */
+export function markPendingAuxiliaryCoverage(filePath, serverIds, markedAtMs = Date.now(), rearmedAtMs) {
+    for (const serverId of serverIds) {
+        const key = pairKey(filePath, serverId);
+        const existing = pending.get(key);
+        if (existing) {
+            // #2027 review: bump the freshness baseline on producer re-mark. A
+            // newer touch means the auxiliary is scanning a NEWER revision;
+            // keeping the original baseline would make every post-baseline mtime
+            // read as stale, permanently dropping current-revision findings.
+            // A re-arm form never moves the baseline — only the TTL anchor.
+            pending.delete(key);
+            pending.set(key, rearmedAtMs === undefined
+                ? { filePath, serverId, markedAtMs }
+                : {
+                    filePath,
+                    serverId,
+                    markedAtMs: existing.markedAtMs,
+                    lastRearmedAtMs: rearmedAtMs,
+                });
+            continue;
+        }
+        pending.set(key, rearmedAtMs === undefined
+            ? { filePath, serverId, markedAtMs }
+            : { filePath, serverId, markedAtMs, lastRearmedAtMs: rearmedAtMs });
+        while (pending.size > MAX_PENDING_AUX_ENTRIES) {
+            const oldest = pending.keys().next().value;
+            if (oldest === undefined)
+                break;
+            pending.delete(oldest);
+        }
+    }
+}
+/**
+ * Remove one pair after its findings were delivered, or whenever the caller
+ * knows it is resolved. Unknown pairs are a no-op.
+ */
+export function clearPendingAuxiliaryCoverage(filePath, serverId) {
+    pending.delete(pairKey(filePath, serverId));
+}
+/**
+ * Drain ALL pending pairs (removing them from the store) and return them in
+ * insertion order. The consumer re-arms the still-waiting subset via
+ * {@link markPendingAuxiliaryCoverage}'s `rearmedAtMs` form, which preserves
+ * each entry's original `markedAtMs` and stamps `lastRearmedAtMs`.
+ */
+export function drainPendingAuxiliaryCoverage() {
+    const drained = [...pending.values()];
+    pending.clear();
+    return drained;
+}
+/** Test-only: current pending pair count. */
+export function pendingAuxiliaryCoverageSizeForTests() {
+    return pending.size;
+}
+/**
+ * Session-boundary clear (#1635): pending baselines are unreachable after
+ * reset (the generation-stamped keys no longer match any active session).
+ */
+export function resetPendingAuxiliaryCoverage() {
+    pending.clear();
+}

package/node_modules/pi-lens/dist/clients/lsp/server.js

@@ -7,7 +7,7 @@
  * - Platform-specific handling
  */
 import { existsSync, mkdirSync } from "node:fs";
-import { access, readFile, readdir, stat, } from "node:fs/promises";
+import { access, readFile, readdir, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { getGlobalPiLensDir, getProjectIgnoreGlobs, isPathIgnoredByProject, } from "../file-utils.js";
@@ -16,7 +16,7 @@ import { DOTNET_CSHARP_ROOT_MARKERS, DOTNET_FSHARP_ROOT_MARKERS, KIND_EXTENSIONS
 import { direntsHaveMarkerGlobMatch, isAtOrAboveHomeDir, isFullyQualified, isWindowsPath, pathsEqual, } from "../path-utils.js";
 import { ensureTool, getToolEnvironment, getToolPath, } from "../installer/index.js";
 import { resolveOpengrepConfig } from "../opengrep-config.js";
-import { isZizmorAuditTarget, resolveZizmorGitHubToken } from "../zizmor-config.js";
+import { isZizmorAuditTarget, resolveZizmorGitHubToken, } from "../zizmor-config.js";
 import { logLatency } from "../latency-logger.js";
 import { logSessionStart } from "../sessionstart-logger.js";
 import { findLocalSgconfig, resolveBaselineSgconfig } from "../sgconfig.js";
@@ -1236,7 +1236,9 @@ function isTsFamilyFile(file) {
     return TS_FAMILY_EXTENSIONS.has(path.extname(file).toLowerCase());
 }
 function tsConfigMarkersForFile(file) {
-    return isTsFamilyFile(file) ? ["tsconfig.json"] : TS_CONFIG_MARKERS;
+    return isTsFamilyFile(file)
+        ? ["tsconfig.json"]
+        : TS_CONFIG_MARKERS;
 }
 // Two detector instances (not one parameterized by file) so each keeps its own
 // per-directory NearestRoot cache valid for its fixed marker set — a shared
@@ -1606,7 +1608,9 @@ function extractTomlTableSection(content, tableName) {
         return "";
     const rest = content.slice(match.index + match[0].length);
     const nextHeading = rest.match(/^\[{1,2}[^\]]+\]{1,2}[ \t]*(?:#.*)?$/m);
-    return nextHeading?.index !== undefined ? rest.slice(0, nextHeading.index) : rest;
+    return nextHeading?.index !== undefined
+        ? rest.slice(0, nextHeading.index)
+        : rest;
 }
 function parseTomlStringArray(content, key) {
     const match = content.match(new RegExp(`^[ \\t]*${key}[ \\t]*=[ \\t]*\\[([\\s\\S]*?)\\]`, "m"));
@@ -1674,7 +1678,10 @@ function matchesCargoWorkspacePattern(pattern, relativePath) {
  * common case and the one #1671's fixtures exercise — is unaffected.
  */
 function cargoWorkspaceDeclaresMember(workspaceContent, parentDir, childDir) {
-    const relativePath = path.relative(parentDir, childDir).split(path.sep).join("/");
+    const relativePath = path
+        .relative(parentDir, childDir)
+        .split(path.sep)
+        .join("/");
     if (relativePath === "" || relativePath.startsWith(".."))
         return false;
     const workspaceSection = extractTomlTableSection(workspaceContent, "workspace");
@@ -1721,7 +1728,8 @@ function RustWorkspaceRoot() {
                 break;
             const parentCargoPath = path.join(parent, "Cargo.toml");
             const parentCargoContent = await readTextFileOrUndefined(parentCargoPath);
-            if (parentCargoContent !== undefined && /^\s*\[workspace\]/m.test(parentCargoContent)) {
+            if (parentCargoContent !== undefined &&
+                /^\s*\[workspace\]/m.test(parentCargoContent)) {
                 // Test membership against the ORIGINAL crate dir (`root`), never the
                 // walk cursor (`current`, which may already have climbed through
                 // gap directories that have no Cargo.toml of their own) — a
@@ -1786,7 +1794,11 @@ async function declaresMavenModule(parentDir, parentPomPath, childDir) {
     }
 }
 function JavaWorkspaceRoot() {
-    const moduleRoot = createRootDetector(["pom.xml", "build.gradle", ".classpath"]);
+    const moduleRoot = createRootDetector([
+        "pom.xml",
+        "build.gradle",
+        ".classpath",
+    ]);
     return async (file) => {
         const root = await moduleRoot(file);
         if (!root)

package/node_modules/pi-lens/dist/clients/lsp/tsserver-sync.js

@@ -114,9 +114,17 @@ export async function probeTsserverProjectIdentity(options) {
     // writing an `lsp_typescript_project_identity` row per didOpen on every
     // server (python, go, opengrep, ...).
     const logOutcome = (outcome, metadata = {}) => logLatency({
-        type: "phase", phase: "lsp_typescript_project_identity", filePath: normalizedFile,
+        type: "phase",
+        phase: "lsp_typescript_project_identity",
+        filePath: normalizedFile,
         durationMs: Date.now() - startedAt,
-        metadata: { serverId: options.serverId, launchVariant: options.launchVariant, clientRoot: options.clientRoot, outcome, ...metadata },
+        metadata: {
+            serverId: options.serverId,
+            launchVariant: options.launchVariant,
+            clientRoot: options.clientRoot,
+            outcome,
+            ...metadata,
+        },
     });
     if (options.serverId !== "typescript" ||
         options.launchVariant !== "classic" ||

package/node_modules/pi-lens/dist/clients/lsp/workspace-diagnostics-cache.js

@@ -6,7 +6,7 @@ import { readJsonCache } from "../json-cache-read.js";
 import { createGenerationMap } from "../generation-guard.js";
 import { normalizeMapKey } from "../path-utils.js";
 import { loadReverseDependencyIndexFromSnapshot } from "../reverse-deps.js";
-import { MTIME_DRIFT_TOLERANCE_MS } from "../blocker-freshness.js";
+import { freshnessFromMtime } from "../freshness.js";
 import { logLatency } from "../latency-logger.js";
 import { workspaceDiagnosticsCacheSessionStart } from "./workspace-diagnostics-session.js";
 import { createDiskBindingCache, } from "./diagnostic-binding.js";
@@ -344,14 +344,19 @@ export function isEntryFresh(filePath, entry, getImports) {
         return entry.depIndexAtScan !== true;
     }
     for (const dep of imports) {
+        let mtimeMs;
         try {
-            if (fs.statSync(dep).mtimeMs > entry.scannedAt + MTIME_DRIFT_TOLERANCE_MS) {
-                return false;
-            }
+            mtimeMs = fs.statSync(dep).mtimeMs;
         }
         catch {
             return false; // dependency deleted/unreadable: fail closed
         }
+        const verdict = freshnessFromMtime({
+            mtimeMs,
+            referenceMs: entry.scannedAt,
+        });
+        if (verdict.verdict === "stale")
+            return false;
     }
     return true;
 }

package/node_modules/pi-lens/dist/clients/lsp-document-symbols.js

@@ -68,9 +68,7 @@ export function findDocumentSymbolAtLine(symbols, oneBasedLine) {
     const visit = (items, ancestry) => {
         for (const symbol of items) {
             const range = symbolRange(symbol);
-            if (range &&
-                range.start.line <= line &&
-                range.end.line >= line) {
+            if (range && range.start.line <= line && range.end.line >= line) {
                 const nextAncestry = [...ancestry, symbol];
                 const span = range.end.line - range.start.line;
                 if (span <= bestSpan) {

package/node_modules/pi-lens/dist/clients/lsp-mutation.js

@@ -1,6 +1,5 @@
 import * as path from "node:path";
 import { createReadGuardEditBatchSummary, getReadGuardCorrelationId, logReadGuardEvent, } from "./read-guard-logger.js";
-import { appendProjectChange, } from "./project-changes.js";
 import { normalizeMapKey } from "./path-utils.js";
 const MAX_SAMPLES = 100;
 const MAX_SUMMARIES_PER_CONTEXT = 100;
@@ -67,7 +66,7 @@ function uniqueDetails(files, fileDetails) {
                     start: Math.min(previous.range.start, detail.range.start),
                     end: Math.max(previous.range.end, detail.range.end),
                 }
-                : previous.range ?? detail.range,
+                : (previous.range ?? detail.range),
             importsChanged: previous.importsChanged || detail.importsChanged,
         });
     }
@@ -93,24 +92,15 @@ function bookkeepLspMutation(context, files, fileDetails) {
             }
         }
         const runtime = context.runtime;
-        if (runtime?.bumpFileSeq) {
-            const { projectSeq, fileSeq } = runtime.bumpFileSeq(filePath);
-            try {
-                appendProjectChange(context.cwd, {
-                    seq: projectSeq,
-                    timestamp: new Date().toISOString(),
-                    sessionId: runtime.telemetrySessionId ?? "unknown",
-                    turnIndex: runtime.turnIndex ?? 0,
-                    source: context.source,
-                    filePath,
-                    fileSeq,
-                    changedRange: detail.range,
-                });
-            }
-            catch (err) {
-                context.dbg?.(`lsp mutation project change append failed for ${filePath}: ${err}`);
-            }
-        }
+        // One mutation seam (#2000 phase 1): bump + receipt + change-log live in
+        // RuntimeCoordinator.recordProjectMutation.
+        runtime?.recordProjectMutation?.({
+            filePath,
+            source: context.source,
+            cwd: context.cwd,
+            changedRange: detail.range,
+            onAppendError: (err) => context.dbg?.(`lsp mutation project change append failed for ${filePath}: ${err}`),
+        });
         if (context.cacheManager) {
             try {
                 context.cacheManager.addModifiedRange(filePath, detail.range ?? { start: 1, end: 1 }, detail.importsChanged ?? true, context.cwd, runtime?.telemetrySessionId);

package/node_modules/pi-lens/dist/clients/mcp/host-shim.js

@@ -9,7 +9,7 @@
  * coupling the MCP path has to satisfy — everything else under `clients/` is
  * host-neutral.
  */
-import { loadPiLensGlobalConfig, resolvePiLensFlag, } from "../lens-config.js";
+import { loadPiLensGlobalConfig, resolvePiLensFlag } from "../lens-config.js";
 import { loadPiLensProjectConfig } from "../project-lens-config.js";
 /**
  * Build a `PiAgentAPI` for the MCP path. `overrides` lets a single MCP tool call

package/node_modules/pi-lens/dist/clients/memory-sampler.js

@@ -40,15 +40,63 @@ export const MEMORY_SAMPLE_TURN_INTERVAL = 10;
 export function shouldEmitMemorySample(turnIndex) {
     return turnIndex > 0 && turnIndex % MEMORY_SAMPLE_TURN_INTERVAL === 0;
 }
-/** PURE: reshape Node's `process.memoryUsage()` into this module's field
- *  names — testable without touching the real process. */
-export function toMemoryProcessUsage(mem) {
+/**
+ * Rising-edge cadence (#1999): when heapUsed grows more than
+ * {@link HEAP_GROWTH_TIGHTEN_RATIO} between two sampled turns, sampling
+ * tightens from every {@link MEMORY_SAMPLE_TURN_INTERVAL} turns to every turn
+ * until growth stabilizes. The state below is module-scoped SESSION state —
+ * reset it at every primary `session_start` via
+ * {@link resetMemorySamplerCadence} (defect shape 17: a process-lifetime latch
+ * holding a session-scoped signal).
+ */
+export const HEAP_GROWTH_TIGHTEN_RATIO = 1.2;
+let _lastSampledHeapUsedBytes = 0;
+let _tightenThroughTurn = 0;
+/** Clear the rising-edge cadence state. Called on primary session_start. */
+export function resetMemorySamplerCadence() {
+    _lastSampledHeapUsedBytes = 0;
+    _tightenThroughTurn = 0;
+}
+/** PURE: >20% heap growth between two sampled readings warrants tightening. */
+export function isRapidHeapGrowth(previousHeapUsedBytes, currentHeapUsedBytes) {
+    return (previousHeapUsedBytes > 0 &&
+        currentHeapUsedBytes > previousHeapUsedBytes * HEAP_GROWTH_TIGHTEN_RATIO);
+}
+/** Record the heap reading of a sample just emitted at `turnIndex`. A rapid
+ *  growth edge extends the tightened window through the NEXT turn; each
+ *  subsequent still-growing sample (including one taken inside an already
+ *  tightened window) extends it again, so the window naturally expires once
+ *  growth stabilizes. Monotonic max so an out-of-order turn can never shrink
+ *  the window. O(1). */
+export function recordMemorySampleOutcome(heapUsedBytes, turnIndex) {
+    if (isRapidHeapGrowth(_lastSampledHeapUsedBytes, heapUsedBytes)) {
+        _tightenThroughTurn = Math.max(_tightenThroughTurn, turnIndex + 1);
+    }
+    _lastSampledHeapUsedBytes = heapUsedBytes;
+}
+/** Adaptive gate used by turn_end: base every-10 cadence OR an open tightened
+ *  window. Pure w.r.t. its argument; the window itself is session state owned
+ *  by {@link recordMemorySampleOutcome}. */
+export function shouldEmitMemorySampleAdaptive(turnIndex) {
+    if (turnIndex <= 0)
+        return false;
+    return (turnIndex % MEMORY_SAMPLE_TURN_INTERVAL === 0 ||
+        turnIndex <= _tightenThroughTurn);
+}
+/** PURE: reshape Node's `process.memoryUsage()` (+ optional
+ *  `process.resourceUsage()`) into this module's field names — testable
+ *  without touching the real process. */
+export function toMemoryProcessUsage(mem, resourceUsage) {
+    const maxKb = resourceUsage?.maxRSS;
     return {
         rssBytes: mem.rss,
         heapUsedBytes: mem.heapUsed,
         heapTotalBytes: mem.heapTotal,
         externalBytes: mem.external,
         arrayBuffersBytes: mem.arrayBuffers,
+        peakWorkingSetBytes: typeof maxKb === "number" && Number.isFinite(maxKb) && maxKb > 0
+            ? maxKb * 1024
+            : null,
     };
 }
 /**
@@ -86,11 +134,23 @@ export function collectMemorySampleSubsystems(wordIndex) {
     };
 }
 /** Assemble one full sample. `mem` is injectable for tests; defaults to a
- *  live `process.memoryUsage()` read. */
-export function buildMemorySample(wordIndex, mem = process.memoryUsage()) {
+ *  live `process.memoryUsage()` read. `resourceUsage` (peak working set) and
+ *  `session` are optional ridealongs (#1999); when `resourceUsage` is omitted
+ *  a live `process.resourceUsage()` read supplies the peak. */
+export function buildMemorySample(wordIndex, mem = process.memoryUsage(), resourceUsage, session) {
+    let resolvedResourceUsage = resourceUsage;
+    if (!resolvedResourceUsage) {
+        try {
+            resolvedResourceUsage = process.resourceUsage();
+        }
+        catch {
+            resolvedResourceUsage = undefined;
+        }
+    }
     return {
-        process: toMemoryProcessUsage(mem),
+        process: toMemoryProcessUsage(mem, resolvedResourceUsage),
         subsystems: collectMemorySampleSubsystems(wordIndex),
+        session,
     };
 }
 const toMb = (bytes) => Math.round(bytes / (1024 * 1024));
@@ -110,6 +170,12 @@ export function formatMemoryHealthLine(sample) {
         ? `${toMb(subsystems.treeSitter.treeCacheTotalBytes)}MB (${subsystems.treeSitter.treeCacheSize} trees)`
         : "n/a";
     const graph = `${subsystems.reviewGraph.totalNodes}n/${subsystems.reviewGraph.totalEdges}e (${subsystems.reviewGraph.cacheEntries} cwd)`;
+    // #1999: peak WS rides along when known — rss far below peak means the
+    // periodic samples are catching idle valleys, not the true high-water mark.
+    const peak = proc.peakWorkingSetBytes !== null
+        ? ` · peak WS ${toMb(proc.peakWorkingSetBytes)}MB`
+        : "";
     return (`Memory: RSS ${toMb(proc.rssBytes)}MB · heap ${toMb(proc.heapUsedBytes)}/${toMb(proc.heapTotalBytes)}MB` +
-        ` · external ${toMb(proc.externalBytes)}MB · tree-sitter cache ${treeCache} · review-graph ${graph}`);
+        ` · external ${toMb(proc.externalBytes)}MB${peak}` +
+        ` · tree-sitter cache ${treeCache} · review-graph ${graph}`);
 }

package/node_modules/pi-lens/dist/clients/metrics-client.js

@@ -18,9 +18,7 @@ export class MetricsClient {
     log;
     fileBaselines = new Map();
     constructor(verbose = false) {
-        this.log = verbose
-            ? createSubsystemLogger("metrics")
-            : () => { };
+        this.log = verbose ? createSubsystemLogger("metrics") : () => { };
     }
     /**
      * Record initial state of a file when first touched this session

package/node_modules/pi-lens/dist/clients/middle-man-analysis.js

@@ -50,7 +50,12 @@ const SELF_TOKEN = {
 const INTENTIONAL_FORWARDER_NAME = /adapter|facade|proxy|wrapper|decorator/i;
 /** Names that are constructors/destructors (never delegation candidates) in at
  * least one covered language. */
-const CONSTRUCTOR_NAMES = new Set(["constructor", "__init__", "__new__", "initialize"]);
+const CONSTRUCTOR_NAMES = new Set([
+    "constructor",
+    "__init__",
+    "__new__",
+    "initialize",
+]);
 /** Below this many real (non-accessor, non-constructor) methods, a delegation
  * ratio isn't a meaningful judgment — a one-method utility class forwarding
  * that one call is not "the class only ever delegates", it's just a small
@@ -130,7 +135,7 @@ function bodyStatementLines(lines, entry, isPython) {
             return [];
         body = raw.slice(braceIdx + 1, lastBrace);
     }
-    return body
+    return (body
         .replace(/\/\*[\s\S]*?\*\//g, "")
         .split("\n")
         .map((l) => l.replace(/\/\/.*$/, ""))
@@ -140,7 +145,7 @@ function bodyStatementLines(lines, entry, isPython) {
         // A lone triple-quoted docstring line in python isn't executable, but
         // distinguishing it textually is unreliable — treat any leading `"""`/`'''`
         // line as noise so a documented one-liner forward still qualifies.
-        .filter((l) => !/^("""|''')/.test(l));
+        .filter((l) => !/^("""|''')/.test(l)));
 }
 /** Detects an accessor (getter/setter) declaration from its raw source line —
  * accessors are a DIFFERENT smell (anemic class) and excluded from both the

package/node_modules/pi-lens/dist/clients/module-report-lsp.js

@@ -82,7 +82,13 @@ function lspLocationsToUsedBy(locs, cap) {
         if (seen.has(key))
             continue;
         seen.add(key);
-        out.push({ file, symbol: "", line, relation: "references", provenance: "lsp" });
+        out.push({
+            file,
+            symbol: "",
+            line,
+            relation: "references",
+            provenance: "lsp",
+        });
         if (out.length >= cap)
             break;
     }

package/node_modules/pi-lens/dist/clients/module-report.js

@@ -1180,7 +1180,8 @@ function unavailableCallGraph(reason) {
 }
 function callGraphCoverage(coverage) {
     const languages = coverage.languages;
-    const complete = coverage.complete && Object.values(languages ?? {}).every((status) => status === "complete");
+    const complete = coverage.complete &&
+        Object.values(languages ?? {}).every((status) => status === "complete");
     return {
         status: complete ? "complete" : "partial",
         complete,
@@ -1235,7 +1236,8 @@ function readCallGraph(projectRoot, normalizedPath, maxEntries, graphFileCap, id
     // read-only: do not walk source files or compare an independent mtime map.
     if (!reviewGraph)
         return unavailableCallGraph("review-graph-missing");
-    if (reviewGraph.persistCoverage?.partial || reviewGraph.persistCoverage?.inProgress) {
+    if (reviewGraph.persistCoverage?.partial ||
+        reviewGraph.persistCoverage?.inProgress) {
         return unavailableCallGraph("partial");
     }
     if (!identity)
@@ -1458,9 +1460,7 @@ export async function moduleReport(file, cwd, options) {
     else if (graph) {
         importsProvenance = "cached-review-graph";
     }
-    const unavailableGraphProvenance = graphFileCap !== undefined
-        ? "unavailable:file-cap"
-        : "none";
+    const unavailableGraphProvenance = graphFileCap !== undefined ? "unavailable:file-cap" : "none";
     const blastRadiusProvenance = blastRadius
         ? "cached-review-graph"
         : unavailableGraphProvenance;
@@ -1495,13 +1495,9 @@ export async function moduleReport(file, cwd, options) {
         provenance: {
             symbols: languageId ? "syntax" : "none",
             imports: importsProvenance,
-            usedBy: hasGraphNode
-                ? "cached-review-graph"
-                : unavailableGraphProvenance,
+            usedBy: hasGraphNode ? "cached-review-graph" : unavailableGraphProvenance,
             callbacks: languageId && !summaryView ? "heuristic-tree-sitter" : "none",
-            ...(options?.blastRadius
-                ? { blastRadius: blastRadiusProvenance }
-                : {}),
+            ...(options?.blastRadius ? { blastRadius: blastRadiusProvenance } : {}),
             ...(options?.callGraph ? { callGraph: callGraphProvenance } : {}),
         },
         semantic: {
@@ -1565,7 +1561,9 @@ function compactEntryLine(entry, width) {
     const range = padRange(entry.startLine, entry.endLine, width);
     const kind = compactKind(entry.kind).padEnd(6);
     const sig = entry.signature ? `${entry.name}${entry.signature}` : entry.name;
-    const flagsSuffix = entry.flags && entry.flags.length > 0 ? `  [${entry.flags.join(", ")}]` : "";
+    const flagsSuffix = entry.flags && entry.flags.length > 0
+        ? `  [${entry.flags.join(", ")}]`
+        : "";
     const docSuffix = entry.doc ? `  — ${entry.doc}` : "";
     const usedBySuffix = compactUsedBySuffix(entry.usedBy);
     return `  ${range}${kind}${sig}${flagsSuffix}${usedBySuffix}${docSuffix}`;
@@ -1607,10 +1605,7 @@ export function renderCompactModuleReport(report) {
         return `${report.path} — unavailable${report.error ? `: ${report.error}` : ""}`;
     }
     const allEntries = [...report.api, ...report.internal];
-    const allRanges = allEntries.flatMap((e) => [
-        e,
-        ...(e.members ?? []),
-    ]);
+    const allRanges = allEntries.flatMap((e) => [e, ...(e.members ?? [])]);
     const width = Math.max(5, ...allRanges.map((e) => `${e.startLine}-${e.endLine}`.length), ...report.callbacks.map((c) => `${c.startLine}-${c.endLine}`.length)) + 2;
     const importsList = [...report.imports.internal, ...report.imports.external];
     const importsSuffix = importsList.length > 0
@@ -1679,7 +1674,9 @@ function baseNameNoExt(p) {
 function selectMatch(candidates, kind) {
     if (candidates.length === 0)
         return {};
-    const filtered = kind ? candidates.filter((c) => c.kind === kind) : candidates;
+    const filtered = kind
+        ? candidates.filter((c) => c.kind === kind)
+        : candidates;
     const pool = filtered.length > 0 ? filtered : candidates;
     const match = pool[0];
     if (pool.length <= 1)