@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

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

@@ -1,5 +1,6 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
-import { appendActionableWarningsHistory, buildActionableWarningsReport, formatActionableWarningsAdvisory, writeActionableWarningsReport, } from "./actionable-warnings.js";
+import { buildActionableWarningsReport, formatActionableWarningsAdvisory, publishActionableWarningsReport, writeDeferredActionableWarningsReport, } from "./actionable-warnings.js";
 import { logActionableWarningsEvent } from "./actionable-warnings-logger.js";
 import { appendCodeQualityWarningsHistory, buildCodeQualityWarningsReport, formatCodeQualityWarningsAdvisory, writeCodeQualityWarningsReport, } from "./code-quality-warnings.js";
 import { clearGitGuardTestFailure, mergeGitGuardTestFailure, writeGitGuardRecord, } from "./git-guard.js";
@@ -29,6 +30,7 @@ import { emitLensTurnFindings } from "./lens-events.js";
 import { RUNTIME_CONFIG } from "./runtime-config.js";
 import { isSubagentSession } from "./subagent-mode.js";
 import { formatRunDurationMs } from "./run-duration.js";
+import { isExcludedTestTarget, isRunnerErrorResult, RUNNERS, } from "./test-runner-client.js";
 import { MAX_ADVISORY_AFFECTED_FILES, gateFindingsByPathFreshness, snapshotAdvisoryProvenance, } from "./advisory-provenance.js";
 import { DEPENDENCY_DRIFT_MAX_DELIVERIES, sweepInlineBlockerFreshness, } from "./blocker-freshness.js";
 import { sweepInlineBlockerPastEof } from "./blocker-past-eof.js";
@@ -40,11 +42,239 @@ import { drainPendingRunnerFindings, dropStaleRunnerFindings, pendingRunnerFindi
 // #1631 review V2: moved to its own leaf module so a low-level store
 // (widget-state.ts) can use the marker without importing this orchestrator —
 // see clients/stale-marker.ts's doc comment.
-import { incrementDegradationCount } from "./degradation-ledger.js";
+import { incrementDegradationCount, recordDegradationOnce, } from "./degradation-ledger.js";
+import { mapWithConcurrency } from "./map-with-concurrency.js";
+import { getAmbientAbortSignal } from "./safe-spawn.js";
+import { emitBounded } from "./bounded-telemetry.js";
 import { degradeDemotedFindingBody, formatDeliveryCapNote, formatRetirementNote, } from "./demoted-finding-render.js";
 import { STALE_LINE_MARKER } from "./stale-marker.js";
 import { getActiveSessionId } from "./session-lifecycle.js";
-import { getWidgetBlockingFilesForSweep, markWidgetFileBlockersStale, recordRunner, } from "./widget-state.js";
+import { drainRenderedDependencyDriftFilePaths, getWidgetBlockingFilesForSweep, incrementWidgetDependencyDriftDelivery, markWidgetFileBlockersStale, recordRunner, retireWidgetDependencyDriftBlockers, } from "./widget-state.js";
+/** Maximum detailed notify-stall coverage-gap rows emitted in one turn. */
+const LATE_AUX_COVERAGE_GAP_DETAIL_CAP_PER_TURN = 20;
+/**
+ * #2504 — bounds on the per-turn test-runner fan-out.
+ *
+ * The reported turn fired 59 `vitest.cmd` spawns at once from a bare
+ * `Promise.allSettled(targets.map(...))`. Each spawn carries its OWN 60 s
+ * timeout (`test-runner-client.ts`), which bounds one target and says nothing
+ * about the batch: 59 of them starved the event loop for the whole turn
+ * (`cpuCoverageRatio 0.56`, 20 orphan-backstop escalations inside the storm).
+ *
+ * Three separate bounds, because they fail differently:
+ *  - CONCURRENCY caps how much CPU the batch can hold at one instant;
+ *  - TARGET COUNT caps how much work one turn may enqueue at all;
+ *  - the WALL BUDGET caps how long the batch may keep spawning, and is raced
+ *    against the ambient abort signal so a cancelled turn stops dispatching
+ *    immediately rather than at the next natural boundary.
+ *
+ * #2522: the batch budget shipped at 90 s in #2509 — well over the turn
+ * itself, so a slow/hung batch could still hold up the agent for most of a
+ * turn before the bound even engaged. Reconciled down to 20 s (one constant,
+ * not a second budget alongside it): well under the turn, and still an order
+ * of magnitude below the PER-TARGET 60 s cap in `test-runner-client.ts`, so
+ * the batch bound is the one that actually fires first for a stuck target.
+ *
+ * #2522 review round 2: lowering the budget on its own made things WORSE,
+ * because the "deferred to the next turn" this comment used to claim did not
+ * exist. `runTestTargetsBounded` returned a skipped COUNT and threw the
+ * identity of the unrun targets away, so a target slower than the budget
+ * produced no result, no cache record and no output — every turn, forever —
+ * while a PARTIAL batch fell through to the clean branch and was reported as
+ * "all tests passed". The deferral is now a real mechanism:
+ *
+ *  - the batch owns an `AbortController` that is handed to each target's spawn
+ *    (`TestRunRequest.signal` → `safeSpawnAsync`), so reaching the bound KILLS
+ *    what is in flight instead of leaving it to burn its own 60 s timeout and
+ *    then mutate a results array the caller has already consumed;
+ *  - the killed set plus the never-dispatched set is returned BY IDENTITY as
+ *    `deferred`, persisted on the `test-runner-findings` record as
+ *    `deferredTargets`, and dispatched FIRST on the next turn — ahead of
+ *    failed-first/related/self — under the same `TEST_RUNNER_MAX_TARGETS` cap;
+ *  - a batch whose `deferred` set is non-empty can never take the clean
+ *    branch, so an unfinished run is never reported as a green one and never
+ *    relaxes the `--lens-guard` commit gate.
+ */
+export const TEST_RUNNER_BATCH_CONCURRENCY = 4;
+export const TEST_RUNNER_MAX_TARGETS = 12;
+export const TEST_RUNNER_BATCH_BUDGET_MS = 20_000;
+/**
+ * How many consecutive turn-end batches a target may be cut out of before it
+ * is retired from turn-end selection altogether.
+ *
+ * Without this the deferral is a LIVELOCK, and not hypothetically: this
+ * repo's own `tests/index-integration.test.ts` — which turn-end resolves
+ * through the `related` strategy whenever `clients/runtime-turn.ts` is
+ * edited — takes 26.4 s, MORE than the entire 20 s batch budget on its own.
+ * Deferring it puts it FIRST in the next batch, where it is cut again at
+ * 20 s, and again, every turn, forever. A target that cannot fit the budget
+ * is not a scheduling problem retrying can solve; it is reported once per
+ * occurrence and dropped, so the turn stops paying 20 s for it.
+ */
+export const TEST_RUNNER_MAX_DEFERRALS = 2;
+/**
+ * Ceiling on how many entries either persisted target list may carry.
+ *
+ * #2522 review round 4, I1: a write may no longer destroy another session's
+ * entries, so nothing in the write path prunes them any more — each session
+ * that ever cut or retired a target in this project leaves its rows behind, on
+ * a record read at every single turn_end. The bound is applied at the one
+ * writer, on the whole list, and sheds FOREIGN rows first (the writer orders
+ * this session's entries last), so it can never evict the entries this turn
+ * depends on. Generous on purpose: it is a backstop against unbounded growth,
+ * not a scheduling policy.
+ */
+export const TEST_RUNNER_MAX_PERSISTED_TARGETS = 64;
+/**
+ * Union two deferral sets by target identity, keeping the HIGHER attempt count
+ * (#2522 review round 3, F3). Two overlapping batches can both be cut on the
+ * same target; taking the lower count would let a target trade an attempt for
+ * every overlap and never converge on `TEST_RUNNER_MAX_DEFERRALS`.
+ *
+ * Identity is (session, path), not path alone (#2522 review round 4, I1): two
+ * sessions can each owe a run of the same file, and collapsing those into one
+ * row makes the surviving row's `sessionId` decide whose deferral is honoured
+ * and whose is silently dropped. The path half is keyed through
+ * `normalizeMapKey` so `/`- and `\`-separated spellings are one entry
+ * (AGENTS.md cross-form-path screen).
+ */
+function deferralEntryKey(entry) {
+    return `${entry.sessionId ?? ""}\u0000${normalizeMapKey(path.resolve(entry.testFile))}`;
+}
+function mergeDeferredTargets(existing, incoming) {
+    const byKey = new Map();
+    for (const entry of [...existing, ...incoming]) {
+        const key = deferralEntryKey(entry);
+        const prior = byKey.get(key);
+        if (prior && (prior.attempts ?? 0) >= (entry.attempts ?? 0))
+            continue;
+        byKey.set(key, entry);
+    }
+    return [...byKey.values()];
+}
+/**
+ * Run `run` over `targets` with a concurrency cap, a batch-wide wall budget
+ * and an abort-signal race. Reuses `mapWithConcurrency` (the repo's existing
+ * worker-pool shape) rather than hand-rolling a second pool.
+ *
+ * Both bounds are enforced twice on purpose: cooperatively, before each
+ * dispatch, so no NEW work starts past the bound; and as a real race against
+ * the pool, so an in-flight target cannot hold the batch past its budget.
+ * Whatever has settled by then is returned — a partial batch of real results
+ * is strictly better than none, and the caller reports the shortfall.
+ */
+export async function runTestTargetsBounded(args) {
+    const results = [];
+    if (args.targets.length === 0)
+        return { results, deferred: [] };
+    let stopReason;
+    // One controller for the whole batch. Aborting it tree-kills every child the
+    // runner has in flight (`safeSpawnAsync` honours the signal it is handed),
+    // which is what turns "the bound fired" into "the work actually stopped".
+    const batchAbort = new AbortController();
+    // Latched at the moment this call returns. Nothing may push into `results`
+    // after that: the caller has already consumed the array, and a late push
+    // would silently change a batch it has finished reasoning about.
+    let closed = false;
+    /**
+     * #2522 review round 4, I4: "was this target CUT, or did it FINISH?" is a
+     * semantic question, and this set is the answer — stamped by the `.then`
+     * attached to `run`'s promise AT DISPATCH, which is that promise's FIRST
+     * continuation. Nothing but a microtask can run between the promise settling
+     * and this stamp, and every path that closes the batch (`setTimeout`, the
+     * ambient signal's `abort` event, the pool settling after every mapper has
+     * returned) reaches `finish()` from a macrotask or later. So `closed` read
+     * here is exactly "the batch was already cut when this value existed".
+     *
+     * Round 3 read the same flag from the mapper's own `await` continuation,
+     * which is several continuations downstream of the settle — a macrotask CAN
+     * interleave there — and papered over the resulting misclassification with a
+     * `setImmediate` hop plus a `latchedOut` parking array. Both are gone: the
+     * hop made the answer depend on queue ordering, which is the thing that kept
+     * producing findings (a spawn aborted BEFORE it started resolves
+     * synchronously, so the hop folded it back in as a completed run — round 4
+     * P3c).
+     */
+    const settledBeforeClose = new Set();
+    const budgetMs = Math.max(0, args.budgetMs);
+    const deadline = Date.now() + budgetMs;
+    const shouldStop = () => {
+        if (stopReason !== undefined)
+            return true;
+        if (args.signal?.aborted) {
+            stopReason = "abort";
+            return true;
+        }
+        if (Date.now() >= deadline) {
+            stopReason = "budget";
+            return true;
+        }
+        return false;
+    };
+    const pool = mapWithConcurrency(args.targets.map((target, index) => ({ target, index })), Math.max(1, args.concurrency), async ({ target, index }) => {
+        if (shouldStop())
+            return;
+        const running = args.run(target, batchAbort.signal);
+        // Attached HERE, at dispatch, so it is the promise's first
+        // continuation — see `settledBeforeClose`. A value that only exists
+        // because the batch was cut (a killed spawn's runner error, or
+        // `safeSpawnAsync`'s synchronous "Spawn aborted before start") settles
+        // strictly after the close and is therefore never recorded, so the
+        // caller defers that target instead of reading it as a completed run.
+        const stamp = running.then((value) => {
+            if (closed)
+                return;
+            settledBeforeClose.add(index);
+            results.push({ status: "fulfilled", value });
+        }, (reason) => {
+            if (closed)
+                return;
+            settledBeforeClose.add(index);
+            results.push({ status: "rejected", reason });
+        });
+        // The stamp swallows both settlements, so this only keeps the pool's
+        // concurrency slot held for as long as the work actually runs.
+        await stamp;
+    });
+    // The pool's mapper swallows every throw from an async `run`; a `run` that throws
+    // SYNCHRONOUSLY still rejects the pool and closes the whole batch (everything defers,
+    // nothing publishes clean). Production runners are async, so this is fail-safe, not reachable.
+    void pool.catch(() => { });
+    await new Promise((resolve) => {
+        let settled = false;
+        const finish = (reason) => {
+            if (settled)
+                return;
+            settled = true;
+            if (reason !== undefined)
+                stopReason ??= reason;
+            // Latch BEFORE resolving, so no continuation scheduled by the kill
+            // below can slip a result in behind the caller's back.
+            closed = true;
+            // Kill whatever is still in flight. Without this the pool ran on past
+            // the bound: a stuck vitest spawn kept a core busy to its own 60s
+            // timeout, long after the turn had moved on.
+            batchAbort.abort();
+            clearTimeout(timer);
+            args.signal?.removeEventListener("abort", onAbort);
+            resolve();
+        };
+        const onAbort = () => finish("abort");
+        const timer = setTimeout(() => finish("budget"), budgetMs);
+        // A pending batch timer must never hold the process open.
+        timer.unref?.();
+        if (args.signal?.aborted)
+            finish("abort");
+        else
+            args.signal?.addEventListener("abort", onAbort, { once: true });
+        void pool.then(() => finish(), () => finish());
+    });
+    return {
+        results,
+        deferred: args.targets.filter((_, index) => !settledBeforeClose.has(index)),
+        stopReason,
+    };
+}
 /**
  * #1617: turn_end reads gitleaks/govulncheck/trivy straight from their
  * session-scan caches and formats them into advisory/blocker text — a
@@ -239,7 +469,7 @@ function capTurnEndMessage(content) {
     return out;
 }
 export async function handleTurnEnd(deps) {
-    const { ctxCwd, getFlag, dbg, runtime, cacheManager, knipClient, deadCodeClients, depChecker, testRunnerClient, owner, resetLSPService, resetFormatService, } = deps;
+    const { ctxCwd, getFlag, dbg, runtime, cacheManager, knipClient, deadCodeClients, depChecker, testRunnerClient, sessionId, owner, resetLSPService, resetFormatService, } = deps;
     // #449 slice 1: piggyback the instance-registry heartbeat on this existing
     // per-turn touchpoint rather than adding a new timer/interval. Cheap (reads
     // process.memoryUsage().rss, one read-modify-write of instances.json) and
@@ -261,13 +491,27 @@ export async function handleTurnEnd(deps) {
     let turnState = cacheManager.readTurnState(cwd);
     // A live foreign writer owns this worklist. Do not clear or consume another
     // pi/MCP session's files; a dead/aged owner is safely evicted instead.
-    const currentOwner = owner ?? {
-        kind: "pi",
-        id: runtime.telemetrySessionId,
-        pid: process.pid,
-        lastSeen: new Date().toISOString(),
+    // #2504: `sessionStartedAt` dates the persisted worklist against THIS
+    // session. Without it an ownerless turn-state.json — the resting shape
+    // before #2504 — read back as "owned" no matter how old it was.
+    const currentOwner = {
+        ...(owner ?? {
+            kind: "pi",
+            id: runtime.telemetrySessionId,
+            pid: process.pid,
+            lastSeen: new Date().toISOString(),
+        }),
+        sessionStartedAt: owner?.sessionStartedAt ?? runtime.sessionStartedAt,
     };
     const access = cacheManager.getTurnStateAccess(cwd, currentOwner);
+    // Captured BEFORE the eviction below rewrites the file: the owner the gate
+    // actually judged. This pair is what would have settled #2504 from the
+    // debug log alone.
+    const gateOwnerLabel = turnState.owner
+        ? `${turnState.owner.kind}:${turnState.owner.id}`
+        : turnState.sessionId
+            ? `legacy:${turnState.sessionId}`
+            : "none";
     const sameProcessPiSessionHandoff = access === "foreign-live" &&
         currentOwner.kind === "pi" &&
         turnState.owner?.kind === "pi" &&
@@ -284,6 +528,49 @@ export async function handleTurnEnd(deps) {
         turnState = cacheManager.readTurnState(cwd);
     }
     const files = Object.keys(turnState.files);
+    /**
+     * #2275: widget-footer sibling of #1950's inline-blocker cap, for the
+     * widget store's OWN dependency-drift demotion
+     * (`markWidgetFileBlockersStale`, driven by the freshness sweep further
+     * down this function) — a completely separate store from
+     * `RuntimeCoordinator`'s inline-blocker map, so it needed its own
+     * delivery count (`WidgetDiagnostic.staleDeliveryCount`) rather than
+     * inheriting one.
+     *
+     * Review F1: the population is what the footer RENDERED since the last
+     * turn end, drained here — not every file that merely holds a demoted
+     * row. The footer draws one record per pass (`withBlocking[0]`, its top
+     * five entries) and may not be drawn at all, so a per-turn walk of the
+     * whole store charged deliveries the agent never received and retired a
+     * delivery early. This is the widget-surface analogue of the inline
+     * loop's own `pendingDependencyDriftDeliveries` deferral below: both
+     * commit a delivery only once the surface has actually served it. Every
+     * `deliveryCount` reported to the ledger is therefore a count of RENDERS.
+     *
+     * Fix-round 3 (#2275 review F1): this drain/charge MUST run before the
+     * `files.length === 0` early return below — a read-only turn (no
+     * modified files) still repaints the footer and can draw a demoted row,
+     * so a cap that only charged deliveries below the early return silently
+     * starved on quiet turns: the footer re-rendered the same demoted row
+     * every turn while the delivery count never advanced. The drain is a
+     * Set.take() plus one map lookup per drained file — cheap enough to run
+     * unconditionally on every turn end.
+     */
+    let widgetDemotedFindingsRetired = 0;
+    for (const wPath of drainRenderedDependencyDriftFilePaths()) {
+        const deliveryCount = incrementWidgetDependencyDriftDelivery(wPath);
+        if (deliveryCount >= DEPENDENCY_DRIFT_MAX_DELIVERIES) {
+            const capRetired = retireWidgetDependencyDriftBlockers(wPath);
+            if (capRetired) {
+                widgetDemotedFindingsRetired += 1;
+                incrementDegradationCount({
+                    kind: "demoted-finding-retired",
+                    subject: `widget-blocker:${toRunnerDisplayPath(cwd, wPath)}`,
+                    reason: `capped after ${deliveryCount} deliveries with no re-run; hidden from the pi-lens footer, still listed by lens_diagnostics mode=all — re-run can still confirm`,
+                });
+            }
+        }
+    }
     // R1 (#1443 follow-up): a read-only turn (no files touched) must not take
     // the fast idle-reset path while a carried cascade run — or one still
     // settling — is waiting for its delivery opportunity. Falling through to
@@ -347,7 +634,7 @@ export async function handleTurnEnd(deps) {
         cancelLSPIdleReset();
         dbg("turn_end: cancelled pending LSP idle reset (active editing)");
     }
-    dbg(`turn_end: ${files.length} file(s) modified, cycles: ${turnState.turnCycles}/${turnState.maxCycles}`);
+    dbg(`turn_end: ${files.length} file(s) modified, cycles: ${turnState.turnCycles}/${turnState.maxCycles}, access: ${access}, owner: ${gateOwnerLabel}`);
     if (cacheManager.isMaxCyclesExceeded(cwd)) {
         dbg("turn_end: max cycles exceeded, clearing state and forcing through");
         cacheManager.clearTurnState(cwd, currentOwner);
@@ -1457,10 +1744,12 @@ export async function handleTurnEnd(deps) {
         metadata: madgeStats ?? { skipped: true },
     });
     // --- Test runner: fire once per turn after all edits are done ---
-    // Runs for each unique test target across modified files; results appear
-    // in the next turn's context injection alongside jscpd/madge findings.
+    // Runs for each unique test target across modified files; results remain in
+    // the pull-diagnostics cache and are delivered after the agent settles.
     if (!getFlag("no-tests") && files.length > 0) {
         const seen = new Set();
+        // `strategy` is widened by one value the resolver itself cannot produce:
+        // a target carried over from the previous turn's cut batch (#2522 R2 F1).
         const targets = [];
         // #628: also target the test companions of this turn's cascade neighbors
         // (files that import an edited file) — a neighbor's own tests can break
@@ -1491,10 +1780,266 @@ export async function handleTurnEnd(deps) {
                 candidates.push({ display: neighbor.filePath, abs, isNeighbor: true });
             }
         }
+        // #2522 review round 2, F1: the previous turn's unfinished targets go
+        // FIRST — ahead of failed-first/related/self — under the same
+        // TEST_RUNNER_MAX_TARGETS cap, so a batch that keeps getting cut makes
+        // progress instead of re-running whatever this turn happened to touch
+        // and dropping the remainder again. The list is consumed here (written
+        // back empty below) so a target can never be carried forever.
+        const priorTestCache = cacheManager.readCache("test-runner-findings", cwd)?.data;
+        const carriedDeferred = priorTestCache?.deferredTargets ?? [];
+        // #2522 review round 3, F5: a deferral list belongs to the session that
+        // cut it. `runtime.telemetrySessionId` is the same identity the batch
+        // stamps its own entries with below (`firedSessionId`), so this is a
+        // single comparison against one source of truth.
+        const turnSessionId = sessionId ?? runtime.telemetrySessionId;
+        const isThisSession = (entry) => entry.sessionId === turnSessionId;
+        const entryPathKey = (entry) => normalizeMapKey(path.resolve(cwd, entry.testFile));
+        /**
+         * #2522 review round 3, F1: the retirement, carried forward.
+         *
+         * Round 2 announced the retirement and dropped it on the floor, so the
+         * candidate loop below re-resolved the very same file through
+         * `related`/`self` in the SAME turn and ran it anyway with a fresh
+         * (undefined) attempt count. Steady state was a 3-turn cycle that spawned
+         * and cut the slow suite on every turn. The retired set is persisted on
+         * the record instead.
+         *
+         * Round 4, I1: this is a SELECTION filter and nothing more. Round 3 also
+         * wrote the filtered list straight back, so a turn taken by the other
+         * entry point into the same project — `clients/mcp/session.ts` passes no
+         * `sessionId` and falls back to `telemetrySessionId`, while `index.ts`
+         * passes pi's stable id — erased the entries belonging to the other
+         * route. Both lists survive every write now; see `writeTestFindings`.
+         */
+        const retiredCarry = (priorTestCache?.retiredTargets ?? []).filter(isThisSession);
+        const retiredKeys = new Set(retiredCarry.map(entryPathKey));
+        /**
+         * Deferral entries of THIS session that this turn has settled: dispatched
+         * into `targets`, retired at the cap, or dropped as unrunnable. Only
+         * these may leave the persisted list, and only when this turn's own write
+         * is not re-asserting them (a cut target comes straight back with
+         * `attempts + 1`).
+         */
+        const resolvedDeferralKeys = new Set();
+        /**
+         * #2522 review round 4, I5: entries this turn could not fit under
+         * `TEST_RUNNER_MAX_TARGETS`. They were not run, so they keep their attempt
+         * count and stay on the list — round 3 folded the over-cap case in with
+         * "no longer resolves" and dropped them outright, so a carry larger than
+         * the cap lost its tail every turn under a dbg line that said the files
+         * were gone.
+         */
+        const heldDeferred = [];
+        /**
+         * The ONE writer of `test-runner-findings` in this block, so the rules
+         * about what survives a write are stated once instead of at six call sites
+         * that a seventh would silently not join (#2522 review round 3, F1; same
+         * net-count rule as `retireTestFindings` in `runtime-context.ts`).
+         *
+         * Three rules, all of them round-4 invariants:
+         *  - I1: the LIVE record is re-read here and merged into, never replaced.
+         *    A row belonging to another session is untouchable — this turn may
+         *    ignore it, never delete it.
+         *  - I2: every write merges. A batch that publishes clean, a batch that
+         *    publishes failures and a superseded batch all go through this, so
+         *    none of them can overwrite a concurrent batch's cut set. Removal is
+         *    narrow by construction: an entry leaves only if it is this session's,
+         *    this turn settled it, and this write is not re-asserting it.
+         *  - the persisted lists are bounded (`TEST_RUNNER_MAX_PERSISTED_TARGETS`)
+         *    with this session's rows ordered LAST, so the bound sheds foreign
+         *    rows first and can never evict what this turn just recorded.
+         */
+        const boundPersisted = (entries, label) => {
+            const ordered = [
+                ...entries.filter((entry) => !isThisSession(entry)),
+                ...entries.filter(isThisSession),
+            ];
+            if (ordered.length <= TEST_RUNNER_MAX_PERSISTED_TARGETS)
+                return ordered;
+            dbg(`turn_end: ${label} test target list held ${ordered.length} entries, bounded to the newest ${TEST_RUNNER_MAX_PERSISTED_TARGETS} (oldest foreign-session rows dropped)`);
+            return ordered.slice(-TEST_RUNNER_MAX_PERSISTED_TARGETS);
+        };
+        const writeTestFindings = (record, ownDeferred) => {
+            const live = cacheManager.readCache("test-runner-findings", cwd)?.data;
+            const own = mergeDeferredTargets(heldDeferred, ownDeferred);
+            const ownKeys = new Set(own.map(entryPathKey));
+            const merged = mergeDeferredTargets(live?.deferredTargets ?? [], own).filter((entry) => {
+                if (!isThisSession(entry))
+                    return true;
+                const key = entryPathKey(entry);
+                return !resolvedDeferralKeys.has(key) || ownKeys.has(key);
+            });
+            cacheManager.writeCache("test-runner-findings", {
+                ...record,
+                deferredTargets: boundPersisted(merged, "deferred"),
+                retiredTargets: boundPersisted(mergeDeferredTargets(live?.retiredTargets ?? [], retiredCarry), "retired"),
+            }, cwd);
+        };
+        let deadDeferred = 0;
+        let heldOverCap = 0;
+        let foreignDeferred = 0;
+        let redispatchedDeferred = 0;
+        let retiredThisTurn = 0;
+        for (const carried of carriedDeferred) {
+            const testFile = path.resolve(cwd, carried.testFile);
+            const carriedKey = normalizeMapKey(testFile);
+            // I1: another session still owes this run. Skip it, leave it on the
+            // record — `writeTestFindings` never removes a row this turn does not
+            // own.
+            if (!isThisSession(carried)) {
+                foreignDeferred++;
+                continue;
+            }
+            if (seen.has(carriedKey)) {
+                resolvedDeferralKeys.add(carriedKey);
+                continue;
+            }
+            const attempts = carried.attempts ?? 0;
+            if (attempts >= TEST_RUNNER_MAX_DEFERRALS) {
+                resolvedDeferralKeys.add(carriedKey);
+                if (!retiredKeys.has(carriedKey)) {
+                    retiredKeys.add(carriedKey);
+                    retiredThisTurn++;
+                    retiredCarry.push({
+                        testFile,
+                        runner: carried.runner,
+                        attempts,
+                        sessionId: turnSessionId,
+                    });
+                    // Never silent, and counted rather than once-per-subject: this is
+                    // the ledger entry that names WHICH suite is too slow to belong in
+                    // a per-turn batch at all.
+                    incrementDegradationCount({
+                        kind: "test-runner-batch-capped",
+                        subject: `${cwd}:deferral-exhausted`,
+                        reason: `test target ${path.relative(cwd, testFile)} was cut at the turn-end batch budget ${attempts} turn(s) running and is retired from turn-end selection for the rest of this session — too slow for a per-turn batch, run it explicitly`,
+                    });
+                    dbg(`turn_end: retiring deferred test target ${path.relative(cwd, testFile)} after ${attempts} cut batch(es) — too slow for the turn-end budget, run it explicitly`);
+                }
+                continue;
+            }
+            // A RunnerConfig carries functions, so the cache stores the runner KEY
+            // and the config is re-resolved here from the single registry.
+            const config = RUNNERS[carried.runner];
+            if (!config ||
+                isExcludedTestTarget(testFile, cwd) ||
+                !fs.existsSync(testFile)) {
+                resolvedDeferralKeys.add(carriedKey);
+                deadDeferred++;
+                continue;
+            }
+            if (targets.length >= TEST_RUNNER_MAX_TARGETS) {
+                // I5: not settled — held, with `attempts` UNCHANGED. It was never
+                // dispatched, so charging it toward retirement would retire a suite
+                // this turn simply had no room for.
+                heldOverCap++;
+                heldDeferred.push({
+                    testFile,
+                    runner: carried.runner,
+                    attempts,
+                    sessionId: turnSessionId,
+                });
+                continue;
+            }
+            resolvedDeferralKeys.add(carriedKey);
+            seen.add(carriedKey);
+            redispatchedDeferred++;
+            targets.push({
+                testFile,
+                runner: carried.runner,
+                config,
+                strategy: "deferred",
+                deferralAttempts: attempts,
+            });
+            dbg(`turn_end: re-running deferred test target ${path.relative(cwd, testFile)} (${carried.runner}) from the previous turn's cut batch`);
+        }
+        if (deadDeferred > 0) {
+            dbg(`turn_end: dropped ${deadDeferred} deferred test target(s) that no longer resolve (missing file, excluded, or unknown runner)`);
+        }
+        if (heldOverCap > 0) {
+            dbg(`turn_end: held ${heldOverCap} deferred test target(s) over the per-turn cap of ${TEST_RUNNER_MAX_TARGETS} — kept on the deferral list for the next turn, attempts unchanged`);
+        }
+        if (foreignDeferred > 0) {
+            dbg(`turn_end: ignored ${foreignDeferred} deferred test target(s) belonging to another session — left on the record for the session that cut them`);
+        }
+        if (carriedDeferred.length > 0) {
+            // #2522 review round 4, S1: the ONE pushed record for this path. The
+            // MCP / Stop-hook route calls `handleTurnEnd` with `dbg: noop`, so every
+            // line above is invisible there and the deferral machinery — the part
+            // that decides whether a suite runs at all — left no trace whatsoever
+            // on the route that fires it most.
+            logLatency({
+                type: "phase",
+                toolName: "turn_end",
+                filePath: cwd,
+                phase: "test_runner_deferral",
+                durationMs: 0,
+                metadata: {
+                    carried: carriedDeferred.length,
+                    redispatched: redispatchedDeferred,
+                    heldOverCap,
+                    retired: retiredThisTurn,
+                    dropped: deadDeferred,
+                    foreignSession: foreignDeferred,
+                    sessionId: turnSessionId,
+                },
+            });
+        }
+        let overCapTargets = 0;
+        let missingTargetFiles = 0;
+        let excludedTargets = 0;
+        let retiredSkips = 0;
         for (const { display, abs, isNeighbor } of candidates) {
             const target = testRunnerClient.getTestRunTarget(abs, cwd, runtime.turnIndex);
-            if (target && !seen.has(target.testFile)) {
-                seen.add(target.testFile);
+            const targetKey = target ? normalizeMapKey(target.testFile) : "";
+            if (target && !seen.has(targetKey)) {
+                seen.add(targetKey);
+                // #2522 review round 3, F1: THE gate that makes the deferral cap a
+                // cap. Whichever strategy produced this target — related, self,
+                // failed-first — a target already retired this session for
+                // outrunning the whole batch budget is not fired again. Without
+                // this the retire branch above was decorative: it logged, and the
+                // candidate loop three lines down re-resolved the same file and
+                // spawned it anyway, with its attempt counter reset to zero.
+                if (retiredKeys.has(targetKey)) {
+                    retiredSkips++;
+                    dbg(`turn_end: ${display} → test target retired earlier this session (outran the turn-end batch budget), skipping spawn (${path.relative(cwd, target.testFile)})`);
+                    continue;
+                }
+                // #2522: built-in exclusion for turn-end SELECTION — a resolved
+                // target under an integration/e2e directory or naming convention
+                // is never auto-fired, whichever strategy (failed-first/related/
+                // self) produced it. No per-project config knob (maintainer
+                // decision); see `TURN_END_EXCLUDED_TEST_GLOBS`.
+                // LATENT HAZARD, deliberately left as-is: this `continue` skips the
+                // candidate entirely, including `retireMissingFailedTargets`. If an
+                // excluded target were ever seeded into the persisted failed set
+                // (it cannot be today — nothing writes that set except a runner
+                // RESULT, and an excluded target is never run, so it can never
+                // produce one), it would sit there unretired forever, chosen by
+                // the failed-first strategy on every turn and dropped here on
+                // every turn. Any future writer of the failed set must retire
+                // excluded entries at the write site, not here.
+                if (isExcludedTestTarget(target.testFile, cwd)) {
+                    excludedTargets++;
+                    dbg(`turn_end: ${display} → test target excluded (integration/e2e), skipping spawn (${path.relative(cwd, target.testFile)})`);
+                    continue;
+                }
+                // #2504: a conventional target that no longer exists on disk still
+                // cost a full runner spawn, which came back "Test file not found"
+                // and was then dropped as an expected skip further down. 9 of the
+                // reported turn's 59 spawns were this. One statSync is cheaper
+                // than a vitest process by four orders of magnitude.
+                if (!fs.existsSync(target.testFile)) {
+                    missingTargetFiles++;
+                    dbg(`turn_end: ${display} → test file missing, skipping spawn (${path.relative(cwd, target.testFile)})`);
+                    continue;
+                }
+                if (targets.length >= TEST_RUNNER_MAX_TARGETS) {
+                    overCapTargets++;
+                    continue;
+                }
                 targets.push(target);
                 dbg(`turn_end: ${display} → test ${target.runner} ${path.relative(cwd, target.testFile)} (${target.strategy}${isNeighbor ? ", cascade-neighbor" : ""})`);
             }
@@ -1502,11 +2047,30 @@ export async function handleTurnEnd(deps) {
                 dbg(`turn_end: ${display} → no test file found${isNeighbor ? " (cascade-neighbor)" : ""}`);
             }
         }
+        if (excludedTargets > 0) {
+            dbg(`turn_end: excluded ${excludedTargets} test target(s) under the built-in integration/e2e exclusion list`);
+        }
+        if (retiredSkips > 0) {
+            dbg(`turn_end: skipped ${retiredSkips} test target(s) retired earlier this session for outrunning the turn-end batch budget`);
+        }
+        if (missingTargetFiles > 0) {
+            dbg(`turn_end: skipped ${missingTargetFiles} test target(s) whose file no longer exists`);
+        }
+        if (overCapTargets > 0) {
+            // Never silent: the agent is told that some of this turn's tests were
+            // not run, rather than reading an all-green batch that covered part
+            // of the edit set.
+            recordDegradationOnce({
+                kind: "test-runner-batch-capped",
+                subject: cwd,
+                reason: `turn touched more test targets than one turn may fire; ran ${TEST_RUNNER_MAX_TARGETS}, skipped ${overCapTargets} — re-run the remainder with lens_diagnostics or edit them in a smaller batch`,
+            });
+            dbg(`turn_end: test target count capped at ${TEST_RUNNER_MAX_TARGETS}, ${overCapTargets} skipped`);
+        }
         if (targets.length > 0) {
-            dbg(`turn_end: firing ${targets.length} test target(s) async (non-blocking)`);
+            dbg(`turn_end: firing ${targets.length} test target(s) async (non-blocking, max ${TEST_RUNNER_BATCH_CONCURRENCY} concurrent)`);
             const firedAtTurn = runtime.turnIndex;
-            const firedSessionId = runtime.telemetrySessionId;
-            const priorTestCache = cacheManager.readCache("test-runner-findings", cwd)?.data;
+            const firedSessionId = turnSessionId;
             const testRunGeneration = (priorTestCache?.testRunGeneration ?? 0) + 1;
             const provenanceFiles = [
                 ...candidates.map((candidate) => ({
@@ -1524,13 +2088,91 @@ export async function handleTurnEnd(deps) {
                 generation: testRunGeneration,
                 files: provenanceFiles,
             });
-            cacheManager.writeCache("test-runner-findings", { ...(priorTestCache ?? { content: "" }), testRunGeneration }, cwd);
-            Promise.allSettled(targets.map((t) => testRunnerClient.runTestFileAsync(t.testFile, cwd, {
-                runner: t.runner,
-                config: t.config,
-                turnIndex: firedAtTurn,
-            })))
-                .then((results) => {
+            writeTestFindings({
+                ...(priorTestCache ?? { content: "" }),
+                testRunGeneration,
+            }, 
+            // Consumed above into `targets` (or retired, or dropped). Anything
+            // this turn HELD is re-asserted by the writer itself; the batch's own
+            // outcome adds the NEW cut set below.
+            []);
+            runTestTargetsBounded({
+                targets,
+                concurrency: TEST_RUNNER_BATCH_CONCURRENCY,
+                budgetMs: TEST_RUNNER_BATCH_BUDGET_MS,
+                // Both bounds, per AGENTS.md: a wall budget AND the ambient
+                // abort signal the rest of the spawn layer already honours.
+                signal: getAmbientAbortSignal(),
+                run: (t, batchSignal) => testRunnerClient.runTestFileAsync(t.testFile, cwd, {
+                    runner: t.runner,
+                    config: t.config,
+                    turnIndex: firedAtTurn,
+                    // #2522 R2 F1: the BATCH's signal, so spending the 20s wall
+                    // budget kills this spawn rather than letting it run out its
+                    // own 60s timeout behind a batch that has already returned.
+                    signal: batchSignal,
+                }),
+            })
+                .then(({ results, deferred, stopReason }) => {
+                const deferredTargets = deferred.map((t) => ({
+                    testFile: t.testFile,
+                    runner: t.runner,
+                    // One more cut batch for this target. Read back by the
+                    // selection loop above, which retires it at
+                    // TEST_RUNNER_MAX_DEFERRALS rather than carrying it forever.
+                    attempts: (t.deferralAttempts ?? 0) + 1,
+                    // #2522 R3 F5: stamped with the session that cut it, so the
+                    // next session re-arms this target instead of inheriting an
+                    // attempt count measured under a load it never saw.
+                    sessionId: firedSessionId,
+                }));
+                if (deferred.length > 0) {
+                    // #2522 review round 2, F4: `incrementDegradationCount`, not
+                    // `recordDegradationOnce`. At a 20s budget this is a
+                    // RECURRING event, and a once-per-subject entry reports the
+                    // tenth cut batch of a session exactly like the first.
+                    incrementDegradationCount({
+                        kind: "test-runner-batch-capped",
+                        subject: `${cwd}:${stopReason ?? "incomplete"}`,
+                        reason: `test batch stopped early (${stopReason ?? "incomplete"}); ${deferred.length} target(s) killed or never dispatched, deferred to the next turn`,
+                    });
+                    dbg(`turn_end: test batch stopped early (${stopReason ?? "incomplete"}), ${deferred.length} target(s) deferred to the next turn`);
+                }
+                const deferralNote = deferred.length > 0
+                    ? `${deferred.length} test target(s) did not finish within the turn-end batch budget and are deferred to the next turn (they run first): ${deferredTargets
+                        .map((t) => path.relative(cwd, t.testFile))
+                        .join(", ")}`
+                    : "";
+                /**
+                 * A newer batch has already published for this project — this
+                 * one's results are stale by construction and must not overwrite
+                 * it. Was inlined three times; extracted once round 2 added a
+                 * fourth call site.
+                 */
+                const supersededByNewerGeneration = (label) => {
+                    const current = cacheManager.readCache("test-runner-findings", cwd)?.data;
+                    const currentGeneration = current?.testRunGeneration;
+                    if (currentGeneration !== undefined &&
+                        currentGeneration > testRunGeneration) {
+                        dbg(`turn_end: ${label}test generation ${testRunGeneration} superseded by ${currentGeneration}`);
+                        // #2522 review round 3, F3: returning here USED to drop this
+                        // batch's cut targets entirely. The newer batch's own pre-run
+                        // write already cleared them, and it never saw this set — so
+                        // with two overlapping batches the targets the older one was
+                        // cut on were never deferred, never re-selected, and the suite
+                        // they belong to simply never ran again. Hand them over
+                        // instead. Round 4, I2: the merge is `writeTestFindings`'s own
+                        // rule now, not a second copy of it here — every branch below
+                        // merges the same way, so a NEWER batch publishing after this
+                        // one no longer flattens what this hand-over just recorded.
+                        if (deferredTargets.length > 0) {
+                            writeTestFindings({ ...(current ?? { content: "" }) }, deferredTargets);
+                            dbg(`turn_end: ${label}carried ${deferredTargets.length} cut target(s) into the newer generation's deferral set`);
+                        }
+                        return true;
+                    }
+                    return false;
+                };
                 const publishedAgainst = snapshotAdvisoryProvenance({
                     cwd,
                     runtime,
@@ -1553,13 +2195,40 @@ export async function handleTurnEnd(deps) {
                 const stale = runtime.turnIndex !== firedAtTurn;
                 const failures = [];
                 const resultValues = [];
+                let rejectedCount = 0;
+                // #2522: whether ANY reported item is a genuine failing test
+                // (`failed > 0`) as opposed to the runner itself never
+                // completing (timeout, missing provider/binary, a rejected
+                // promise). Drives the delivery framing below — a batch made
+                // up ENTIRELY of runner errors is not something the agent
+                // introduced, so it must not read as "fix before continuing".
+                let hasRealFailure = false;
                 for (const r of results) {
                     if (r.status === "rejected") {
+                        rejectedCount++;
+                        emitBounded("test_runner_delivery", `${cwd}:generation:${testRunGeneration}:rejected`, {
+                            filePath: cwd,
+                            durationMs: 0,
+                            metadata: {
+                                outcome: "runner-promise-rejected",
+                                sessionId: firedSessionId,
+                                generation: testRunGeneration,
+                                targetCount: targets.length,
+                                droppedDetailCount: 0,
+                                reason: String(r.reason).slice(0, 500),
+                            },
+                        }, {
+                            ledgerKind: "test-runner-delivery",
+                            reason: "test runner promise rejected",
+                            capPerTurn: { limit: 8, turnIndex: firedAtTurn },
+                        });
                         dbg(`turn_end: test run rejected — ${r.reason}`);
                         continue;
                     }
                     resultValues.push(r.value);
                     const { file, runner, passed, failed, duration, error } = r.value;
+                    if (failed > 0)
+                        hasRealFailure = true;
                     const shortFile = path.basename(file);
                     // #1479: `(0ms)` used to be printed for a run nobody
                     // timed — a payload with no suite timestamps, an
@@ -1581,19 +2250,33 @@ export async function handleTurnEnd(deps) {
                     // `elapsed` is: the pair read as a nested ternary, which
                     // this line only got flagged for because #1479 touched it.
                     const verdict = failed > 0 ? "FAIL" : "PASS";
-                    const summary = error && passed === 0 && failed === 0
-                        ? `error: ${error}`
+                    // #2532 review S1: folded onto `isRunnerErrorResult` instead of
+                    // re-deriving `error && passed === 0 && failed === 0` here — that
+                    // local spelling missed a runner error reported alongside partial
+                    // passes (pytest `Interrupted` after some tests already passed),
+                    // which read as a clean "PASS Np/0f" line with the error silently
+                    // dropped. A partial run says so explicitly rather than reading
+                    // as a clean pass.
+                    const summary = isRunnerErrorResult(r.value)
+                        ? passed > 0
+                            ? `error: ${error} (${passed} passed before)`
+                            : `error: ${error}`
                         : `${verdict} ${passed}p/${failed}f (${elapsed})`;
                     dbg(`turn_end: ${stale ? "[stale] " : ""}test ${runner} ${shortFile} → ${summary}`);
                     // #1524: also fires on `error` alone, not just `failed > 0`.
-                    // A runner-error result (the suite never started — spawn/
-                    // config failure) has `failed === 0` by construction, so
-                    // gating on `failed > 0` alone dropped it silently: the
-                    // agent got no context at all, and the empty `failures`
-                    // array below sent this result down the "all tests
-                    // passed" branch, clearing any prior real test-failure
-                    // git-guard blocker. `formatResult` already renders the
-                    // error-only case as "Could not run tests: ...".
+                    // A runner error (the suite never started, or was
+                    // interrupted before finishing — spawn/config/timeout
+                    // failure) can arrive with `failed === 0` even when tests
+                    // DID pass before it (#2532 review S2 — not "by
+                    // construction": `parsePytestOutput` sets `error` from the
+                    // exit code independently of the parsed counts, so
+                    // `isRunnerErrorResult` is `failed === 0 && !!error`, not an
+                    // invariant elsewhere). Gating on `failed > 0` alone dropped
+                    // it silently: the agent got no context at all, and the
+                    // empty `failures` array below sent this result down the
+                    // "all tests passed" branch, clearing any prior real
+                    // test-failure git-guard blocker. `formatResult` already
+                    // renders the error-only case as "Could not run tests: ...".
                     if (failed > 0 || error) {
                         // #2028: "Test file not found" is an expected skip
                         // (conventional test path without an actual file),
@@ -1607,17 +2290,32 @@ export async function handleTurnEnd(deps) {
                             failures.push(formatted);
                     }
                 }
+                if (rejectedCount > 0) {
+                    failures.push(`Test runner rejected ${rejectedCount} promise(s) before producing a structured result.`);
+                }
                 if (failures.length > 0) {
-                    const currentGeneration = cacheManager.readCache("test-runner-findings", cwd)?.data?.testRunGeneration;
-                    if (currentGeneration !== undefined &&
-                        currentGeneration > testRunGeneration) {
-                        dbg(`turn_end: test generation ${testRunGeneration} superseded by ${currentGeneration}`);
+                    if (supersededByNewerGeneration(""))
                         return;
-                    }
-                    const content = stale
-                        ? `[from a prior turn — the edit that triggered this run had already been superseded by the time results came back]\n\n${failures.join("\n\n")}`
-                        : failures.join("\n\n");
-                    cacheManager.writeCache("test-runner-findings", {
+                    const content = [
+                        stale
+                            ? "[from a prior turn — the edit that triggered this run had already been superseded by the time results came back]"
+                            : "",
+                        failures.join("\n\n"),
+                        // A batch can BOTH find a real failure and be cut short.
+                        // The agent needs to see the failure AND that the run was
+                        // incomplete, or it reads a partial list as the full one.
+                        deferralNote,
+                    ]
+                        .filter(Boolean)
+                        .join("\n\n");
+                    // #2522: nothing in this batch is a genuine failing test —
+                    // every entry is a runner error (timeout, missing
+                    // provider/binary, a rejected promise). `peekTestFindings`
+                    // reads this to deliver advisory framing instead of
+                    // "fix before continuing", since the agent introduced
+                    // nothing here to fix.
+                    const runnerErrorOnly = !hasRealFailure;
+                    writeTestFindings({
                         content,
                         stale,
                         results: resultValues,
@@ -1626,7 +2324,20 @@ export async function handleTurnEnd(deps) {
                         publishedAgainst,
                         provenance: publishedAgainst,
                         superseded,
-                    }, cwd);
+                        runnerErrorOnly,
+                    }, deferredTargets);
+                    try {
+                        deps.onTestRunnerComplete?.({
+                            cwd,
+                            sessionId: firedSessionId,
+                            generation: testRunGeneration,
+                            targetCount: targets.length,
+                            hasFindings: true,
+                        });
+                    }
+                    catch (deliveryErr) {
+                        dbg(`turn_end: test delivery staging failed — ${deliveryErr}`);
+                    }
                     if (getFlag("lens-guard") &&
                         firedSessionId === runtime.telemetrySessionId) {
                         // #1524: `&& !value.error` — a runner-error result has
@@ -1648,13 +2359,117 @@ export async function handleTurnEnd(deps) {
                         if (cleanFiles.length > 0) {
                             clearGitGuardTestFailure(cacheManager, cwd, runtime, cleanFiles);
                         }
-                        mergeGitGuardTestFailure(cacheManager, cwd, runtime, content, resultValues
-                            .filter((value) => value.failed > 0)
-                            .map((value) => value.file));
+                        // #2532: `runnerErrorOnly` (computed above for the turn-end
+                        // delivery framing) is true exactly when nothing in this
+                        // batch is a genuine failing test — every entry is a
+                        // runner error the agent did not introduce. Without this
+                        // gate, an all-runner-error batch still called
+                        // `mergeGitGuardTestFailure` with an EMPTY failed-files
+                        // list, which unconditionally sets `hasBlockers: true`:
+                        // the identical event the turn-end message reports as
+                        // advisory read as "COMMIT BLOCKED" under --lens-guard.
+                        if (!runnerErrorOnly) {
+                            mergeGitGuardTestFailure(cacheManager, cwd, runtime, content, resultValues
+                                .filter((value) => value.failed > 0)
+                                .map((value) => value.file));
+                        }
+                        else {
+                            // #2532 review T2: the skip above is otherwise pull-only —
+                            // nothing records that a batch with real content
+                            // (`failures.length > 0`) was deliberately kept OFF the
+                            // `--lens-guard` blocker because every entry was a runner
+                            // error. Same phase/ledger as the rejected-promise event
+                            // above, so both `--lens-guard` demotions land in one
+                            // queryable place. Reached only inside the enclosing
+                            // `getFlag("lens-guard") && firedSessionId === …` check —
+                            // no point recording a demotion the flag can't act on.
+                            emitBounded("test_runner_delivery", `${cwd}:generation:${testRunGeneration}:runner-error-only`, {
+                                filePath: cwd,
+                                durationMs: 0,
+                                metadata: {
+                                    outcome: "runner-error-only-not-blocking",
+                                    sessionId: firedSessionId,
+                                    generation: testRunGeneration,
+                                    targetCount: targets.length,
+                                    droppedDetailCount: 0,
+                                },
+                            }, {
+                                ledgerKind: "test-runner-delivery",
+                                reason: "runner-error-only batch kept off the --lens-guard blocker",
+                                capPerTurn: { limit: 8, turnIndex: firedAtTurn },
+                            });
+                        }
                     }
-                    dbg(`turn_end: ${failures.length} test failure(s) cached for next context injection${stale ? " (stale — turn advanced while tests ran)" : ""}`);
+                    dbg(`turn_end: ${failures.length} test failure(s) cached for pull diagnostics and post-agent delivery${stale ? " (stale — turn advanced while tests ran)" : ""}`);
+                }
+                else if (deferred.length > 0) {
+                    // #2522 review round 2, F1: a PARTIAL batch is not a clean
+                    // batch. Pre-round-2 this fell through to the branch below —
+                    // `content: ""`, "all tests passed", and a `--lens-guard`
+                    // clear — on the strength of a run that never finished. The
+                    // record names the deferral instead; the commit gate is left
+                    // exactly as it was, because nothing here proves anything
+                    // passed that was not already proven.
+                    if (supersededByNewerGeneration("deferred "))
+                        return;
+                    writeTestFindings({
+                        content: deferralNote,
+                        stale,
+                        results: resultValues,
+                        testRunGeneration,
+                        launchedFrom,
+                        publishedAgainst,
+                        provenance: publishedAgainst,
+                        superseded,
+                        // Advisory framing: an unfinished batch is not a
+                        // failure the agent introduced, exactly like a runner
+                        // error. See `TestRunnerFindingsCache.runnerErrorOnly`.
+                        runnerErrorOnly: true,
+                    }, deferredTargets);
+                    try {
+                        deps.onTestRunnerComplete?.({
+                            cwd,
+                            sessionId: firedSessionId,
+                            generation: testRunGeneration,
+                            targetCount: targets.length,
+                            hasFindings: true,
+                        });
+                    }
+                    catch (deliveryErr) {
+                        dbg(`turn_end: test delivery staging failed — ${deliveryErr}`);
+                    }
+                    dbg(`turn_end: partial test batch — ${results.length} target(s) settled, ${deferred.length} deferred to the next turn; NOT recorded as a clean run`);
                 }
                 else if (results.length > 0) {
+                    if (supersededByNewerGeneration("clean "))
+                        return;
+                    writeTestFindings({
+                        ...(priorTestCache ?? { content: "" }),
+                        content: "",
+                        stale: false,
+                        results: resultValues,
+                        testRunGeneration,
+                        launchedFrom,
+                        publishedAgainst,
+                        provenance: publishedAgainst,
+                        superseded,
+                    }, 
+                    // Nothing was cut. This turn's own settled entries drop out;
+                    // I2 keeps every row this batch does not own — including a
+                    // concurrent older batch's hand-over.
+                    []);
+                    try {
+                        deps.onTestRunnerComplete?.({
+                            cwd,
+                            sessionId: firedSessionId,
+                            generation: testRunGeneration,
+                            targetCount: targets.length,
+                            hasFindings: false,
+                        });
+                    }
+                    catch (deliveryErr) {
+                        dbg(`turn_end: test delivery staging failed — ${deliveryErr}`);
+                    }
                     if (getFlag("lens-guard") &&
                         firedSessionId === runtime.telemetrySessionId) {
                         clearGitGuardTestFailure(cacheManager, cwd, runtime, resultValues.map((value) => value.file));
@@ -1664,6 +2479,17 @@ export async function handleTurnEnd(deps) {
             })
                 .catch(() => { });
         }
+        else if (carriedDeferred.length > 0) {
+            // Nothing fired, so no batch outcome will write the list back, but this
+            // turn still settled part of it (targets retired at the cap, or dropped
+            // because their file is gone). Persist that here rather than re-reading
+            // a set of dead paths on every future turn; `writeTestFindings` carries
+            // this turn's retirements alongside, which is what the deferral-cap
+            // branch above depends on when it retires the LAST carried target and
+            // fires nothing. Rows this turn only HELD (over the cap) or does not
+            // own (another session's) are re-asserted by the writer itself.
+            writeTestFindings({ ...(priorTestCache ?? { content: "" }) }, []);
+        }
     }
     if (runtime.errorDebtBaseline && files.length > 0) {
         dbg("turn_end: marking error debt check for next session");
@@ -1797,10 +2623,79 @@ export async function handleTurnEnd(deps) {
                 fileSeqByPath,
                 deltaOnly: !getFlag("lens-actionable-warning-all"),
                 dbg,
+                // #2504: this call is AWAITED on the turn_end hook, so its cost is
+                // terminal-blocking time. The file cap and wall budget are its
+                // bounds; the abort signal is the second one AGENTS.md requires.
+                signal: getAmbientAbortSignal(),
+                // A cold-cache turn hands the fresh-pull loop back here, off the
+                // hook — it lands in the same cache the in-band report goes to.
+                onDeferredReport: (deferred) => {
+                    try {
+                        // #2504 review round 2 (F2): GUARDED. This callback fires up
+                        // to a minute after the turn that armed it, and the report
+                        // it carries is stamped with THAT turn's
+                        // turnIndex/projectSeq. Writing it unconditionally
+                        // overwrote a newer report, which `agent_end` then rejected
+                        // as `project_seq_mismatch` (silently skipping the autofix
+                        // pass) and `lens_diagnostics` re-served as a stale delta.
+                        // #2504 review round 4 (F1): guarded PER FILE, not per
+                        // report. The round-3 shape (publish, or discard whole
+                        // when something newer is persisted) composed with
+                        // incumbent-wins into "publish nothing" — every turn_end
+                        // with modified files persists an in-band report with a
+                        // strictly increasing turnIndex, and the decline fires
+                        // exactly when such a turn runs while a loop is in
+                        // flight, so a decline always implied a supersede. The
+                        // merge upserts the entries whose file has not moved and
+                        // drops only those that have.
+                        writeDeferredActionableWarningsReport({
+                            cacheManager,
+                            cwd,
+                            report: deferred,
+                            // The LIVE per-file sequence at WRITE time is the
+                            // baseline the merge judges each entry against. The
+                            // runtime is the only thing that knows it: a file
+                            // edited into cleanliness by a later turn is absent
+                            // from the persisted report entirely.
+                            getFileSeq: getFileSeq
+                                ? (filePath) => getFileSeq.call(runtime, filePath)
+                                : undefined,
+                            dbg,
+                        });
+                    }
+                    catch (deferErr) {
+                        dbg(`turn_end: deferred actionable-warnings write failed — ${deferErr}`);
+                    }
+                },
+            });
+            // #2504 review round 5 (F1): THE publish choke point. This was a
+            // blind `writeActionableWarningsReport` while the deferred callback
+            // above read-modify-wrote the SAME cache key. The deferred merge can
+            // land anywhere inside this handleTurnEnd -- the cascade settle,
+            // knip, madge, the test batch, the in-band LSP enrichment are all
+            // awaited between the moment it is armed and the moment we get
+            // here -- and the blind write erased it 607 ms later in the
+            // reviewer's trace. The publisher now always reads what is persisted
+            // and merges per file, so the two writers cannot race. It carries
+            // forward only entries a DEFERRAL produced, and only while their
+            // file has not moved, so a `turn_delta` report does not accumulate
+            // every prior turn's findings.
+            const publishResult = publishActionableWarningsReport(cacheManager, cwd, report, {
+                origin: "in-band",
+                getFileSeq: getFileSeq
+                    ? (filePath) => getFileSeq.call(runtime, filePath)
+                    : undefined,
+                dbg,
             });
-            writeActionableWarningsReport(cacheManager, cwd, report);
-            appendActionableWarningsHistory(cwd, report);
-            const advisory = formatActionableWarningsAdvisory(report);
+            // #2504 review round 6 (a): the advisory must read the MERGED report,
+            // not the pre-merge `report` this turn assembled -- a rescued deferred
+            // entry lives only on `publishResult.report`, and formatting the
+            // pre-merge report silently dropped it from the turn_end advisory
+            // even though it was correctly persisted to cache.
+            // #2521: `cwd` is what resolves the store location the advisory
+            // names -- it is the SAME cwd `publishActionableWarningsReport`
+            // just wrote through, so the two cannot disagree.
+            const advisory = formatActionableWarningsAdvisory(publishResult.report, cwd);
             // @delivery-surface: runtime-turn:actionable-warnings-advisory
             if (advisory)
                 advisoryParts.push(advisory);
@@ -1809,7 +2704,13 @@ export async function handleTurnEnd(deps) {
                 sessionId: runtime.telemetrySessionId,
                 metadata: {
                     turnIndex: runtime.turnIndex,
-                    unsuppressed: report.summary.unsuppressed,
+                    // #2504 review round 7 (F2): the MERGED report, matching the
+                    // advisory text above it (round 6, a) -- a rescued deferred
+                    // entry lives only on `publishResult.report`, and the pre-merge
+                    // `report` this turn assembled undercounts it. This is the value
+                    // scripts/analyze-pi-lens-logs.mjs sums, so an undercount here is
+                    // a silent miscount there too.
+                    unsuppressed: publishResult.report.summary.unsuppressed,
                 },
             });
             logLatency({
@@ -1850,7 +2751,7 @@ export async function handleTurnEnd(deps) {
         });
         writeCodeQualityWarningsReport(cacheManager, cwd, qualityReport);
         appendCodeQualityWarningsHistory(cwd, qualityReport);
-        const advisory = formatCodeQualityWarningsAdvisory(qualityReport);
+        const advisory = formatCodeQualityWarningsAdvisory(qualityReport, cwd);
         // @delivery-surface: runtime-turn:code-quality-warnings-advisory
         if (advisory)
             advisoryParts.push(advisory);
@@ -1975,6 +2876,10 @@ export async function handleTurnEnd(deps) {
     let lateAuxExpired = 0;
     let lateAuxCeilingExhausted = 0;
     let lateAuxAnswered = 0;
+    let lateAuxNotifyStallDemoted = 0;
+    const lateAuxCoverageGapPairs = [];
+    let lateAuxCoverageGapDetailCount = 0;
+    let lateAuxCoverageGapDropCount = 0;
     const lateAuxStuckPairs = [];
     if (drainedPairs.length > 0) {
         const byFile = new Map();
@@ -2026,6 +2931,40 @@ export async function handleTurnEnd(deps) {
                         lateAuxClientGone += 1;
                         continue;
                     }
+                    if (cachedEntry.notifyStallDemoted) {
+                        if (cachedEntry.demotedAt === undefined ||
+                            pair.markedAtMs > cachedEntry.demotedAt) {
+                            // A pair marked after teardown belongs to the missing
+                            // generation, so it follows ordinary clientGone handling.
+                            lateAuxClientGone += 1;
+                            continue;
+                        }
+                        // #2356: notify-stall teardown is a transient absence while the
+                        // breaker cools down, but only for a pair marked before teardown.
+                        lateAuxNotifyStallDemoted += 1;
+                        const pastTtl = isPendingAuxiliaryPastRearmTtl(pair);
+                        const atCeiling = (pair.rearmCount ?? 0) >= MAX_LATE_AUX_REARMS;
+                        if (!pastTtl && !atCeiling) {
+                            rearmPendingAuxiliaryCoverage(pair);
+                            lateAuxRearmed += 1;
+                            if (lateAuxStuckPairs.length < 20)
+                                lateAuxStuckPairs.push({
+                                    filePath: pair.filePath,
+                                    serverId: pair.serverId,
+                                });
+                        }
+                        else {
+                            if (pastTtl)
+                                lateAuxExpired += 1;
+                            else
+                                lateAuxCeilingExhausted += 1;
+                            lateAuxCoverageGapPairs.push({
+                                filePath: pair.filePath,
+                                serverId: pair.serverId,
+                            });
+                        }
+                        continue;
+                    }
                     const rawDiags = cachedEntry.diags;
                     if (cachedEntry.publishedAt === undefined ||
                         cachedEntry.publishedAt <= pair.markedAtMs) {
@@ -2117,6 +3056,33 @@ export async function handleTurnEnd(deps) {
         catch (err) {
             dbg(`turn_end: late-auxiliary probe failed: ${err}`);
         }
+        // #2356: a demoted scanner that never gets replaced remains a coverage
+        // gap. Re-raise it once when the existing bounded late-pair window closes,
+        // preserving the server/file identity in both the ledger and latency row.
+        for (const pair of lateAuxCoverageGapPairs) {
+            const normalizedPairPath = normalizeMapKey(pair.filePath);
+            const emitted = emitBounded("lsp_scanner_coverage_gap", `${pair.serverId}:${normalizedPairPath}`, {
+                filePath: normalizedPairPath,
+                durationMs: 0,
+                metadata: {
+                    source: "late-auxiliary",
+                    serverIds: [pair.serverId],
+                    reason: "notify-stall-replacement-unavailable",
+                    reRaised: true,
+                },
+            }, {
+                ledgerKind: "lsp-scanner-coverage-gap",
+                reason: "notify-stall replacement was not available before late-coverage ceiling",
+                capPerTurn: {
+                    limit: LATE_AUX_COVERAGE_GAP_DETAIL_CAP_PER_TURN,
+                    turnIndex: runtime.turnIndex,
+                },
+            });
+            if (emitted)
+                lateAuxCoverageGapDetailCount += 1;
+            else
+                lateAuxCoverageGapDropCount += 1;
+        }
         logLatency({
             type: "phase",
             toolName: "turn_end",
@@ -2137,6 +3103,10 @@ export async function handleTurnEnd(deps) {
                 expired: lateAuxExpired,
                 ceilingExhausted: lateAuxCeilingExhausted,
                 answered: lateAuxAnswered,
+                notifyStallDemoted: lateAuxNotifyStallDemoted,
+                coverageGapReRaised: lateAuxCoverageGapPairs.length,
+                coverageGapReRaisedDetailed: lateAuxCoverageGapDetailCount,
+                coverageGapReRaisedDropped: lateAuxCoverageGapDropCount,
                 capEvicted: lateAuxCapEvicted,
                 stuckPairs: lateAuxStuckPairs,
             },
@@ -2325,6 +3295,11 @@ export async function handleTurnEnd(deps) {
             // answers that from latency.log even when the payload is empty, and
             // the payload itself carries the retirement note when it is not.
             demotedFindingsRetired,
+            // #2275: the widget-footer store's own dependency-drift retirements —
+            // a separate surface/counter from `demotedFindingsRetired` above,
+            // since a widget retirement never touches `advisoryParts` or the
+            // `turn-end-findings-last` suppression cache the block below clears.
+            widgetDemotedFindingsRetired,
         },
     });
     resetFormatService();