@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/blocker-past-eof.js

@@ -0,0 +1,119 @@
+/**
+ * Past-EOF validity gate for the turn-end inline-blocker store (#1641
+ * remainder).
+ *
+ * #1664 wired `demotePastEofDiagnostics` into every surface that renders a
+ * `WidgetDiagnostic` — widget-state, `lens_diagnostics` (`mode=all`/`full`),
+ * and the TUI blocking-render loop. It deliberately deferred one surface:
+ * `RuntimeCoordinator`'s `_pendingInlineBlockers` map (the "Unresolved from
+ * this turn" blocker re-served at `turn_end`, `clients/runtime-turn.ts`).
+ * That store's records (`InlineBlockerRecord`) never carried a `WidgetDiagnostic`
+ * — just a rendered `summary` string — so the shared gate had nothing to run
+ * against. #1633 was meant to add the structured line field and never did;
+ * it merged with only the dependency-drift gate (`blocker-freshness.ts`)
+ * wired in. This module is that missing half.
+ *
+ * Design choice (#1641 remainder, decided here): carry a STRUCTURED `lines`
+ * field on `InlineBlockerRecord`, captured at write time from the same
+ * `Diagnostic[]` the summary text was rendered from
+ * (`dispatchResult.blockers` in `pipeline.ts`), rather than regex-parsing the
+ * cited line back out of the rendered summary prose. Re-deriving a number
+ * that was already in hand one call earlier — by parsing a string built for
+ * human display, not machine reading — is exactly the re-derivation-vs-
+ * correlation screen's failure shape: any future change to the summary's
+ * wording (a different prefix, a renamed tool label) would silently break
+ * the parse with no type error. Threading the number through is one field on
+ * an existing interface and a few lines at each hop.
+ *
+ * Composition with #1631's dependency-drift gate (`blocker-freshness.ts`,
+ * also swept at `turn_end`): each gate demotes with its own
+ * `InlineBlockerRecord.staleReason` and only re-derives (heals) entries
+ * carrying its OWN reason — `setInlineBlockerPastEofStale` refuses to touch a
+ * `"dependency-drift"` demotion, and this gate skips a record already
+ * demoted for that reason before it even computes a verdict. The two gates
+ * therefore layer rather than race: whichever ran first "wins" the record for
+ * this turn, and the other's condition is picked up again once the first
+ * heals or a fresh dispatch/retire clears the record outright.
+ *
+ * RE-ARMS, never latches (mirrors `demotePastEofDiagnostics`): the verdict is
+ * recomputed from the file's CURRENT line count on every turn end, so a
+ * transient shrink-then-restore un-demotes on its own next turn without any
+ * session-lifetime flag to reset.
+ */
+import { demotePastEofDiagnostics, resyncDocumentOnPastEof, } from "./diagnostic-line-freshness.js";
+/**
+ * Past-EOF sweep over the cached inline blockers. Called at turn end
+ * alongside (and, per the module doc, ordered before) the dependency-drift
+ * sweep — a cheap `statSync` per file is worth paying first so the pricier
+ * import-parsing sweep can skip anything this gate already took out of the
+ * authoritative channel.
+ *
+ * Never throws: a per-entry failure leaves that entry untouched rather than
+ * failing the turn end.
+ */
+export function sweepInlineBlockerPastEof(runtime, cwd, options) {
+    const counts = {
+        total: 0,
+        checked: 0,
+        demoted: 0,
+        healed: 0,
+    };
+    const resync = options?.resync ?? resyncDocumentOnPastEof;
+    let entries;
+    try {
+        entries = runtime.getInlineBlockersSnapshot();
+    }
+    catch {
+        return counts;
+    }
+    counts.total = entries.length;
+    for (const entry of entries) {
+        try {
+            if (!entry.lines || entry.lines.length === 0)
+                continue;
+            // Not this gate's demotion to heal or re-assert (#1641 composition
+            // rule — see module doc).
+            if (entry.stale && entry.staleReason !== "past-eof")
+                continue;
+            counts.checked += 1;
+            // Reuse the shared gate's per-line verdict machinery: feed it one
+            // synthetic "diagnostic" per cited line, sharing this record's
+            // current stale/staleReason so it can detect the rising/falling
+            // edge itself instead of this module re-implementing that logic.
+            const probes = entry.lines.map((line) => ({
+                line,
+                stale: entry.stale,
+                staleReason: entry.staleReason,
+            }));
+            // `demotePastEofDiagnostics` already logs (`diagnostic_past_eof`) and
+            // fires `resync` exactly once per call on a rising edge — reusing it
+            // here (rather than re-implementing that bookkeeping) keeps this
+            // gate's telemetry and resync-on-demotion behavior identical to the
+            // widget/lens surfaces #1664 already wired.
+            const { diagnostics } = demotePastEofDiagnostics({
+                store: "inline-blocker",
+                cwd,
+                filePath: entry.filePath,
+                diagnostics: probes,
+                lineCountCache: options?.lineCountCache,
+                resync,
+            });
+            // The record cites any of its lines being past EOF as a whole-record
+            // demotion — one summary string, not one flag per line.
+            const isPastEof = diagnostics.some((d) => d.stale);
+            const transitioned = runtime.setInlineBlockerPastEofStale(entry.filePath, isPastEof);
+            if (!transitioned)
+                continue;
+            if (isPastEof) {
+                counts.demoted += 1;
+            }
+            else {
+                counts.healed += 1;
+            }
+        }
+        catch {
+            // Per-entry failure: leave the entry as-is.
+        }
+    }
+    return counts;
+}

package/node_modules/pi-lens/dist/clients/bootstrap.js

@@ -47,6 +47,14 @@ async function logBootstrapFailures(failures) {
         // the per-analyzer lines above already named the failures
     }
 }
+/**
+ * Every per-client load below is individually fail-soft (`load`/`loadList`
+ * degrade to a stub instead of throwing), so this promise is not expected to
+ * reject in practice. It is still memoized with eviction-on-rejection —
+ * consistent with the other lazy-import memos (#1570) — so a genuinely
+ * unexpected throw (e.g. `logBootstrapFailures`) cannot latch a permanently
+ * rejected bootstrap for the rest of the process.
+ */
 export function loadBootstrapClients() {
     bootstrapPromise ??= (async () => {
         const failures = [];
@@ -112,6 +120,9 @@ export function loadBootstrapClients() {
             agentBehaviorClient,
             deadCodeClients,
         };
-    })();
+    })().catch((err) => {
+        bootstrapPromise = null;
+        throw err;
+    });
     return bootstrapPromise;
 }

package/node_modules/pi-lens/dist/clients/bounded-pid-file-lock.js

@@ -57,9 +57,18 @@ async function releaseQuarantineLock(lockPath, token) {
     }
 }
 function quarantineOwnerIsStale(owner, staleMs) {
-    return Number.isInteger(owner.pid) && owner.pid > 0 &&
-        Number.isFinite(owner.createdAt) &&
-        (!ownerPidIsLive(owner.pid) || Date.now() - owner.createdAt > staleMs);
+    // #1816: the two staleness signals are INDEPENDENT, and the original
+    // conjunction made the dead-PID one unreachable. An `owner.json` with a
+    // valid PID but a missing or non-numeric `createdAt` (an older writer, a
+    // half-written file, a hand-edited one) short-circuited on the
+    // `Number.isFinite` guard, so a dead owner never reclaimed and the lock
+    // stayed poisoned for the life of the directory. This is
+    // `installer/index.ts:173`'s predicate: a dead PID reclaims regardless of
+    // `createdAt`, and an aged lock reclaims regardless of what the PID says.
+    const pidUsable = Number.isInteger(owner.pid) && owner.pid > 0;
+    if (pidUsable && !ownerPidIsLive(owner.pid))
+        return true;
+    return (Number.isFinite(owner.createdAt) && Date.now() - owner.createdAt > staleMs);
 }
 async function reclaimQuarantineLock(lockPath, staleMs) {
     const quarantined = quarantinePath(lockPath, `reclaim-${Date.now()}-${randomUUID()}`);

package/node_modules/pi-lens/dist/clients/bounded-telemetry.js

@@ -0,0 +1,192 @@
+/**
+ * Typed bounded telemetry emission (#1743).
+ *
+ * Four PRs in two days hand-built the same machinery: a failure path that
+ * needs a detailed `latency.log` record, an exact per-identity tally, and a
+ * bound so a storming subsystem cannot flood the log. #1705 (orphan
+ * forensics), #1717 (pull timeouts and late answers), #1726 (navRequest
+ * timeouts, rising edge per method and file), and #1733 (loop-block floor
+ * with a per-turn bound) each rebuilt it, and each needed a review round to
+ * get the bounding right. This module is the intersection of those four, not
+ * a speculative framework. Three of its four options come straight from those
+ * sites. The fourth, `capPerTurn`, expresses #1733's per-turn bound
+ * structurally but has no caller yet: that site's bound is its call cadence,
+ * and pinning a cap there would red its own wiring tests. It ships tested and
+ * mutation-proofed, awaiting its first site.
+ *
+ * Three rules the helper makes structural instead of prose:
+ *
+ * 1. **The rising edge comes from the ledger's own tally.** #1705 established
+ *    that `incrementDegradationCount` already knows whether a
+ *    (kind, subject) pair is being seen for the first time, and returns it.
+ *    A caller that wants "log the detail once, count the rest" reads that
+ *    return value. It never keeps a second `Set` — a parallel latch is state
+ *    that must re-arm at `session_start` and will eventually be forgotten
+ *    (the #1266–#1625 defect class).
+ * 2. **A per-turn cap names its turn.** `capPerTurn` carries the caller's
+ *    `turnIndex` in the same object as the limit, so there is no separate
+ *    reset to wire and forget: the counters clear when the observed turn
+ *    changes. This is the same lazy clear-on-transition shape as
+ *    `noteImportResolutionMemoTurn` (`clients/blocker-freshness.ts`).
+ * 3. **Identity always survives.** Every emitted record carries the
+ *    discriminating identity in `filePath` and in `metadata.identity`, so
+ *    aggregation can still answer "which file, which method, which record is
+ *    stuck" (the rule AGENTS.md states, now enforced by the signature).
+ *
+ * `BOUNDED_TELEMETRY_PHASES` is the registry.
+ * `tests/clients/bounded-telemetry-sweep.test.ts` sweeps it registered-or-
+ * fail: a failure-path phase must either route through this helper or carry a
+ * stated reason for staying raw.
+ *
+ * Nothing here ever throws. Telemetry must not perturb the path it observes —
+ * every one of the four migrated sites had already decided its outcome before
+ * calling in.
+ */
+import { incrementDegradationCount } from "./degradation-ledger.js";
+import { logLatency } from "./latency-logger.js";
+/**
+ * Phases that emit through this helper. The `phase` parameter is typed to
+ * this list, so a new bounded phase cannot be emitted without joining the
+ * registry, and the sweep proves the reverse direction: a registered phase
+ * must not also be written by a raw `logLatency` call somewhere else.
+ */
+export const BOUNDED_TELEMETRY_PHASES = [
+    /** #1705: a deferred-format record whose origin worktree never claimed it. */
+    "agent_end_deferred_format_orphan_origin_mismatch",
+    /** #1713: a `textDocument`/`workspace` diagnostic pull abandoned at budget. */
+    "lsp_pull_diagnostic_timeout",
+    /** #1713: that abandoned pull answered anyway, too late to serve anyone. */
+    "lsp_pull_late_answer_discarded",
+    /** #1773: a pull skipped outright because the caller's budget was already
+     *  exhausted — never dispatched, so it must not be confused with a genuine
+     *  timeout. */
+    "lsp_pull_skipped_budget_exhausted",
+    /** #1774: an abandoned pull's request eventually REJECTED (e.g. a server
+     *  `ContentModified`) rather than answering or staying silent forever —
+     *  the third outcome late-answer telemetry previously could not see. */
+    "lsp_pull_late_rejection",
+    /** #1716: a hover/definition/references/etc. request abandoned at budget. */
+    "lsp_nav_request_timeout",
+    /** #1716: that abandoned nav request answered anyway, after the caller left. */
+    "lsp_nav_late_answer_discarded",
+    /**
+     * #1743 review: a per-file touch skipped a server in breaker cooldown or
+     * latched permanently broken. Fires once per file per touch during an
+     * outage, so it is rising-edge per (server, file).
+     */
+    "lsp_client_skipped_broken",
+    /** #1743 review: the same skip, for a temporarily unavailable command. */
+    "lsp_client_skipped_unavailable_command",
+    /**
+     * #1723: an event-loop block at or above the floor. Not a degradation, so
+     * no ledger kind; bounded by call cadence (one `turn_end` runs it once per
+     * turn) rather than by an option here.
+     */
+    "loop_block",
+];
+const REGISTERED_PHASES = new Set(BOUNDED_TELEMETRY_PHASES);
+/** Report whether a phase name is in the registry (used by the sweep). */
+export function isBoundedTelemetryPhase(phase) {
+    return REGISTERED_PHASES.has(phase);
+}
+/**
+ * Per-turn admission counters, keyed by phase. Cleared lazily when a call
+ * observes a turn index different from the one the counters were built for,
+ * and eagerly by `resetBoundedTelemetry` at `session_start` (a new session
+ * restarts turn numbering at 0, so the lazy check alone could carry a stale
+ * count across a session boundary that happened to land on the same index).
+ */
+let turnCounts = new Map();
+let countedTurnIndex;
+/**
+ * Decide whether this occurrence earns a detailed record, and count it in the
+ * ledger either way. Returns `true` when the caller should write the record.
+ *
+ * Split out from `emitBounded` for the #1705 shape: that site loops over N
+ * abandoned records, admits each one, and then writes ONE batched
+ * `logLatency` naming only the admitted ones. A helper that could only emit
+ * per-call would have turned one record into N.
+ */
+export function admitBounded(phase, identity, options = {}) {
+    try {
+        let isRisingEdge = true;
+        if (options.ledgerKind !== undefined) {
+            // `subject` is the identity, unmodified: the ledger's per-subject
+            // entry is what tells a reader WHICH file or method is stuck after
+            // the detailed records stop.
+            isRisingEdge = incrementDegradationCount({
+                kind: options.ledgerKind,
+                subject: identity,
+                reason: options.reason ?? phase,
+            });
+        }
+        if (options.risingEdgePer !== undefined && !isRisingEdge)
+            return false;
+        return admitAgainstTurnCap(phase, options.capPerTurn);
+    }
+    catch {
+        // Telemetry must never break the observed path. Emitting is the safer
+        // failure: an extra record is noise, a swallowed one is a blind spot.
+        return true;
+    }
+}
+/**
+ * Count every occurrence in the ledger, then write ONE bounded `latency.log`
+ * record if this occurrence is admitted. Returns whether the record was
+ * written, so a caller can branch on it (all four migrated sites either
+ * ignore it or, in #1705's case, use `admitBounded` directly).
+ */
+export function emitBounded(phase, identity, payload, options = {}) {
+    try {
+        if (!admitBounded(phase, identity, options))
+            return false;
+        logLatency({
+            ...payload,
+            type: payload.type ?? "phase",
+            phase,
+            // `filePath` is what existing latency.log queries filter on, so a site
+            // may keep a coarser one; `metadata.identity` below always carries the
+            // full discriminating identity. Aggregation that loses WHICH subject
+            // is stuck is the failure AGENTS.md names.
+            filePath: payload.filePath ?? identity,
+            metadata: { ...payload.metadata, identity },
+        });
+        return true;
+    }
+    catch {
+        // Telemetry must never break the observed path.
+        return false;
+    }
+}
+/**
+ * Apply the per-turn ceiling. Separated so the turn-rollover clear happens in
+ * exactly one place: a cap and its reset drifting apart is how #1733's
+ * compensating-pair guards got past review.
+ */
+function admitAgainstTurnCap(phase, cap) {
+    if (cap === undefined)
+        return true;
+    if (countedTurnIndex !== cap.turnIndex) {
+        turnCounts = new Map();
+        countedTurnIndex = cap.turnIndex;
+    }
+    const used = turnCounts.get(phase) ?? 0;
+    if (used >= cap.limit)
+        return false;
+    turnCounts.set(phase, used + 1);
+    return true;
+}
+/**
+ * Session-boundary/test reset. The rising-edge state is NOT here — it lives
+ * in the degradation ledger, which `handleSessionStart` already re-arms via
+ * `resetDegradationLedger`. Only the per-turn counters are this module's own,
+ * and they need this because turn numbering restarts at 0 each session.
+ */
+export function resetBoundedTelemetry() {
+    turnCounts = new Map();
+    countedTurnIndex = undefined;
+}
+/** Test-only: the live per-turn admission count for a phase. */
+export function _boundedTurnCountForTest(phase) {
+    return turnCounts.get(phase) ?? 0;
+}

package/node_modules/pi-lens/dist/clients/cascade-budget.js

@@ -0,0 +1,196 @@
+/**
+ * Cascade neighbour-budget sizing (#1462).
+ *
+ * The flat neighbour cap (40) and the turn-end settle wait (5000 ms) were set in
+ * two different files with nothing relating them. Dogfood 2026-08-15 measured
+ * what that costs: n=50 cascades, median 30 ms, max 3.88 s at nbr=40 — and with
+ * a `reverse_deps_cache` refresh ahead of the graph build (2046 ms for
+ * `logger.ts`) the run overran the turn_end cap, so `cascade_settle_wait`
+ * returned `settled: 0` and the finding arrived a turn late.
+ *
+ * ## What a slow run actually costs
+ *
+ * It is NOT lost. `RuntimeCoordinator.settleCascadeRuns` re-parks a promise
+ * still in flight at the cap, `agent_settled` gives it a second and more
+ * generous drain (`cascade_carry_over_settle`, `quietWindowWaitMs`, 15 000 ms),
+ * and `beginTurn` deliberately keeps `_pendingCascadeRuns` so anything still
+ * running surfaces at a later turn_end — that is #1443, and pre-#450 these
+ * findings were always awaited. So the real trade is:
+ *
+ *   full neighbour set, one turn late   vs.   a narrowed set, on time,
+ *                                             with the remainder lost for good
+ *
+ * Narrowing is therefore only worth paying for when it genuinely converts a
+ * late run into an on-time one. That gives three zones, and the derivation
+ * below is exactly those three:
+ *
+ *   fits         the full walk still fits the on-time window — nothing to do
+ *   narrowed     the RESCUE BAND: the full walk no longer fits but a shorter
+ *                one does, so trading the tail for on-time delivery buys
+ *                something real
+ *   past-rescue  not even a floor-sized walk fits any more, so narrowing would
+ *                drop neighbours permanently AND still miss the window. Keep
+ *                the full budget and let the carry-over deliver it complete.
+ *                This is the cold-session case: a fresh graph build measures up
+ *                to ~19 s (see `runtime-coordinator.ts`'s carry-over note), and
+ *                a floor-sized stub there is strictly worse than pre-#1462.
+ *
+ * One more guard, for the same reason. If the on-time window could not fit a
+ * full walk even at zero prelude, there is no LATE run to rescue — every
+ * cascade would be permanently downsized because a *wait* was configured small.
+ * That is a budget change wearing a timeout's clothes, so the derivation stands
+ * down entirely (`no-rescue-window`) and the flat cap applies. This is what
+ * keeps `PI_LENS_CASCADE_SETTLE_WAIT_MS` from doubling as a neighbour-count
+ * knob: at the 5000/100/40 defaults the band is a prelude of 1.0–4.5 s, and
+ * shrinking the wait to 1000 ms disables narrowing rather than capping every
+ * cascade at ~10 neighbours.
+ */
+import { recordDegradationOnce } from "./degradation-ledger.js";
+import { toPositiveFinite } from "./env-utils.js";
+// The knobs only, never the scheduler — this module is arithmetic and has no
+// business depending on a task registry to read two numbers (#1462 review N4).
+// Note it buys nothing at load time: `runtime-config.js` below already reaches
+// `pidusage` via `lens-config.js`.
+import { isQuietWindowEnabled, quietWindowWaitMs, } from "./quiet-window-config.js";
+import { RUNTIME_CONFIG } from "./runtime-config.js";
+/**
+ * Bounded wait for the turn's deferred cascade computes (#450) to settle before
+ * they are merged at turn_end. A late compute is carried over, never dropped.
+ *
+ * `0` is a meaningful setting (never block turn_end), so this deliberately does
+ * NOT use `lazyEnvNumber` — that helper treats 0 as "unset" and would silently
+ * restore the 5000 ms default.
+ */
+export function cascadeSettleWaitMs() {
+    const raw = Number(process.env.PI_LENS_CASCADE_SETTLE_WAIT_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : 5000;
+}
+/** The budget floor, and the minimum any env override of the cap can produce. */
+const MIN_NEIGHBOUR_BUDGET = RUNTIME_CONFIG.pipeline.cascadeMaxFiles;
+/**
+ * The flat per-run cap: the most neighbours a cascade walks. Still the ceiling
+ * — the derivation below only ever narrows it, and only inside the rescue band.
+ */
+const DEFAULT_NEIGHBOUR_BUDGET = 40;
+export const CASCADE_NEIGHBOUR_BUDGET = Math.max(MIN_NEIGHBOUR_BUDGET, Number.parseInt(process.env.PI_LENS_CASCADE_NEIGHBOUR_BUDGET ?? "40", 10) ||
+    DEFAULT_NEIGHBOUR_BUDGET);
+/**
+ * True when `PI_LENS_CASCADE_NEIGHBOUR_BUDGET` moved the ceiling away from the
+ * default (#1462 review F-E). Raising it far enough can push
+ * `ceiling * perNeighbourMs` past the settle window, so EVERY cascade reads
+ * `no-rescue-window` — the whole derivation disarmed by a cap change nobody
+ * meant as a timeout change. Read once at load, same lifetime as the constant
+ * it describes.
+ */
+const NEIGHBOUR_BUDGET_OVERRIDDEN = process.env.PI_LENS_CASCADE_NEIGHBOUR_BUDGET !== undefined &&
+    CASCADE_NEIGHBOUR_BUDGET !== DEFAULT_NEIGHBOUR_BUDGET;
+/**
+ * Marginal wall-clock cost of one more neighbour in the walk, in ms. Calibrated
+ * on the 2026-08-15 dogfood tail: 3.88 s at nbr=40 and 3.71 s at nbr=38, both
+ * ~97 ms per neighbour. Touches fan out in parallel, so this is the observed
+ * marginal cost under LSP contention, not one touch's own latency.
+ *
+ * It is an ESTIMATE, and the derivation is sensitive to it: if the true cost is
+ * materially above this, a walk sized against it still overruns (the rescue
+ * fails and the tail was dropped for nothing). `scripts/bench-cascade-budget.mjs
+ * --true-cost-ms=<n>` measures that sensitivity directly. Rounded UP from the
+ * measurement so the estimate errs toward narrowing less.
+ */
+const DEFAULT_NEIGHBOUR_COST_MS = 100;
+/** Read per call — sized once per cascade run, never on a hot path. */
+function neighbourCostMs() {
+    return (toPositiveFinite(process.env.PI_LENS_CASCADE_NEIGHBOUR_COST_MS) ||
+        DEFAULT_NEIGHBOUR_COST_MS);
+}
+function neighbourFloor() {
+    return (toPositiveFinite(process.env.PI_LENS_CASCADE_NEIGHBOUR_FLOOR) ||
+        MIN_NEIGHBOUR_BUDGET);
+}
+/**
+ * Size one run's neighbour walk against the on-time window supplied by its
+ * caller.
+ *
+ * `elapsedMs` is arithmetic input, not an observation made by this function.
+ * The production caller measures it against the active turn_end settle window
+ * and passes that elapsed time here. When that boundary is unavailable, the
+ * caller passes zero to preserve the flat cap. Legacy callers may still pass
+ * deferred run age for compatibility.
+ *
+ * Every override exists so the derivation can be tested and benchmarked as a
+ * pure function; the function itself does not observe a deferred run's age.
+ */
+export function deriveCascadeNeighbourBudget(options) {
+    const ceiling = options.ceiling ?? CASCADE_NEIGHBOUR_BUDGET;
+    // The floor can never exceed the ceiling — a floor above the cap would make
+    // the derived budget LARGER than the flat one it exists to bound.
+    const floor = Math.min(ceiling, options.floor ?? neighbourFloor());
+    const onTimeMs = options.settleWaitMs ?? cascadeSettleWaitMs();
+    const perNeighbourMs = options.perNeighbourMs ?? neighbourCostMs();
+    const elapsedMs = toPositiveFinite(options.elapsedMs);
+    const remainingMs = onTimeMs - elapsedMs;
+    const deliveryWindowMs = onTimeMs +
+        (options.quietDrainMs ??
+            (isQuietWindowEnabled() ? quietWindowWaitMs() : 0));
+    const full = { budget: ceiling, ceiling, remainingMs, deliveryWindowMs };
+    // No on-time window at all, or one too small to ever fit a full walk. There
+    // is no late run to rescue here, only every run to shrink — stand down.
+    //
+    // Boundary, acknowledged rather than special-cased: at exactly
+    // `onTimeMs === ceiling * perNeighbourMs` this does not fire and the `fits`
+    // zone has zero width, so ANY prelude narrows. Not slightly, either — at
+    // 4000/100/40 a 2 s prelude gives 20 and a 3.5 s prelude gives the floor.
+    // Left alone because the narrowing is honest at that setting: with the
+    // window sized to exactly one full walk, a run that has spent any of it
+    // really would miss, so every one of those cuts is a genuine rescue rather
+    // than the `no-rescue-window` case this guard exists to catch. What it does
+    // cost is headroom — see the divisor bands in the bench's `--sweep` text.
+    if (onTimeMs <= 0 || onTimeMs < ceiling * perNeighbourMs) {
+        // #1462 review F-E: name the override, once per session, when it is the
+        // REASON the derivation stood down — not when a caller under test asked
+        // for a specific ceiling, and not on every one of the cascades this
+        // disarms for the rest of the session.
+        if (options.ceiling === undefined && NEIGHBOUR_BUDGET_OVERRIDDEN) {
+            recordDegradationOnce({
+                kind: "cascade-budget-override-disarmed",
+                subject: "cascade-neighbour-budget",
+                reason: `PI_LENS_CASCADE_NEIGHBOUR_BUDGET=${CASCADE_NEIGHBOUR_BUDGET} needs ` +
+                    `${ceiling * perNeighbourMs}ms to walk the full cap, which exceeds ` +
+                    `the ${onTimeMs}ms settle window — the rescue band is disarmed and ` +
+                    `every cascade keeps the flat (overridden) cap`,
+            });
+        }
+        return { ...full, zone: "no-rescue-window" };
+    }
+    // The full walk still fits. Nothing to buy.
+    if (remainingMs >= ceiling * perNeighbourMs) {
+        return { ...full, zone: "fits" };
+    }
+    // Past rescue: not even a floor-sized walk fits, so narrowing would drop the
+    // tail permanently and still miss the window. The carry-over delivers the
+    // whole set one turn later instead.
+    //
+    // #1462 review F-B, kept rather than shrunk: one dogfood log measured this
+    // zone at 0/1090 cascades, and asked whether a 3-zone module earns its keep
+    // at that frequency. It was measured against the WRITE-relative clock this
+    // same round fixed, which charges elapsed time no cascade actually spent
+    // waiting — so it under-counts how often a genuinely slow compute (a cold
+    // graph build, ~19 s) overlaps an already-running settle window, which is
+    // exactly what this zone exists to catch (F3, a real regression the first
+    // review round found: a floor-sized stub on that cold-start case is
+    // strictly worse than pre-#1462). Reachability under the corrected clock
+    // has not been re-measured; shrinking on a stale sample would trade a
+    // cheap, already-tested guard against a proven regression for a paper
+    // simplification. Revisit if a post-fix dogfood window confirms it still
+    // never fires.
+    if (remainingMs < floor * perNeighbourMs) {
+        return { ...full, zone: "past-rescue" };
+    }
+    // The rescue band: a shorter walk lands on time.
+    return {
+        budget: Math.min(ceiling, Math.max(floor, Math.floor(remainingMs / perNeighbourMs))),
+        ceiling,
+        remainingMs,
+        deliveryWindowMs,
+        zone: "narrowed",
+    };
+}

package/node_modules/pi-lens/dist/clients/cascade-format.js

@@ -3,8 +3,18 @@ import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
     const withErrors = neighbors.filter((n) => n.diagnostics.length > 0);
     const inconclusive = neighbors.filter((n) => n.inconclusive === true && n.diagnostics.length === 0);
-    if (withErrors.length === 0 && inconclusive.length === 0)
+    // #1459: a neighbour whose scanner never looked at it is not a clean leaf. It
+    // is also not `inconclusive` — the language server answered — so it gets its
+    // own honest line instead of being folded into either bucket. Only the
+    // zero-diagnostic case needs saying: a neighbour with findings already renders.
+    const uncovered = neighbors.filter((n) => n.diagnostics.length === 0 &&
+        n.inconclusive !== true &&
+        (n.unconfirmedServerIds?.length ?? 0) > 0);
+    if (withErrors.length === 0 &&
+        inconclusive.length === 0 &&
+        uncovered.length === 0) {
         return "";
+    }
     const noun = options.noun ?? "neighbor";
     let out = withErrors.length > 0
         ? `📐 Cascade errors in ${withErrors.length} ${noun} file(s) — fix before finishing turn:`
@@ -29,6 +39,15 @@ export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
             out += `\n  ${toRunnerDisplayPath(cwd, neighbor.filePath)}`;
         }
     }
+    if (uncovered.length > 0) {
+        if (out)
+            out += "\n";
+        out += `⚠️ Cascade scanners did not cover ${uncovered.length} ${noun} file(s) — no findings does NOT mean clean here:`;
+        for (const neighbor of uncovered) {
+            const servers = (neighbor.unconfirmedServerIds ?? []).join(", ");
+            out += `\n  ${toRunnerDisplayPath(cwd, neighbor.filePath)} (not scanned by ${servers})`;
+        }
+    }
     return out;
 }
 /**

package/node_modules/pi-lens/dist/clients/cascade-types.js

@@ -1 +1,9 @@
-export {};
+/**
+ * How long a cascade neighbour's diagnostics stay usable (#1816).
+ *
+ * One constant for two consumers that each declared their own `240_000`:
+ * `clients/lsp/index.ts` (the neighbour-diagnostics cache) and
+ * `clients/dispatch/integration.ts` (the cascade turn scope). They must move
+ * together — a split pair reads as two independent policies and drifts.
+ */
+export const CASCADE_DIAGNOSTICS_TTL_MS = 240_000;