@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-lens/dist/clients/dead-code-client.js

@@ -15,6 +15,7 @@ import { createSubsystemLogger } from "./extension-log.js";
 import { incrementDegradationCount } from "./degradation-ledger.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { findLocalBinsAt, VENV_BIN_DIRS } from "./package-manager.js";
 import { findNearestMarkerRoot } from "./path-utils.js";
 import { getScratchTreeFnmatchPatterns } from "./scratch-tree-policy.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
@@ -171,22 +172,26 @@ export class PythonDeadCodeClient {
      * whatever happens to be active in the CALLING shell, not the project's
      * (#1731, discipline B — the same venv-first shape sqlfluff's binary
      * resolution already uses, `runner-helpers.ts` `createVenvFinder`).
+     *
+     * The directory list is the shared `VENV_BIN_DIRS` — this was a third
+     * private spelling of the same four venv directories, with a
+     * `process.platform` branch that meant the ubuntu lane never saw the
+     * `Scripts` half at all (defect shape 30).
+     *
+     * The search is a fixed lookup at `root` ONLY (`findLocalBinsAt`, no
+     * ancestor walk) — #2544 review round 3 folded this onto the shared
+     * ancestor walker, reasoning a monorepo package should find its
+     * repo-root venv, but that was an unrequested behaviour change with no
+     * #2514 defect behind it. Reverted in round 4 F2. `findLocalBinsAt`
+     * returns EVERY match at `root` rather than the first, because
+     * `doEnsureAvailable` probes candidates in order and must keep the
+     * `venv/` fallback when a `.venv/` vulture exists but cannot run.
      */
     venvCandidates(root) {
-        const isWin = process.platform === "win32";
-        const relPaths = isWin
-            ? [
-                path.join(".venv", "Scripts", "vulture.exe"),
-                path.join("venv", "Scripts", "vulture.exe"),
-            ]
-            : [
-                path.join(".venv", "bin", "vulture"),
-                path.join("venv", "bin", "vulture"),
-            ];
-        return relPaths
-            .map((rel) => path.join(root, rel))
-            .filter((full) => fs.existsSync(full))
-            .map((full) => ({ cmd: full, prefix: [] }));
+        return findLocalBinsAt(["vulture"], root, {
+            windowsExt: ".exe",
+            binDirs: VENV_BIN_DIRS,
+        }).map((full) => ({ cmd: full, prefix: [] }));
     }
     async doEnsureAvailable(root) {
         // Presence-gated, NOT auto-installed. vulture is a pure-Python package

package/node_modules/pi-lens/dist/clients/dead-code-logger.js

@@ -7,9 +7,9 @@
  */
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
-const LOG_DIR = getGlobalPiLensDir();
+const LOG_DIR = getGlobalPiLensLogDir();
 const LOG_FILE = path.join(LOG_DIR, "dead-code.log");
 const LOG_BACKUP_FILE = path.join(LOG_DIR, "dead-code.log.1");
 const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_DEAD_CODE_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);
@@ -28,7 +28,3 @@ export function logDeadCodeScan(event) {
         return;
     writer.log({ ts: new Date().toISOString(), ...event });
 }
-/** Resolve once all enqueued dead-code writes are on disk (tests/shutdown). */
-export function flushDeadCodeLog() {
-    return writer.flush();
-}

package/node_modules/pi-lens/dist/clients/deadline-utils.js

@@ -10,6 +10,7 @@
  * promise's late rejection (an unhandled rejection if the timer won first), and
  * `withinRemaining` never cleared its timer.
  */
+import { recordDegradationOnce } from "./degradation-ledger.js";
 /**
  * Combine multiple abort signals into one that aborts when ANY of them does.
  * Returns the single signal unchanged when only one is live, and `undefined`
@@ -100,3 +101,180 @@ export function withinRemaining(promise, deadlineAt) {
         onReject: "undefined",
     });
 }
+/**
+ * The abort half of a bound, as a value the race can settle on. A symbol, not
+ * `undefined`, so `bounded` can tell "the signal fired" from "the awaited work
+ * genuinely resolved `undefined`" — the distinction AGENTS.md defect shape 10
+ * (silencing counted as fixing) exists to protect.
+ */
+const BOUND_ABORTED = Symbol("pi-lens/bounded/aborted");
+/**
+ * Await `promise` under BOTH bounds a hook needs: a wall-clock budget AND the
+ * hook's own abort signal (#2523 AC2).
+ *
+ * ## Why the type refuses one bound
+ *
+ * Every bound in this codebase lived at a LEAF — a spawn timeout, an LSP wait
+ * — so a dependency that wedged before reaching the leaf was unreachable by
+ * all of them, and `wrapSessionEventHandler` adds neither. The two halves fail
+ * differently and neither substitutes for the other: a deadline alone means
+ * Escape cannot release the hook (measured: still blocked 30s after the abort
+ * fired), and a signal alone means a dependency that wedges without anyone
+ * pressing Escape never returns at all (measured: 400s, the harness ceiling).
+ * `ms` and `signal` are therefore both non-optional properties, so
+ * `bounded(p, { ms: 500, hook, label })` is a COMPILE error, not a review
+ * catch. `tests/clients/bounded-hook-await.test.ts` pins that with
+ * `@ts-expect-error`: weaken either property and those directives become
+ * unused, which `tsc` reports as TS2578.
+ *
+ * ## Semantics
+ *
+ * - Resolves to the promise's value when it settles inside both bounds.
+ * - Resolves to `undefined` when the budget elapses OR a signal aborts,
+ *   whichever comes first — and firing a signal settles IMMEDIATELY, it
+ *   never waits the remaining deadline out.
+ * - Rejections propagate: this helper decides how LONG to wait, never what an
+ *   error means. Once a bound has fired, a later rejection from the
+ *   superseded promise is suppressed (a no-op catch is attached to the work
+ *   up front) so it cannot surface as an unhandled rejection.
+ *
+ * ## What reaches the ledger, and what deliberately does not
+ *
+ * Which bound fired decides this, via {@link BoundCause}. Only the DEADLINE
+ * records `hook-await-exceeded` — ONE rising-edge row per (hook, label) via
+ * `recordDegradationOnce`, naming the hook, the await, the budget, the actual
+ * elapsed ms and the cause. Bounded by construction: a hook that blows its
+ * budget on every turn of a long session writes one ledger row, not one per
+ * turn. Promote it to `incrementDegradationCount` if slice 2 finds the exact
+ * tally is needed.
+ *
+ * A `"caller-abort"` records NOTHING. The caller's signal is the user pressing
+ * Escape or a turn being cancelled — a deliberate action, not a degraded
+ * environment. `clients/bootstrap.ts` already carries this lesson at its
+ * `if (unavailableReason !== "aborted")` guard: writing a cancel to the ledger
+ * made it indistinguishable from an unhealthy analyzer graph in
+ * `pilens_health`. This helper is meant to become THE bound primitive at
+ * ~187 call sites, so recording a cancel here would ship that inversion
+ * everywhere at once.
+ *
+ * A `"shutdown"` records `hook-await-abandoned`, which is in
+ * `INFORMATIONAL_DEGRADATION_KINDS` — teardown abandoning in-flight work is
+ * the design, so it is a tally rather than a `⚠`.
+ *
+ * `undefined` therefore means "no answer inside the bound" and must never be
+ * read as an empty/clean ANSWER (defect shape 10, and the #240 lesson that a
+ * failed diagnostic pull is not a clean file). The caller decides what the
+ * absence means; the ledger row is what makes it visible either way.
+ *
+ * The promise is not cancelled — nothing here can cancel work already
+ * started. It is abandoned, with the abandonment recorded. Work that must not
+ * outlive its hook needs the signal threaded INTO it as well (#2523 slice 2's
+ * `TurnEndDeps`/`AgentEndDeps`/`SessionStartDeps` change); wrapping the await
+ * bounds the HOOK, not the work.
+ */
+export async function bounded(promise, options) {
+    const { signal, shutdownSignal, hook, label } = options;
+    // A non-finite budget settles immediately rather than throwing. The type
+    // forbids it, but a JS caller (or a `@ts-expect-error` probe) can still
+    // hand one over, and `setTimeout(fn, NaN)` would fire on the next tick
+    // with a warning — a helper whose whole job is keeping a hook from blowing
+    // up must not itself misbehave inside one. Same
+    // `Number.isFinite`-before-`Math.max` gate the runtime-config readers use.
+    const ms = Number.isFinite(options.ms) ? Math.max(0, options.ms) : 0;
+    const startedAt = Date.now();
+    // Late rejection from work a bound has already abandoned must not surface
+    // as an unhandled rejection. Attached to the BOXED promise, which is what
+    // the race below actually subscribes to; the caller still sees a rejection
+    // that arrives inside the bounds, because `Promise.race` attaches its own
+    // handler to the same promise.
+    const boxed = promise.then((value) => ({ value }));
+    void boxed.catch(() => { });
+    // ONE timer and ONE listener per source signal, all released in `finally`
+    // (#2530 review F2/F4).
+    //
+    // The round-1 implementation folded the wall clock in as
+    // `AbortSignal.timeout(ms)` and combined it through `AbortSignal.any`,
+    // then ALSO passed `ms` to `withDeadline` — two timers for one budget, and
+    // a composite signal per call. `AbortSignal.any` does not add a listener
+    // to its sources: it appends the composite to an internal dependant list
+    // on each of them, which lives as long as the SOURCE does. The hook signal
+    // outlives one await by a whole turn, so 20 000 successful `bounded()`
+    // calls on one hook signal left 20 000 entries on it, and the `finally`'s
+    // `removeEventListener` — aimed at the throwaway composite — removed
+    // nothing from the source. Listening on the sources directly is what makes
+    // the cleanup reach the thing that outlives the call.
+    let cause;
+    let timer;
+    let onCallerAbort;
+    let onShutdownAbort;
+    const abandoned = new Promise((resolve) => {
+        // `abandonedError`'s precedence, unchanged: the caller's own signal
+        // first, then teardown, then the clock. A turn cancelled while the
+        // session also happens to be tearing down is still a cancel.
+        const fire = (reason) => {
+            cause ??= reason;
+            resolve(BOUND_ABORTED);
+        };
+        // `signal?.` — a missing signal is treated as one that never aborts.
+        // The KEY is required (so a call that never mentions a signal does not
+        // compile), but its type admits `undefined` because several seams
+        // genuinely hold `AbortSignal | undefined` — see `BoundedOptions.signal`
+        // for which ones and why. This branch is what lets them pass it straight
+        // through instead of each spelling its own never-aborting stand-in
+        // (#2557 review F2), and it is also what keeps a JS caller, or a
+        // `@ts-expect-error` probe, from making a helper whose whole job is
+        // keeping a hook from blowing up throw `Cannot read properties of
+        // undefined` (#2530 round 3 F5).
+        if (signal?.aborted)
+            return fire("caller-abort");
+        if (shutdownSignal?.aborted)
+            return fire("shutdown");
+        // A zero budget ("this hook may not await at all") is a bound that has
+        // already elapsed, not a timer to arm.
+        if (ms <= 0)
+            return fire("deadline");
+        timer = setTimeout(() => fire("deadline"), ms);
+        // Never hold the event loop open past the hook this bounds.
+        timer.unref?.();
+        onCallerAbort = () => fire("caller-abort");
+        signal?.addEventListener("abort", onCallerAbort, { once: true });
+        if (shutdownSignal) {
+            onShutdownAbort = () => fire("shutdown");
+            shutdownSignal.addEventListener("abort", onShutdownAbort, {
+                once: true,
+            });
+        }
+    });
+    try {
+        // The value is boxed so a promise that legitimately resolves
+        // `undefined` stays distinguishable from a bound firing (defect shape
+        // 10: a silenced answer must not read as a clean one).
+        const settled = await Promise.race([boxed, abandoned]);
+        if (settled !== BOUND_ABORTED)
+            return settled.value;
+        const elapsedMs = Date.now() - startedAt;
+        const fired = cause ?? "deadline";
+        // A caller's own abort is Escape or a cancelled turn — deliberate, not
+        // a degradation, and deliberately absent from the ledger.
+        if (fired === "deadline" || fired === "shutdown") {
+            recordDegradationOnce({
+                kind: fired === "deadline" ? "hook-await-exceeded" : "hook-await-abandoned",
+                subject: `${hook}:${label}`,
+                reason: fired === "deadline"
+                    ? `exceeded ${ms}ms budget after ${elapsedMs}ms`
+                    : `abandoned after ${elapsedMs}ms: session is shutting down (budget ${ms}ms)`,
+                metadata: { hook, label, budgetMs: ms, elapsedMs, cause: fired },
+            });
+        }
+        return undefined;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onCallerAbort)
+            signal?.removeEventListener("abort", onCallerAbort);
+        if (onShutdownAbort) {
+            shutdownSignal?.removeEventListener("abort", onShutdownAbort);
+        }
+    }
+}

package/node_modules/pi-lens/dist/clients/debug-handles.js

@@ -43,12 +43,12 @@
  */
 import * as asyncHooks from "node:async_hooks";
 import * as path from "node:path";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 /** Read once at module load — see module docstring. Not re-read per call. */
 const DEBUG_HANDLES_ENABLED = process.env.PI_LENS_DEBUG_HANDLES === "1";
-const DEBUG_HANDLES_LOG_FILE = path.join(getGlobalPiLensDir(), "debug-handles.log");
+const DEBUG_HANDLES_LOG_FILE = path.join(getGlobalPiLensLogDir(), "debug-handles.log");
 /** Cap on tracked in-flight creation sites (bounded past this). */
 export const TRACKER_MAX_ENTRIES = 500;
 /** The first N insertion-order entries are never evicted — see the module

package/node_modules/pi-lens/dist/clients/debug-heap.js

@@ -50,7 +50,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as v8 from "node:v8";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 /** Read once at module load — see module docstring. Not re-read per call. */
@@ -61,7 +61,7 @@ const DEBUG_HEAP_ENABLED = process.env.PI_LENS_DEBUG_HEAP === "1";
 export const SNAPSHOT_RETENTION = 3;
 const SNAPSHOT_PREFIX = "heap-";
 const SNAPSHOT_SUFFIX = ".heapsnapshot";
-const HEAP_SNAPSHOT_LOG_FILE = path.join(getGlobalPiLensDir(), "heap-snapshots.log");
+const HEAP_SNAPSHOT_LOG_FILE = path.join(getGlobalPiLensLogDir(), "heap-snapshots.log");
 // Only ever constructed when the flag is on — the entire cost of this module
 // when unset is the one boolean check at the top of each export below.
 const writer = DEBUG_HEAP_ENABLED
@@ -138,7 +138,7 @@ export function pruneOldSnapshots(dir, keep = SNAPSHOT_RETENTION) {
 export function writeHeapSnapshotNow(label) {
     if (!DEBUG_HEAP_ENABLED)
         return null;
-    const dir = getGlobalPiLensDir();
+    const dir = getGlobalPiLensLogDir();
     try {
         fs.mkdirSync(dir, { recursive: true });
     }

package/node_modules/pi-lens/dist/clients/deferred-lsp-work.js

@@ -0,0 +1,106 @@
+/**
+ * The one owner of "work that keeps talking to the LSP service after the hook
+ * that started it has returned" (#2504 review round 2, F3).
+ *
+ * #2504 moved the cold-cache actionable-warnings fresh-pull loop off the
+ * awaited `turn_end` hook. That loop then had effectively ONE bound: it
+ * captured the COMPLETED turn's `ctx.signal` — which `index.ts` clears from
+ * the ambient slot in its `finally`, so it can never fire — plus a 60 s wall
+ * deadline checked only BETWEEN files. A wedged `getDiagnostics` was therefore
+ * unbounded, the loop kept opening files (and could re-spawn servers) after
+ * `turn_end` returned and after the LSP idle reset, a `session_shutdown`
+ * landing mid-loop hit the #234 spawn-at-teardown shape, and the handle was a
+ * module-level `let` with no reset that a second deferral simply overwrote.
+ *
+ * This module supplies the missing halves: ONE registered handle (held by
+ * whichever deferral got there first, released when its work settles — see
+ * `armDeferredLspWork`) and ONE abort signal that
+ * `resetLSPService` fires — the single choke point through which
+ * `session_shutdown`, `session_start` and the idle reset all retire the
+ * service, so no caller has to remember to wire each lifecycle event
+ * separately. Aborting only ever settles a promise; it never spawns, which is
+ * what AGENTS.md's #234 teardown rule requires of anything reachable from
+ * `session_shutdown`.
+ *
+ * Deliberately a zero-dependency leaf, for the same reason
+ * `map-with-concurrency.ts` is one: `clients/lsp/index.ts` must not gain an
+ * import edge to `actionable-warnings.ts` (and through it `lsp/edits.ts`,
+ * `lsp-mutation.ts`, the durable store …) for a 20-line handle registry.
+ */
+let deferredController;
+let deferredWork;
+/**
+ * Abort the in-flight deferred LSP work, if any, and drop the slot.
+ *
+ * Safe at teardown: it settles a promise and spawns nothing. Idempotent — a
+ * second call with no armed work is a no-op.
+ */
+export function abortDeferredLspWork(reason) {
+    const controller = deferredController;
+    deferredController = undefined;
+    deferredWork = undefined;
+    controller?.abort(new Error(reason));
+}
+/**
+ * Claim the deferred-work slot, or `undefined` when an incumbent still holds
+ * it. THE INCUMBENT WINS (#2504 review round 3, F-A(d)).
+ *
+ * Round 2 had arming ABORT the previous deferral, reasoning that two loops
+ * must not run concurrently against one LSP service. The first half of that is
+ * right and still holds — there is exactly one slot. The second half was
+ * backwards about which loop to keep. A deferral is armed by a turn that
+ * primed NO LSP cache, which in a live editing session is every turn; so every
+ * turn cancelled its predecessor, and an aborted loop publishes nothing by
+ * design (its service is presumed gone). Back-to-back editing turns therefore
+ * delivered NOTHING AT ALL — the exact delivery AC #2504 exists to preserve.
+ *
+ * Keeping the incumbent inverts that: the loop that is already talking to the
+ * service runs to completion and publishes, and the newcomer is declined and
+ * says so out loud. The cost is stated rather than silent — the declining
+ * turn's cold files go unchecked on this channel until a later turn defers.
+ *
+ * Declining cannot latch. `registerDeferredLspWork` releases the slot the
+ * moment the work settles, and the loop itself is bounded twice over
+ * (`ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS` between files, a per-round-trip
+ * timeout inside them), so an incumbent always yields the slot in bounded
+ * time. Teardown is unaffected: `abortDeferredLspWork` still evicts the
+ * incumbent unconditionally, which is how `resetLSPService` retires it.
+ */
+export function armDeferredLspWork() {
+    if (isDeferredLspWorkArmed())
+        return undefined;
+    const controller = new AbortController();
+    deferredController = controller;
+    deferredWork = undefined;
+    return controller.signal;
+}
+/**
+ * Register the armed work's promise so callers (and tests) have something to
+ * await. Ignored when the slot has already been re-armed or aborted since — a
+ * late registration must not resurrect a retired handle.
+ *
+ * Registration also arranges the RELEASE (#2504 review round 3, F-A(d)):
+ * because the slot now turns a newcomer away rather than evicting the
+ * incumbent, something has to hand it back, and the only correct moment is
+ * when the work settles. Guarded on identity, so a slot re-armed or aborted in
+ * the meantime is never cleared by a stale finalizer.
+ */
+export function registerDeferredLspWork(signal, work) {
+    if (deferredController?.signal !== signal)
+        return;
+    deferredWork = work;
+    void work.finally(() => {
+        if (deferredController?.signal !== signal)
+            return;
+        deferredController = undefined;
+        deferredWork = undefined;
+    });
+}
+/** The in-flight deferred work, or an already-resolved promise when idle. */
+export function awaitDeferredLspWork() {
+    return deferredWork ?? Promise.resolve();
+}
+/** True while a deferral holds the slot and has not been aborted. */
+export function isDeferredLspWorkArmed() {
+    return deferredController?.signal.aborted === false;
+}

package/node_modules/pi-lens/dist/clients/degradation-ledger.js

@@ -1,17 +1,25 @@
 /** Bounded, process-local telemetry for behavior degraded during one session. */
 import { logExtension } from "./extension-log.js";
-import { LEDGER_FIELD_MAX, truncateForLedger } from "./ledger-bounds.js";
+import { DEGRADATION_ENTRIES_PER_KIND, LEDGER_FIELD_MAX, truncateForLedger, } from "./ledger-bounds.js";
 import { logLatency } from "./latency-logger.js";
-import { getSinkWriteFailures, resetSinkWriteFailures, } from "./ndjson-logger.js";
+import { getSinkRotations, getSinkWriteFailures, resetSinkRotations, resetSinkWriteFailures, } from "./ndjson-logger.js";
 // #2146: pulled at READ time, never pushed. `process-singletons.ts` is a
 // dependency leaf on purpose — it cannot import this module without closing a
 // no-client-cycles cycle through instance-registry/instance-reaper — so the
 // ledger reaches IN for its reset log, the same inversion `getSinkWriteFailures`
 // above uses.
 import { getProcessSingletonResets, PROCESS_SINGLETON_RESET_KIND, } from "./process-singletons.js";
+// #2506: same inversion, same reason — the log-dir resolver cannot import this
+// module (directly OR dynamically). THIS module is on a no-client-cycles cycle
+// via extension-log.ts; the resolver's whole correctness argument is that it
+// sits off every cycle, so an edge in that direction would put it back on one.
+// `getGlobalPiLensLogDir()`'s probe-home-redirect event is therefore written
+// into `probe-home-state.ts` and read back here instead. See that module's doc
+// comment for the full account.
+import { getProbeHomeRedirectEvent } from "./probe-home-state.js";
 // Re-exported so existing importers keep one name for the ledger's bound.
 export { LEDGER_FIELD_MAX, truncateForLedger };
-const ENTRIES_PER_KIND = 20;
+const ENTRIES_PER_KIND = DEGRADATION_ENTRIES_PER_KIND;
 const MAX_DISTINCT_KINDS = 32;
 const OVERFLOW_KIND = "other";
 const groups = new Map();
@@ -65,7 +73,7 @@ export function recordDegradationOnce(record) {
             return;
         onceKeys.add(key);
         if (recordDegradation({ kind, subject, reason: record.reason })) {
-            logDurableDegradation(kind, subject, 1, record.metadata);
+            logDurableDegradation(kind, subject, 1, record.metadata, record.code);
         }
     }
     catch (error) {
@@ -114,7 +122,7 @@ export function incrementDegradationCount(record) {
         // Durable rows use the summary's admission and emit the first event and
         // power-of-two milestones only, keeping the sink bounded.
         if (admitted && isPowerOfTwo(count)) {
-            logDurableDegradation(kind, subject, count, record.metadata);
+            logDurableDegradation(kind, subject, count, record.metadata, record.code);
         }
         return count === 1;
     }
@@ -130,7 +138,7 @@ export function incrementDegradationCount(record) {
  * redaction, and write queue. The subject and kind were already bounded by the
  * ledger before reaching this seam.
  */
-function logDurableDegradation(kind, subject, count, metadata) {
+function logDurableDegradation(kind, subject, count, metadata, code) {
     const boundedMetadata = boundLedgerMetadata(metadata);
     logLatency({
         type: "phase",
@@ -143,6 +151,9 @@ function logDurableDegradation(kind, subject, count, metadata) {
             subject,
             count,
             ledgerGeneration,
+            // Reserved row field, written AFTER the bounded caller metadata so the
+            // `MAX_METADATA_KEYS` cap cannot evict the stable code (#2418).
+            ...(code ? { code } : {}),
         },
     });
 }
@@ -190,6 +201,38 @@ export function getDegradationSummary() {
             })),
         });
     }
+    // #2505, same read-time fold: a mid-session rotation is visible without
+    // this module writing about it through the very sink family it is
+    // reporting on — see the `log-sink-rotated` doc comment on
+    // `DegradationKind`.
+    const sinkRotations = getSinkRotations();
+    const rotated = sinkRotations.filter((sink) => sink.rotationCount > 0);
+    if (rotated.length > 0) {
+        summary.push({
+            kind: "log-sink-rotated",
+            count: rotated.reduce((total, sink) => total + sink.rotationCount, 0),
+            droppedCount: 0,
+            latestReasons: rotated.map((sink) => ({
+                subject: truncateForLedger(sink.file),
+                reason: truncateForLedger(`${sink.rotationCount} rotation(s) at the configured byte bound`),
+            })),
+        });
+    }
+    // A rotation the writer ATTEMPTED and could not complete is a different
+    // fact from a rotation that happened, and the only signal that a sink is
+    // growing past its bound right now (#2505 review F2).
+    const rotateFailed = sinkRotations.filter((sink) => sink.failureCount > 0);
+    if (rotateFailed.length > 0) {
+        summary.push({
+            kind: "log-sink-rotate-failed",
+            count: rotateFailed.reduce((total, sink) => total + sink.failureCount, 0),
+            droppedCount: 0,
+            latestReasons: rotateFailed.map((sink) => ({
+                subject: truncateForLedger(sink.file),
+                reason: truncateForLedger(`${sink.failureCount} failed rotation attempt(s); this sink is growing past its byte bound`),
+            })),
+        });
+    }
     // #2146, same read-time fold: process-singleton resets live in the leaf
     // module's own bounded log. One entry per family, so this group's count is
     // the number of families this build could not adopt, never an event tally.
@@ -205,6 +248,23 @@ export function getDegradationSummary() {
             })),
         });
     }
+    // #2506, same read-time fold: `getGlobalPiLensLogDir()`'s probe-home redirect
+    // fires at most once per process (see `probe-home-state.ts`), so this is a
+    // presence check, not a tally.
+    const probeHomeRedirect = getProbeHomeRedirectEvent();
+    if (probeHomeRedirect) {
+        summary.push({
+            kind: "global-dir-probe-redirect",
+            count: 1,
+            droppedCount: 0,
+            latestReasons: [
+                {
+                    subject: truncateForLedger(probeHomeRedirect.probeHome),
+                    reason: truncateForLedger(`PI_LENS_HOME unset with cwd in an agent worktree/tmp probe context (${probeHomeRedirect.cwd}), or PILENS_PROBE=1 forced it; LOGS redirected away from the real home directory (tools, bin and instances.json are unaffected)`),
+                },
+            ],
+        });
+    }
     return summary;
 }
 function isRenderableSummary(value) {
@@ -223,6 +283,34 @@ function isRenderableSummary(value) {
                 typeof entry.reason === "string"));
     });
 }
+/**
+ * Kinds that record something the system did ON PURPOSE, correctly, and
+ * that a reader only needs a tally of — never a call to action (#2505
+ * review). A routine log rotation at the configured bound is the writer
+ * working as designed; giving it the same warning marker a real
+ * degradation gets trains the reader to ignore the marker. The FAILED
+ * rotation is the line that has to stand out, so it is deliberately NOT
+ * in this set.
+ */
+const INFORMATIONAL_DEGRADATION_KINDS = new Set([
+    "log-sink-rotated",
+    // #2504 review round 8 (S1): both fire on the ordinary re-edit cadence
+    // (a carry-forward window closing, or a session boundary) and are
+    // self-healing -- the next turn's analysis or deferral re-observes the
+    // file -- so a `⚠` overstates them the same way a routine log rotation
+    // would.
+    "actionable-warnings-inband-superseded",
+    "actionable-warnings-deferred-superseded",
+    // #2523: a hook await abandoned because the session is tearing down. The
+    // teardown signal firing is the design working, so it is a tally; the
+    // BUDGET blow-out (`hook-await-exceeded`) is the line that has to stand
+    // out, and a caller's own Escape records nothing at all.
+    "hook-await-abandoned",
+    // #2524: can fire on a query that ultimately settles `ok` (see the kind's
+    // doc comment above) and is frequent/self-healing by design — a `⚠` would
+    // cry wolf on the sampler's ordinary best-effort data loss.
+    "resource-sampler-scanner-escalated",
+]);
 export function renderDegradationLines(summary = getDegradationSummary()) {
     if (!isRenderableSummary(summary))
         return [];
@@ -231,6 +319,9 @@ export function renderDegradationLines(summary = getDegradationSummary()) {
     return [
         "Degradations:",
         ...summary.map((group) => {
+            if (INFORMATIONAL_DEGRADATION_KINDS.has(group.kind)) {
+                return `  ${group.kind}: ${group.count}`;
+            }
             const latest = group.latestReasons.at(-1);
             return `  ⚠ ${group.kind}: ${group.count}${latest ? ` — ${latest.subject}: ${latest.reason}` : ""}`;
         }),
@@ -258,6 +349,10 @@ export function resetDegradationLedger() {
     // process-lifetime latch too — it re-arms alongside the rest of the
     // ledger rather than surviving past the session that observed it.
     resetSinkWriteFailures();
+    // #2505, same catalog shape 17 re-arm: a rotation tally recurs (new writes
+    // keep crossing the bound), so clearing it costs nothing and a later
+    // session re-observes the fact fresh.
+    resetSinkRotations();
     // #2146 review F3: the OTHER pulled source, `getProcessSingletonResets()`,
     // deliberately does NOT re-arm here, and the difference from its neighbour
     // above is the point. A sink write failure recurs — new writes fail, so
@@ -270,6 +365,17 @@ export function resetDegradationLedger() {
     // session (one entry per family, capped at 16), so leaving it costs a fixed
     // handful of lines and keeps a process-scope fact visible for the process's
     // life. Deliberate exception to catalog shape 17, not an oversight.
+    //
+    // `getProbeHomeRedirectEvent()` (#2506) is the same shape as the
+    // process-singleton case above and for the same reason: the redirect is
+    // resolved at most once per PROCESS (memoized in the `globalThis` slot
+    // `probe-home-state.ts` owns, not a session-scoped one), so it cannot
+    // recur within this process's life either — clearing it here would hide
+    // the fact from every session after the first in the same probe process.
 }
-export const DEGRADATION_ENTRIES_PER_KIND = ENTRIES_PER_KIND;
+// Re-exported so every existing importer keeps its specifier. The value now
+// lives in the `ledger-bounds.js` leaf (#2426), so a producer that only needs
+// the BOUND does not have to import the ledger — and cannot be broken by a test
+// that mocks it wholesale.
+export { DEGRADATION_ENTRIES_PER_KIND };
 export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;

package/node_modules/pi-lens/dist/clients/dependency-checker.js

@@ -11,6 +11,7 @@
 import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { mapWithConcurrency } from "./map-with-concurrency.js";
 import { findNodeToolBinary } from "./package-manager.js";
 import { isFullyQualified } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
@@ -138,28 +139,16 @@ async function resolvedCommandIsStale(resolved, spawnableCache) {
 }
 /**
  * Run `mapper` over `items` with at most `concurrency` in flight at once.
+ *
  * Exported (#1810 review F6) so `clients/dispatch/runners/biome-check.ts`'s
  * `resolveBiomeFixKinds` can reuse this exact worker-pool shape for its
- * `biome explain` fan-out instead of carrying a second copy — this file
- * predates that need but is otherwise unrelated to it; a shared home for
- * this one helper wasn't worth a whole new module for two call sites.
+ * `biome explain` fan-out instead of carrying a second copy. #2504 moved the
+ * VALUE to the zero-dependency `map-with-concurrency.js` leaf — a third caller
+ * (`runtime-turn.ts`) needs the pool without pulling this analyzer client into
+ * the eager startup graph — and re-exports it here so every existing importer
+ * keeps its specifier. This stays the helper's documented home.
  */
-export async function mapWithConcurrency(items, concurrency, mapper) {
-    if (items.length === 0)
-        return;
-    let nextIndex = 0;
-    const workerCount = Math.max(1, Math.min(concurrency, items.length));
-    const worker = async () => {
-        while (true) {
-            const index = nextIndex++;
-            if (index >= items.length)
-                return;
-            await mapper(items[index]);
-        }
-    };
-    const workers = Array.from({ length: workerCount }, () => worker());
-    await Promise.all(workers);
-}
+export { mapWithConcurrency };
 // --- Client ---
 export class DependencyChecker {
     madgeAvailability = createAvailabilityChecker("madge", ".cmd", ["--version"], {

package/node_modules/pi-lens/dist/clients/diagnostic-dispositions.js

@@ -128,7 +128,7 @@ export function computeStrictAnchor(args) {
     });
 }
 /** Intent-level anchor — see module doc. Used for defer/flagged/suppress. */
-export function computeWeakAnchor(args) {
+function computeWeakAnchor(args) {
     return stableFindingId("ddw:", {
         cwd: args.cwd,
         filePath: args.filePath,