@herbertgao/pi-extensions 2026.9.6 → 2026.9.8

package/node_modules/pi-lens/dist/clients/read-guard.js

@@ -266,15 +266,19 @@ export class ReadGuard {
     // pi Write tool authored, independent of filesystem mtime granularity
     // or clock skew (NFS, FAT32, etc.).
     writtenThisSession = new Set();
+    unchangedThisSession = new Set();
     // Existence-independent index for hasKnownPath/forgetPath (#1668 review
     // F1). `this.key()` (normalizeFilePath) branches on whether `filePath`
-    // currently exists on disk: an existing file resolves to realpathSync
-    // canonical casing, a missing one to a lowercased tail. recordRead/
-    // recordWritten always key while the file is still on disk (real
-    // casing); hasKnownPath/forgetPath are queried AFTER an external delete
-    // already landed, when the path no longer exists — recomputing
+    // currently exists on disk, on EVERY platform since #3098 — an existing
+    // file resolves to its on-disk casing (win32: `realpathSync.native`;
+    // POSIX: the on-disk casing of the trailing segments), a missing one to a
+    // lowercased tail on win32 and to the caller's own spelling on POSIX.
+    // recordRead/recordWritten always key while the file is still on disk
+    // (real casing); hasKnownPath/forgetPath are queried AFTER an external
+    // delete already landed, when the path no longer exists — recomputing
     // `this.key()` at that point returns a DIFFERENT string for any
-    // mixed-case basename (`MyModule.ts` → `mymodule.ts`), so a lookup
+    // mixed-case basename (win32 `MyModule.ts` → `mymodule.ts`; POSIX
+    // `Components/x.ts` held against an on-disk `components/`), so a lookup
     // against `reads`/`writtenThisSession` silently misses. This index maps
     // a purely syntactic key (`normalizeEphemeralMapKey` — slash-fold +
     // lowercase, no filesystem access, so it never depends on current disk
@@ -282,6 +286,17 @@ export class ReadGuard {
     // time, so a post-delete lookup finds the same entry regardless of what
     // happened to the file since. Pruned inside `evictFile` so it never
     // outlives the record it points at.
+    //
+    // ONLY hasKnownPath/forgetPath route through this index, because only they
+    // need the real key BACK. `noteCreatedFile` (keys while the file is still
+    // absent) and `recordWritten` (keys after it exists) straddle the same
+    // state change, and used to do it through `this.key()` directly — a
+    // spelling whose key moved orphaned the `pendingCreations` entry and the
+    // creation read was never injected (#3163, pre-existing on win32 and
+    // reachable on POSIX since #3098). They now key `pendingCreations` by the
+    // same existence-independent `normalizeEphemeralMapKey` spelling this index
+    // is keyed by; no index is needed there, since the real key is derived by
+    // `recordWritten` itself at the moment it is used.
     knownPathIndex = new Map();
     /** Running per-file record-cap trim totals for this session (#1913 F1). */
     trimAccumulators = new Map();
@@ -424,8 +439,15 @@ export class ReadGuard {
      * Record that a file was read.
      * Call this from the tool_call handler after any LSP expansion.
      */
-    recordRead(record) {
+    recordRead(record, opts) {
         const filePath = this.key(record.filePath);
+        if (opts?.supersedes) {
+            const records = this.reads.get(filePath);
+            const provisionalSource = `native-read:${opts.supersedes.toolCallId}:provisional`;
+            const provisionalIndex = records?.findIndex((candidate) => candidate.source === provisionalSource);
+            if (provisionalIndex !== undefined && provisionalIndex >= 0)
+                records.splice(provisionalIndex, 1);
+        }
         // #1668 review F1: index by the existence-independent syntactic key
         // while the file is (presumably) still on disk, so a later
         // hasKnownPath/forgetPath lookup after an external delete can still
@@ -865,9 +887,26 @@ export class ReadGuard {
      * Must be called from the tool_call handler before the write lands so
      * isNewFile() still returns true. recordWritten will inject a synthetic
      * read so immediate follow-up edits are not blocked by zero_read.
+     *
+     * Keyed by the existence-INDEPENDENT syntactic spelling
+     * (`normalizeEphemeralMapKey`, the same key `knownPathIndex` uses), NOT by
+     * `this.key()` (#3163). This entry is written while the file is still
+     * ABSENT and read back by `recordWritten` once it EXISTS — the one state
+     * change `normalizeFilePath` itself branches on — so a `this.key()` on each
+     * side answered with two different strings for any spelling whose key moves
+     * when the file appears (win32: a mixed-case basename, lower-cased in the
+     * absent branch by `resolveNonExisting`; POSIX since #3098: a parent whose
+     * canonical casing is adopted once `realpathSync.native` succeeds). The
+     * entry was then orphaned — nothing prunes `pendingCreations` — and the
+     * creation read never injected. The syntactic key never touches the
+     * filesystem, so it cannot move; the REAL key the injected read needs is
+     * derived by `recordWritten` itself and is not stored here.
      */
     noteCreatedFile(filePath, turnIndex, writeIndex) {
-        this.pendingCreations.set(this.key(filePath), { turnIndex, writeIndex });
+        this.pendingCreations.set(normalizeEphemeralMapKey(filePath), {
+            turnIndex,
+            writeIndex,
+        });
     }
     /**
      * Refresh the FileTime stamp after the model's own write lands on disk.
@@ -876,6 +915,7 @@ export class ReadGuard {
      */
     recordWritten(rawFilePath) {
         const filePath = this.key(rawFilePath);
+        this.unchangedThisSession.delete(filePath);
         // #1668 review F1: index by the existence-independent syntactic key
         // (see `knownPathIndex`) so a later hasKnownPath/forgetPath lookup
         // after an external delete can still find this entry's real key.
@@ -886,12 +926,25 @@ export class ReadGuard {
             this.consumedReadFiles.add(filePath);
         this.touchFile(filePath);
         this.enforceFileCap();
-        const creation = this.pendingCreations.get(filePath);
+        // #3163: `noteCreatedFile` announced this creation while the file was
+        // still absent, so the announcement is keyed by the syntactic spelling —
+        // look it up the same way, never through the existence-dependent
+        // `filePath` above. `injectCreationRead` still receives the real key.
+        const creationKey = normalizeEphemeralMapKey(rawFilePath);
+        const creation = this.pendingCreations.get(creationKey);
         if (creation) {
-            this.pendingCreations.delete(filePath);
+            this.pendingCreations.delete(creationKey);
             this.injectCreationRead(filePath, creation.turnIndex, creation.writeIndex);
         }
     }
+    /** Record that a recognized mutation had complete evidence but changed no bytes. */
+    recordUnchanged(rawFilePath) {
+        const filePath = this.key(rawFilePath);
+        // A no-op command is scoped to this command. It must not erase a
+        // confirmed Write from earlier in the session.
+        if (!this.writtenThisSession.has(filePath))
+            this.unchangedThisSession.add(filePath);
+    }
     /**
      * Add a one-time exemption for a file.
      * Called via /lens-allow-edit command.
@@ -1074,6 +1127,8 @@ export class ReadGuard {
         });
     }
     wasWrittenThisSession(filePath) {
+        if (this.unchangedThisSession.has(filePath))
+            return false;
         // Authoritative path: we observed a write of this file via recordWritten.
         // Survives mtime granularity (FAT32 ~2s), clock skew (NFS), and external
         // tools that touch mtime backward.
@@ -1338,6 +1393,8 @@ export class ReadGuard {
         const reads = this.reads.get(filePath) ?? [];
         // First pass: check symbol coverage and any single read that covers the edit.
         for (const read of reads) {
+            if (read.provisional === true)
+                continue;
             const readStart = Math.max(1, read.effectiveOffset - this.config.contextLines);
             const readEnd = read.effectiveOffset +
                 read.effectiveLimit -
@@ -1356,7 +1413,9 @@ export class ReadGuard {
         }
         // Second pass: merge all read intervals and check if their union covers
         // [editStart, editEnd]. Handles multi-chunk reads (e.g. 1-100 + 101-200).
-        const intervals = reads.map((read) => [
+        const intervals = reads
+            .filter((read) => read.provisional !== true)
+            .map((read) => [
             Math.max(1, read.effectiveOffset - this.config.contextLines),
             read.effectiveOffset +
                 read.effectiveLimit -

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

@@ -44,10 +44,20 @@
  * clients/instance-reaper.ts (`decideOrphanReaping` vs `sweepOrphans`).
  */
 import pidusage from "pidusage";
-import { recordDegradationOnce } from "./degradation-ledger.js";
+import { incrementDegradationCount, recordDegradationOnce, } from "./degradation-ledger.js";
 import { terminateScannerChild } from "./instance-reaper.js";
 import { queryProcessTable } from "./process-snapshot.js";
 export const RESOURCE_SAMPLE_QUERY_TIMEOUT_MS = 2_000;
+/**
+ * ONE ledger subject for every spawn sampler in the session (#2968). The
+ * per-spawn identity (pid, command) is NOT the subject: a subject is a
+ * `tallies` key, and one key per spawn would make the ledger grow with the
+ * session's spawn count — catalog shape 9, the same leak this fix exists to
+ * close. The command that was sampled is already on the `spawn_resource_usage`
+ * latency row; what the ledger answers is "did sampling hit its bounds, and
+ * how often", which is a per-session tally.
+ */
+const SPAWN_SAMPLER_LEDGER_SUBJECT = "spawn-usage-sampler";
 function recordQueryFailure(subject, status, exitCode) {
     const exitReason = status === "exit-error" ? ` (exit code ${exitCode ?? "unknown"})` : "";
     recordDegradationOnce({
@@ -434,13 +444,89 @@ export async function sampleProcessTreeCpuPercent(pid, windowMs = 1200, floorPer
         cpuPercent: observed,
     };
 }
-export function startSpawnUsageSampler(pid, intervalMs = 750) {
+/**
+ * Base poll cadence — inside #620's suggested 500ms-1s band, cheap enough not
+ * to become measurable overhead for the (usually sub-few-second) analyzer
+ * children this brackets.
+ */
+const SPAWN_SAMPLE_INTERVAL_MS = 750;
+/**
+ * #2968: how many ticks keep the full `intervalMs` cadence before the backoff
+ * starts. 8 × 750ms = the first 6 seconds, which covers the short-lived
+ * analyzer children the short interval exists for; a child still running past
+ * that is not short-lived and does not need sub-second resolution.
+ */
+const SPAWN_SAMPLE_FULL_RATE_TICKS = 8;
+/**
+ * #2968: backoff ceiling, as a multiple of `intervalMs` (16 × 750ms = 12s).
+ * Past the full-rate window the delay doubles each tick up to this, so a
+ * long-lived child costs a bounded ~5 polls/minute instead of 80.
+ */
+const SPAWN_SAMPLE_MAX_INTERVAL_MULTIPLIER = 16;
+/**
+ * Brackets one transient spawn with a short-interval poll. Usage:
+ *
+ *   const sampler = startSpawnUsageSampler(child.pid, interval, capMs);
+ *   child.on("close", () => {
+ *     const usage = sampler.stop(); // null if never got a single sample
+ *   });
+ *
+ * Best-effort: a poll tick that throws (pid already gone, sampling error) is
+ * silently skipped — it never stops the polling or the spawn early, and
+ * `stop()` is always safe to call even if zero samples ever landed.
+ *
+ * Windows note: `clients/safe-spawn.ts` spawns with `shell: true` on Windows,
+ * so `pid` here is `cmd.exe`'s pid, not the real tool's — sampling it alone
+ * would report near-zero usage for the whole invocation. Each Windows tick
+ * resolves `pid`'s live descendant tree (`findDescendantPidsWindows`) and
+ * sums usage across `pid` + every descendant, so a `node`/`npx`-wrapped tool
+ * (or one that re-execs itself) is actually captured. POSIX spawns are
+ * unwrapped (`shell: false`), so `pid` there is already the real tool.
+ *
+ * ## Backpressure: three bounds, three axes (#2968, external report)
+ *
+ * A Windows tick is not free — it is TWO `powershell.exe` CIM queries (the
+ * descendant walk plus the usage read), and a query that blows
+ * `RESOURCE_SAMPLE_QUERY_TIMEOUT_MS` adds a `taskkill.exe`. With a `setInterval`
+ * that neither waited for its own tick nor ever expired, four children that
+ * hung for 5-6 hours left 234 live `powershell.exe`/`taskkill.exe` processes
+ * (~10GB) parented by the host. Each bound below closes one axis; catalog
+ * shape 9 is exactly the shape where closing only one of them is not a fix:
+ *
+ * 1. CONCURRENCY — a tick never starts while the previous one is unsettled
+ *    (`inFlight`). The old `setInterval` fired regardless, so a query slower
+ *    than the interval stacked one more pair of children every tick.
+ * 2. RATE — past `SPAWN_SAMPLE_FULL_RATE_TICKS` the delay doubles per tick up
+ *    to `SPAWN_SAMPLE_MAX_INTERVAL_MULTIPLIER × intervalMs`. The short
+ *    interval exists to catch short-lived children; a 180s runner (the
+ *    longest spawn timeout in the tree) costs ~26 polls instead of 240.
+ * 3. LIFETIME — polling stops for good at `lifetimeCapMs`, measured from
+ *    start. `stop()` still returns everything gathered up to that point; a
+ *    capped sampler loses resolution, never the reading it already had. The
+ *    cap is read at TICK granularity, so the last poll can land up to one
+ *    backed-off interval (≤ 12s by default) before polling ends — the tick
+ *    that discovers the cap does no sampling and arms nothing.
+ *
+ * Ticks skipped for (1) and the cap in (3) are both recorded, bounded, on the
+ * degradation ledger — a sampler that quietly stops sampling is the #1863 /
+ * #2132 shape one level up.
+ *
+ * `lifetimeCapMs` has no default ON PURPOSE: an unbounded sampler is the whole
+ * defect, so the bound is the caller's to state rather than something a future
+ * call site can forget. The cadence keeps its default, which is policy this
+ * module owns.
+ */
+export function startSpawnUsageSampler(pid, intervalMs = SPAWN_SAMPLE_INTERVAL_MS, lifetimeCapMs) {
     if (!Number.isFinite(pid) || pid <= 0) {
         return { stop: () => null };
     }
     const targetPid = pid;
     const accumulator = new UsageAccumulator();
+    const startedAt = Date.now();
     let stopped = false;
+    let inFlight = false;
+    let tickCount = 0;
+    let timer;
     const tick = async () => {
         if (stopped)
             return;
@@ -470,20 +556,72 @@ export function startSpawnUsageSampler(pid, intervalMs = 750) {
             // Best-effort: a failed poll tick just misses one sample.
         }
     };
+    const releaseInFlight = () => {
+        inFlight = false;
+    };
+    /**
+     * Delay before the NEXT tick, given how many have already run. Full rate
+     * through the short-lived window, then doubling to the ceiling (#2968).
+     */
+    const nextDelayMs = () => {
+        if (tickCount <= SPAWN_SAMPLE_FULL_RATE_TICKS)
+            return intervalMs;
+        const grown = intervalMs * 2 ** (tickCount - SPAWN_SAMPLE_FULL_RATE_TICKS);
+        return Math.min(grown, intervalMs * SPAWN_SAMPLE_MAX_INTERVAL_MULTIPLIER);
+    };
+    const arm = (delayMs) => {
+        timer = setTimeout(runTick, delayMs);
+        // Never let this timer keep the process alive on its own.
+        timer.unref?.();
+    };
+    function runTick() {
+        timer = undefined;
+        if (stopped)
+            return;
+        if (Date.now() - startedAt >= lifetimeCapMs) {
+            // LIFETIME bound: deliberately NOT re-armed. The accumulator is kept,
+            // so `stop()` still answers with everything gathered before the cap.
+            incrementDegradationCount({
+                kind: "resource-sampler-lifetime-capped",
+                subject: SPAWN_SAMPLER_LEDGER_SUBJECT,
+                reason: `spawn sampler stopped polling at its ${lifetimeCapMs}ms lifetime cap; the child was still running`,
+            });
+            return;
+        }
+        tickCount++;
+        if (inFlight) {
+            // CONCURRENCY bound: the previous tick's process-table queries have
+            // not settled, so starting another would stack a second set of
+            // children on top of them (#2968's Windows pile-up).
+            incrementDegradationCount({
+                kind: "resource-sampler-tick-overlapped",
+                subject: SPAWN_SAMPLER_LEDGER_SUBJECT,
+                reason: `spawn sampler skipped a poll tick: the previous sample was still in flight after ${intervalMs}ms`,
+            });
+        }
+        else {
+            inFlight = true;
+            // `tick` never rejects (it is fully guarded), but settle BOTH ways
+            // anyway: a rejection that escaped would otherwise latch `inFlight`
+            // true and silently end all sampling.
+            void tick().then(releaseInFlight, releaseInFlight);
+        }
+        arm(nextDelayMs());
+    }
     // Fire one tick immediately (short-lived children can exit before the
     // first interval elapses) plus a recurring poll.
-    void tick();
-    const timer = setInterval(() => {
-        void tick();
-    }, intervalMs);
-    // Never let this timer keep the process alive on its own.
-    timer.unref?.();
+    tickCount = 1;
+    inFlight = true;
+    void tick().then(releaseInFlight, releaseInFlight);
+    arm(nextDelayMs());
     return {
         stop() {
             if (stopped)
                 return accumulator.summarize();
             stopped = true;
-            clearInterval(timer);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
             return accumulator.summarize();
         },
     };

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

@@ -79,7 +79,7 @@ export class RuffClient {
             // nested `pyproject.toml` whenever the caller passed a workspace root.
             const ruffCwd = resolveToolCwd("runner", "ruff", absolutePath, {
                 ...(cwd !== undefined && { cwd }),
-            });
+            }).cwd;
             // Shared config-args seam (#1247): the lint runner consumes the same
             // builder, so `check --fix` can never drift to ruff's default rule
             // set when the project lacks its own config and the package-owned

package/node_modules/pi-lens/dist/clients/runtime-agent-end.js

@@ -6,6 +6,8 @@ import { publishAutofixStart, publishFormatStart, } from "./format-events-publis
 import { logLatency } from "./latency-logger.js";
 import { isPathIgnoredByProject } from "./file-utils.js";
 import { admitBounded, emitBounded } from "./bounded-telemetry.js";
+import { bounded } from "./deadline-utils.js";
+import { HOOK_WALL_BUDGET_MS } from "./hook-budgets.js";
 import { newLspMutationCorrelationId, } from "./lsp-mutation.js";
 import { getGlobalActionableWarningMaxFixes, } from "./lens-config.js";
 import { resyncLspFile, runAutofix, runFormatPhase } from "./pipeline.js";
@@ -32,7 +34,7 @@ function recordProjectChange(args) {
         onAppendError: (err) => args.dbg(`project change log append failed for ${args.filePath}: ${err}`),
     });
 }
-export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, dbg, runtime, cacheManager, getFormatService, biomeClient, ruffClient, getAutofixClients, currentSessionId, staleAfterMs = DEFERRED_FORMAT_STALE_AFTER_MS, }) {
+export async function handleAgentEnd({ signal, ctxCwd, getFlag, getFlagSource, notify, dbg, runtime, cacheManager, getFormatService, biomeClient, ruffClient, getAutofixClients, currentSessionId, staleAfterMs = DEFERRED_FORMAT_STALE_AFTER_MS, }) {
     // #791: ownership-filtered drain — records queued by a DIFFERENT known
     // session (e.g. a concurrent in-process secondary/subagent) stay queued
     // for their owner's own agent_end, unless they've been stale long enough
@@ -204,7 +206,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
     const deferredAutofixChanged = new Set();
     // Mutation ordering is intentional: lint --write may disturb wrapping, so
     // autofix reaches the final edited state first and formatting stabilizes it.
-    const ambientSignal = getAmbientAbortSignal();
+    const ambientSignal = signal ?? getAmbientAbortSignal();
     const executedAutofixScopes = new Set();
     const autofixRecords = records.filter((candidate) => candidate.kinds.has("autofix"));
     if (autofixRecords.length > 0 &&
@@ -367,7 +369,13 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                 const filePath = path.resolve(record.filePath);
                 started.add(index);
                 if (!nodeFs.existsSync(filePath)) {
-                    work[index] = { record, filePath, fileStart, missing: true };
+                    work[index] = {
+                        record,
+                        filePath,
+                        fileStart,
+                        result: undefined,
+                        missing: true,
+                    };
                     continue;
                 }
                 try {
@@ -375,7 +383,12 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                         record,
                         filePath,
                         fileStart,
-                        result: await runFormatPhase(filePath, getFormatService, dbg),
+                        result: await bounded(runFormatPhase(filePath, getFormatService, dbg, ambientSignal, 30_000, "agent_settled"), {
+                            ms: HOOK_WALL_BUDGET_MS.agent_settled,
+                            signal: ambientSignal,
+                            hook: "agent_settled",
+                            label: "deferred-format",
+                        }),
                     };
                 }
                 catch (err) {
@@ -383,6 +396,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                         record,
                         filePath,
                         fileStart,
+                        result: undefined,
                         error: err instanceof Error ? err.message : String(err),
                     };
                 }
@@ -423,8 +437,22 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                 continue;
             }
             const result = entry.result;
-            if (!result)
+            if (!result) {
+                // The abort branch above already requeues work that never started;
+                // preserve its established ownership for an in-flight caller abort.
+                if (ambientSignal?.aborted)
+                    continue;
+                const reason = entry.error ?? "deferred formatter exceeded agent_settled budget";
+                summary.failed.push({ filePath, errors: [reason] });
+                requeue([
+                    {
+                        ...record,
+                        kinds: new Set(["format"]),
+                        toolNames: new Set(record.toolNames),
+                    },
+                ], "format-failed");
                 continue;
+            }
             summary.formatted++;
             if (result.formatFailures.length > 0) {
                 summary.failed.push({ filePath, errors: result.formatFailures });

package/node_modules/pi-lens/dist/clients/runtime-context.js

@@ -1,5 +1,6 @@
 import { provenanceStamp, validateAdvisoryProvenance, } from "./advisory-provenance.js";
 import { logLatency } from "./latency-logger.js";
+import { translateGuidanceToolNames, } from "./tool-config.js";
 // Exported so the Stop-hook bin strips exactly what these bridges prepend.
 export const AUTOMATION_FRAMING = "[pi-lens automated check — not a user request] ";
 // #1432 review (S3b): a multi-file bash write can carry hundreds of changed
@@ -184,7 +185,7 @@ export function acknowledgeTestFindings(cacheManager, cwd) {
         return;
     retireTestFindings(cacheManager, cwd);
 }
-export function consumeSessionStartGuidance(cacheManager, cwd) {
+export function consumeSessionStartGuidance(cacheManager, cwd, host = "pi") {
     const guidance = cacheManager.readCache("session-start-guidance", cwd);
     if (!guidance?.data?.content)
         return;
@@ -200,7 +201,10 @@ export function consumeSessionStartGuidance(cacheManager, cwd) {
         messages: [
             {
                 role: "user",
-                content: `[pi-lens automated context — not a user request]\n\n${guidance.data.content}`,
+                // #2535: the stored guidance names pi tools; MCP agents receive
+                // the registry-translated rendering. The stored record keeps
+                // its shape — resolution happens here, at delivery.
+                content: `[pi-lens automated context — not a user request]\n\n${translateGuidanceToolNames(guidance.data.content, host)}`,
             },
         ],
     };

package/node_modules/pi-lens/dist/clients/runtime-coordinator.js

@@ -12,6 +12,9 @@ import { RUNTIME_CONFIG } from "./runtime-config.js";
 import { TurnSummaryCollector } from "./turn-summary.js";
 import { deriveProviderFromModelId } from "./model-provider.js";
 import { beginTurnContext, setTurnContextSession } from "./turn-context.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
+/** Keep deferred cascade admission bounded without dropping late findings. */
+export const MAX_PENDING_CASCADE_RUNS = 32;
 /**
  * Bounded receipt ring capacity (defect shape 9: bound the axis that grows —
  * per-mutation receipts are unbounded across a long session). Oldest receipts
@@ -286,8 +289,8 @@ export class RuntimeCoordinator {
         }
         this._mutationReceipts.push({
             seq: projectSeq,
-            // Reuse the bump's normalized key (~200us realpath on Windows) —
-            // never re-derive it here.
+            // Reuse the bump's normalized key (a realpath syscall: ~200us on
+            // Windows, ~1.8us on POSIX since #3098) — never re-derive it here.
             filePath: key,
             source: args.source,
             turnIndex: this._turnIndex,
@@ -455,8 +458,9 @@ export class RuntimeCoordinator {
         }
     }
     bumpFileSeq(filePath) {
-        // normalizeMapKey costs ~200us/call on Windows (realpath); every caller
-        // that also needs the key must reuse this one instead of paying it twice.
+        // normalizeMapKey costs a realpath syscall per call — ~200us on Windows,
+        // ~1.8us on POSIX since #3098; every caller that also needs the key must
+        // reuse this one instead of paying it twice.
         const key = normalizeMapKey(path.resolve(filePath));
         this._projectSeq += 1;
         const fileSeq = (this._fileSeq.get(key) ?? 0) + 1;
@@ -542,7 +546,24 @@ export class RuntimeCoordinator {
         this._cascadeRuns.push(run);
     }
     appendCascadePromise(p) {
-        this._pendingCascadeRuns.push(p);
+        if (this._pendingCascadeRuns.length < MAX_PENDING_CASCADE_RUNS) {
+            this._pendingCascadeRuns.push(p);
+            return;
+        }
+        // Preserve delivery for overflow rather than growing the per-edit array.
+        // The settled run enters the same accumulator off-hook and is therefore
+        // visible to the next turn-end drain.
+        recordDegradationOnce({
+            kind: "cascade-pending-cap",
+            subject: "runtime-coordinator",
+            reason: `deferred cascade admission capped at ${MAX_PENDING_CASCADE_RUNS}`,
+        });
+        void p
+            .then((run) => this.appendCascadeRun(run))
+            .catch(() => {
+            // Pipeline promises are normally non-rejecting; preserve the existing
+            // failure sink if a caller violates that contract.
+        });
     }
     /**
      * The active turn_end settle clock, or undefined outside that wait.
@@ -644,16 +665,24 @@ export class RuntimeCoordinator {
         // that actually settles it delivers it.
         return this._cascadeRuns.length > 0;
     }
-    recordInlineBlockers(filePath, summary, writeIndex, sources, lines) {
+    recordInlineBlockers(filePath, summary, writeIndex, sources, lines, contentBaseline) {
+        const recordedAtMs = Date.now();
         this._pendingInlineBlockers.set(path.resolve(filePath), {
             filePath,
             summary,
             writeIndex,
             sources,
             lines,
-            recordedAtMs: Date.now(),
+            recordedAtMs,
             stale: false,
+            ...(contentBaseline
+                ? {
+                    recordedSize: contentBaseline.size,
+                    recordedHash: contentBaseline.sha256,
+                }
+                : {}),
         });
+        return recordedAtMs;
     }
     clearInlineBlockers(filePath) {
         this._pendingInlineBlockers.delete(path.resolve(filePath));
@@ -708,6 +737,47 @@ export class RuntimeCoordinator {
         });
         return true;
     }
+    /**
+     * #2982: re-derive the self-drift demotion for one inline-blocker record.
+     *
+     * Modelled on {@link setInlineBlockerPastEofStale}, not on
+     * {@link markInlineBlockerStale}: it RE-ARMS rather than latching, so a
+     * file whose bytes drift and then come back (a checkout, a revert, an
+     * editor writing the original content) un-demotes on the next sweep
+     * instead of staying demoted for the session. That re-arm is what lets
+     * this axis skip the #1950 delivery cap entirely — a record that can heal
+     * needs no bounded-noise retirement, and applying the cap here would walk
+     * an ast-grep or tree-sitter security finding out of turn-end rendering
+     * permanently (#2982 review).
+     *
+     * Composes with the sibling gates the same way they compose with each
+     * other: it never touches a record another gate demoted, and never heals a
+     * demotion it did not make. Returns true only on an actual transition, so
+     * the caller counts exactly one edge.
+     */
+    setInlineBlockerSelfDriftStale(filePath, isSelfDrift) {
+        const key = path.resolve(filePath);
+        const existing = this._pendingInlineBlockers.get(key);
+        if (!existing)
+            return false;
+        if (existing.stale && existing.staleReason !== "self-drift")
+            return false;
+        const currentlySelfDrift = !!existing.stale && existing.staleReason === "self-drift";
+        if (currentlySelfDrift === isSelfDrift)
+            return false;
+        // Omit the key rather than assigning `undefined` to it: under
+        // `exactOptionalPropertyTypes` those are different, and writing the
+        // `undefined` is a strictness spike the ratchet counts. Healing has to
+        // drop `staleReason` off the rebuilt record, so destructure it away
+        // instead of letting `...existing` carry the old value through.
+        const { staleReason: _cleared, ...rest } = existing;
+        this._pendingInlineBlockers.set(key, {
+            ...rest,
+            stale: isSelfDrift,
+            ...(isSelfDrift ? { staleReason: "self-drift" } : {}),
+        });
+        return true;
+    }
     /**
      * #1944: retire a past-EOF demotion after its ONE degraded delivery.
      *

package/node_modules/pi-lens/dist/clients/runtime-session.js

@@ -14,7 +14,7 @@ import { resetDispatchAvailabilityState } from "./dispatch/runners/utils/runner-
 import { resetObservedRunnerLatency } from "./dispatch/collect-later-tier.js";
 import { resetPendingRunnerFindings } from "./dispatch/pending-runner-findings.js";
 import { clearAllSessions as clearFileTimeSessions } from "./file-time.js";
-import { getGlobalPiLensDir, getKnipIgnorePatterns, getProjectDataDir, } from "./file-utils.js";
+import { drainProjectDataDirMigrations, getGlobalPiLensDir, getKnipIgnorePatterns, getProjectDataDir, resetProjectDataDirSessionState, } from "./file-utils.js";
 import { GitleaksClient } from "./gitleaks-client.js";
 import { resetGoAvailability } from "./go-client.js";
 import { GovulncheckClient, } from "./govulncheck-client.js";
@@ -1369,7 +1369,7 @@ function scheduleDeferredToolProbesWithClients(deps, languageProfile, startupDef
 export const SESSION_START_GUIDANCE = [
     "📌 pi-lens active — automated checks run on every edit/write; blocking errors (including pre-existing) show inline and must be fixed.\n" +
         "Key tools (see each tool's own description for args):\n" +
-        "• lens_diagnostics — source=session reads cache; empty cache ≠ clean; use source=lsp scope=paths for changed files with absent or stale findings.\n" +
+        "• lens_diagnostics — source=session reads cache; empty cache ≠ clean; use source=lsp scope=paths for changed files with absent or stale findings (aggregate hosts: lens(action=diagnostics)).\n" +
         "• symbol_search → module_report → read_symbol/read_enclosing — ranked identifier search, then navigable outline/callback handles + exact body reads; cheaper than reading a whole file before editing.\n" +
         "• Situational (activate via pi_lens_activate_tools): lsp_navigation, ast_grep_search, ast_grep_replace. Use ast_grep_search with dump=true to inspect AST nodes.",
 ];
@@ -1381,6 +1381,7 @@ export async function handleSessionStart(deps) {
     // every analyzer refused for the rest of the process — AGENTS.md defect
     // shape 17. The resident clients themselves are deliberately kept.
     resetAnalyzerBootstrapSessionState();
+    resetProjectDataDirSessionState();
     resetTestRunnerDelivery();
     // #2450 fix round 3, catalog shape 17: the "bridge unavailable" dbg latch
     // (`clients/lsp-mutation.ts`) is a process-lifetime once-per-session flag,
@@ -1900,6 +1901,24 @@ export async function handleSessionStart(deps) {
     // project data roots and machine-global registry root once per session start;
     // this is fire-and-forget and bounded so it never delays startup.
     const projectDataDir = getProjectDataDir(cwd);
+    // #2874: `getProjectDataDir` queues one migration per old-slug directory
+    // it renames (or finds coexisting with its hashed successor). Drain here
+    // so each migration emits one bounded record per session at most.
+    for (const migration of drainProjectDataDirMigrations()) {
+        const targetName = path.basename(migration.to);
+        const hash = targetName.match(/([0-9a-f]{8})$/)?.[1] ?? "unknown";
+        recordDegradationOnce({
+            kind: "data_dir_migrated",
+            subject: hash,
+            reason: migration.outcome === "renamed"
+                ? "using hashed directory after renaming legacy directory"
+                : migration.outcome === "coexisting"
+                    ? "using hashed directory because legacy and hashed directories both exist"
+                    : migration.outcome === "rename-failed"
+                        ? "using legacy directory after hashed-directory rename failure"
+                        : "using resolved directory after realpath fallback",
+        });
+    }
     // #1609 review F1: sweepOwnStagingFiles does not recurse, so the installer's
     // bin/ and tools/ subdirectories (clients/installer/index.ts's
     // GITHUB_BIN_DIR / TOOLS_DIR, now atomic-write.js writers too) need their