@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

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/bus-events-logger.js

@@ -1,13 +1,20 @@
 /**
  * Persistent NDJSON trace of `pi.events` bus publish attempts
  * (`pilens:files:touched` #482 / `pilens:diagnostics` #502 /
- * `pilens:format:queued` + `pilens:format:start` #673).
+ * `pilens:diagnostic:disposition` / `pilens:format:queued` +
+ * `pilens:format:start` + `pilens:autofix:start` #673/#684 /
+ * `pi-lens/analysis-complete` + `pi-lens/findings` + `pi-lens/turn-findings`
+ * #1415) — nine event names across five producers.
  *
- * All four producers (clients/bus-publish.ts, clients/diagnostics-publish.ts,
- * clients/format-events-publish.ts) are fire-and-forget: on failure or on a
- * structural no-op (never wired, kill switch off) they only invoke an
- * optional `dbg` callback, which varies by host and is a documented no-op in
- * the MCP host (clients/mcp/session.ts's `dbg: noop`). That leaves
+ * All five producers (clients/bus-publish.ts, clients/diagnostics-publish.ts,
+ * clients/disposition-publish.ts, clients/format-events-publish.ts,
+ * clients/lens-events.ts) are fire-and-forget: on failure or on a structural
+ * no-op (never wired, kill switch off) the four #482/#502/#673/#684
+ * producers only invoke an optional `dbg` callback, which varies by host and
+ * is a documented no-op in the MCP host (clients/mcp/session.ts's
+ * `dbg: noop`); `lens-events.ts` (#1415) has no `dbg` param at all — its
+ * events are purely observational inter-extension telemetry, so this NDJSON
+ * trace is its ONLY failure-visible surface. Either way, that leaves
  * bus-publish outcomes invisible in exactly the context where they matter
  * most — same failure shape as the #544 MCP session_start incident this repo
  * already fixed once.
@@ -26,6 +33,9 @@
  * spam one identical line per write batch for an entire session with zero
  * new information after the first. Both are gated log-once-per-process, the
  * same `hasLoggedFailure` shape the producers already use for emit_failed.
+ * `skipped_stale_session` is an info-level per-occurrence outcome: the emit
+ * seam intentionally declined a target whose associated ctx was confirmed
+ * stale, so it is neither a bus failure nor input for the smells rollup.
  * The empty-batch branch (`paths.length === 0` / `files.length === 0`) is
  * NOT logged at all: every call site already guards against invoking these
  * functions with nothing to report (see clients/pipeline.ts,
@@ -37,17 +47,63 @@ import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
+import { logLatency } from "./latency-logger.js";
 const BUS_EVENTS_LOG_FILE = path.join(getGlobalPiLensDir(), "bus-events.log");
 const writer = createNdjsonLogger({
     filePath: BUS_EVENTS_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,
 });
+const eventRollupCounts = new Map();
+function bumpRollupCount(event, outcome) {
+    const existing = eventRollupCounts.get(event) ?? {
+        emitted: 0,
+        skipped_stale_session: 0,
+        emit_failed: 0,
+    };
+    existing[outcome] += 1;
+    eventRollupCounts.set(event, existing);
+}
 export function logBusEvent(entry) {
+    if (entry.outcome === "emitted" ||
+        entry.outcome === "skipped_stale_session" ||
+        entry.outcome === "emit_failed") {
+        bumpRollupCount(entry.event, entry.outcome);
+    }
     if (isTestMode()) {
         return;
     }
     writer.log({ ts: new Date().toISOString(), ...entry });
 }
+/** Snapshot the current session's rollup, keyed by event name. Non-mutating —
+ *  pair with {@link resetBusEventRollupCounts} at session end. */
+export function getBusEventRollupCounts() {
+    return Object.fromEntries(eventRollupCounts);
+}
+/** Clear the rollup — call once the session-end snapshot has been logged
+ *  (or from tests) so a new session starts from zero. */
+export function resetBusEventRollupCounts() {
+    eventRollupCounts.clear();
+}
+/**
+ * Log one `session_end_bus_rollup` latency row per event NAME that had any
+ * activity this session, then clear the rollup. Called from index.ts's
+ * `session_shutdown` handler (the session-end hook this repo's other
+ * teardown work — LSP fleet shutdown, cache-prefix eviction — already runs
+ * from). A no-op (logs nothing) when nothing was ever published, matching
+ * `formatSmellsSessionStartLine`'s "no noise on an ordinary session" shape.
+ */
+export function emitBusEventRollupAtSessionEnd(cwd) {
+    for (const [event, counts] of eventRollupCounts) {
+        logLatency({
+            type: "phase",
+            phase: "session_end_bus_rollup",
+            filePath: cwd,
+            durationMs: 0,
+            metadata: { event, ...counts },
+        });
+    }
+    resetBusEventRollupCounts();
+}
 export function getBusEventsLogPath() {
     return BUS_EVENTS_LOG_FILE;
 }

package/node_modules/pi-lens/dist/clients/bus-publish.js

@@ -20,7 +20,7 @@
 import { logBusEvent } from "./bus-events-logger.js";
 import { normalizeFilePath } from "./path-utils.js";
 import { appendRecentTouches } from "./recent-touches.js";
-import { createLiveBusEmitter, recordStaleBusFailure, } from "./live-bus-emitter.js";
+import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const BUS_FILES_TOUCHED_EVENT = "pilens:files:touched";
 export const BUS_FILES_TOUCHED_VERSION = 1;
 const liveEmitter = createLiveBusEmitter();
@@ -106,8 +106,14 @@ export function publishFilesTouched(args) {
     }).catch((err) => {
         args.dbg?.(`bus-publish: recent-touches append failed: ${err}`);
     });
-    const busEmit = liveEmitter.get();
-    if (!busEmit) {
+    const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
+        event: BUS_FILES_TOUCHED_EVENT,
+        cwd: normalizeFilePath(args.cwd),
+        reason: args.reason,
+    }));
+    if (resolution.outcome === "stale-session")
+        return;
+    if (resolution.outcome === "unwired") {
         if (!hasLoggedUnwired) {
             hasLoggedUnwired = true;
             logBusEvent({
@@ -119,6 +125,7 @@ export function publishFilesTouched(args) {
         }
         return;
     }
+    const busEmit = resolution.emit;
     try {
         const payload = {
             v: BUS_FILES_TOUCHED_VERSION,
@@ -150,6 +157,7 @@ export function publishFilesTouched(args) {
             cwd: normalizeFilePath(args.cwd),
             reason: args.reason,
             error: String(err),
+            ctxSource: resolution.ctxSource,
         });
         if (!hasLoggedFailure) {
             hasLoggedFailure = true;

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

@@ -1,10 +1,24 @@
+import { convertLspDiagnostics } from "./dispatch/utils/lsp-diagnostics.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
     const withErrors = neighbors.filter((n) => n.diagnostics.length > 0);
-    if (withErrors.length === 0)
+    const inconclusive = neighbors.filter((n) => n.inconclusive === true && n.diagnostics.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 = `📐 Cascade errors in ${withErrors.length} ${noun} file(s) — fix before finishing turn:`;
+    let out = withErrors.length > 0
+        ? `📐 Cascade errors in ${withErrors.length} ${noun} file(s) — fix before finishing turn:`
+        : "";
     for (const neighbor of withErrors) {
         const display = toRunnerDisplayPath(cwd, neighbor.filePath);
         const reason = options.includeReason ? ` reason="${neighbor.reason}"` : "";
@@ -17,5 +31,65 @@ export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
         }
         out += "\n</diagnostics>";
     }
+    if (inconclusive.length > 0) {
+        if (out)
+            out += "\n";
+        out += `⚠️ Cascade diagnostics inconclusive for ${inconclusive.length} ${noun} file(s) — no clean result was confirmed:`;
+        for (const neighbor of inconclusive) {
+            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;
 }
+/**
+ * Build the turn-end `CascadeRun` for a neighbour whose diagnostics landed only
+ * AFTER its cascade touch skipped the in-lane wait (#1023's `resolved-found`
+ * quiet-window outcome; #1444 made native TS7 take that same path). Returns
+ * `undefined` when there is nothing agent-facing to say — no ERROR-severity
+ * diagnostics, or nothing the formatter renders.
+ *
+ * Lives here rather than inline in the quiet-window callback so the delivery
+ * path (reconcile → run → turn_end) is testable end to end; index.ts only wires
+ * it to `runtime.appendCascadeRun`.
+ */
+export function buildResolvedFoundCascadeRun(cwd, neighbor) {
+    const { filePath } = neighbor;
+    const diagnostics = convertLspDiagnostics(neighbor.diagnostics.filter((d) => d.severity === 1), filePath, { tool: "lsp" });
+    if (diagnostics.length === 0)
+        return undefined;
+    const neighbors = [
+        { filePath, reason: "references", diagnostics, lspTouched: true },
+    ];
+    const formatted = formatCascadeNeighborDiagnostics(cwd, neighbors, {
+        noun: "cold neighbor",
+    });
+    if (!formatted)
+        return undefined;
+    return {
+        filePath,
+        result: {
+            filePath,
+            impact: {
+                filePath,
+                changedSymbols: [],
+                directImporters: [],
+                directCallers: [],
+                neighborFiles: [filePath],
+                riskFlags: [],
+            },
+            neighbors,
+            formatted,
+        },
+        neighborCount: 1,
+        diagnosticCount: diagnostics.length,
+    };
+}

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;