@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/actionable-warnings.js

@@ -4,11 +4,14 @@ import * as path from "node:path";
 import { hashText, normalizeMessage, stableFindingId, } from "./finding-identity.js";
 import { applyWorkspaceEdit } from "./lsp/edits.js";
 import { getLSPService } from "./lsp/index.js";
-import { normalizeMapKey } from "./path-utils.js";
+import { isUnderDir, normalizeMapKey } from "./path-utils.js";
+import { bounded, combineAbortSignals, withDeadline, } from "./deadline-utils.js";
+import { armDeferredLspWork, awaitDeferredLspWork, registerDeferredLspWork, } from "./deferred-lsp-work.js";
+import { incrementDegradationCount, recordDegradationOnce, } from "./degradation-ledger.js";
 import { recordLspMutationBatch, } from "./lsp-mutation.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 import { logActionableWarningsEvent } from "./actionable-warnings-logger.js";
-import { getProjectDataDir } from "./file-utils.js";
+import { displayProjectDataPath, getProjectDataDir } from "./file-utils.js";
 import { commitDurableStore } from "./durable-store.js";
 let beforeWarningStateLockForTests = null;
 /** Test seam for a sibling process commit immediately before lock acquisition. */
@@ -305,10 +308,161 @@ function mergeWarnings(records) {
     return [...byId.values()].sort((a, b) => a.displayPath.localeCompare(b.displayPath) ||
         (a.line ?? 0) - (b.line ?? 0));
 }
+/**
+ * #2504 — bounds on the LSP enrichment loop.
+ *
+ * This function runs on the AWAITED turn_end hook. With `includeLspCodeActions`
+ * on and a cold LSP cache it opened every file it was handed and pulled fresh
+ * per-file diagnostics serially at ~880 ms each: 147 files, 187 891 ms, for
+ * `warnings: 0`. Three bounds, plus a project-root filter (it had opened
+ * `~/.claude/plans/*.md` in an LSP client), plus a deferral: when the turn
+ * primed NO cache, every file would be a fresh pull, so the whole loop moves
+ * off the hook and delivers through the cached channel instead.
+ */
+export const ACTIONABLE_WARNINGS_LSP_FILE_CAP = 25;
+export const ACTIONABLE_WARNINGS_LSP_BUDGET_MS = 2_500;
+export const ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS = 60_000;
+/**
+ * #2504 review round 2 (F3): the per-round-trip bound. The batch deadlines
+ * above are checked only BETWEEN files, so a single wedged `getDiagnostics`
+ * (or `openFile`, or `codeAction`) was unbounded no matter how small the
+ * batch budget was. Generous relative to the ~880 ms a real cold pull costs —
+ * this is a wedge detector, not a latency target.
+ */
+export const ACTIONABLE_WARNINGS_LSP_PULL_TIMEOUT_MS = 10_000;
+/**
+ * #2504 review round 3 (S-2): the third bound, per FILE.
+ *
+ * The wall budgets above are re-checked BETWEEN files only — deliberately, so
+ * that a file already opened is finished rather than half-enriched — and the
+ * per-round-trip timeout bounds one call. Neither bounds the COUNT of calls
+ * one file can demand: a generated or vendored file with hundreds of warnings
+ * on modified lines costs one `codeAction` round trip each, all inside a
+ * single between-files interval. This caps that fan-out. The abort signal
+ * still escapes promptly — `boundedLspCall` checks it on every trip.
+ */
+export const ACTIONABLE_WARNINGS_MAX_CODE_ACTIONS_PER_FILE = 25;
+/**
+ * The in-flight deferred fresh-pull, if any. Exposed for tests only: the
+ * deferral is fire-and-forget by design, and a test asserting that the work
+ * still happens off-hook needs a handle to await.
+ *
+ * #2504 review round 2 (F3): the handle no longer lives here as a bare
+ * module-level `let` that a second deferral silently overwrote (leaving the
+ * first loop running, untracked and unstoppable) and that nothing ever reset.
+ * `clients/deferred-lsp-work.ts` owns the single slot and its abort signal.
+ */
+export function _awaitDeferredLspPullForTest() {
+    return awaitDeferredLspWork();
+}
+/**
+ * Both bounds on ONE LSP round trip (#2504 review round 2, F3), as AGENTS.md
+ * requires of any async step in a sweep loop: a per-call timeout AND the abort
+ * signal. Resolves `undefined` when either bound wins; the caller reads that
+ * as "this file was not checked", never as "this file is clean".
+ *
+ * #2523 slice 2 folded this onto `bounded()`. It used to be `withDeadline`
+ * (deadline only) raced against a hand-built `abortRace` leg carried on the
+ * deps — the fifth private spelling of "deadline AND signal".
+ *
+ * What the fold did NOT fix, stated because the first draft of this PR claimed
+ * it did (#2557 review F5): the old shape did not silently degrade any wait.
+ * Both construction sites derived the leg from the signal in the same
+ * expression (`args.signal ? makeAbortRace(args.signal) : undefined`), so
+ * `abortRace` was absent exactly when `signal` was, and the behaviour before
+ * and after this fold is identical on that axis. What the fold actually buys
+ * is that the two fields which had to AGREE are now one — a pairing invariant
+ * that lived in prose is gone rather than enforced — plus the abandonment now
+ * reaching the ledger, and the leg's listener now being released per call
+ * instead of living as long as the loop's signal does.
+ *
+ * ## The loop's residual budget is a THIRD bound, and it must not reach the
+ * ledger (#2557 review F-A)
+ *
+ * Round 1 clamped `bounded()`'s own timer to
+ * `Math.min(pullTimeoutMs, remainingMs)`, so whenever the LOOP's own wall
+ * budget was already low, `bounded()` armed at the shrunken value and — on
+ * firing — recorded `hook-await-exceeded` naming THAT value as "the budget".
+ * A healthy pull that simply started late in a big batch was reported as
+ * exceeding a budget that exists in no configuration (measured: 400 ms
+ * pulls, 12 files, "exceeded 65ms budget after 77ms"), and because
+ * `recordDegradationOnce` is rising-edge, that benign row could silence a
+ * genuinely wedged server later in the same session.
+ *
+ * `bounded()`'s OWN timer is now always armed at the full `pullTimeoutMs`, so
+ * it only ever fires — and only ever records — when a call outlives its own
+ * configured per-trip budget (`metadata.budgetMs === pullTimeoutMs`, always).
+ * The loop's shrinking residual is enforced SEPARATELY, by racing `bounded()`
+ * against `withDeadline(…, { onTimeout: "undefined" })` keyed to the loop's
+ * own `deadlineAt` — a deadline-only wait with no ledger connection of its
+ * own, the same primitive `bounded()` itself is built to replace when a
+ * caller needs BOTH bounds. The still-running `bounded()` call is not
+ * cancelled (nothing here can cancel already-started work); if it later
+ * genuinely outlives `pullTimeoutMs`, it still records, correctly, on its own
+ * clock.
+ */
+async function boundedLspCall(call, deps) {
+    if (deps.signal?.aborted)
+        return undefined;
+    // #2504 review round 4 (F2): the loop's wall budget bounds THIS trip too. A
+    // round trip that starts with 5 ms of budget left may not run for 10 s just
+    // because the per-call timeout says so -- that is how one file held the
+    // awaited hook for minutes past a spent batch budget.
+    const remainingMs = deps.deadlineAt !== undefined ? deps.deadlineAt - Date.now() : undefined;
+    // Returned BEFORE `bounded()` rather than handed to it as a zero budget: a
+    // trip that never started did not exceed anything, and recording it as an
+    // exceedance would attribute the loop's spent budget to whichever call
+    // happened to be next.
+    if (remainingMs !== undefined && remainingMs <= 0)
+        return undefined;
+    const inner = bounded(call().then((value) => ({ value })), {
+        // Always the FULL per-trip budget -- never clamped to the loop's own
+        // residual. The residual is enforced below, off the ledger.
+        ms: deps.pullTimeoutMs,
+        // Optional for the in-band caller; `bounded()` reads a missing signal
+        // as one that never aborts, so the deadline half stays live.
+        signal: deps.signal,
+        // From the deps, never a literal: the in-band and deferred loops must
+        // key separately (#2557 review F3).
+        hook: deps.site.hook,
+        label: deps.site.label,
+    });
+    const boxed = deps.deadlineAt !== undefined
+        ? await withDeadline(inner, {
+            deadlineAt: deps.deadlineAt,
+            onTimeout: "undefined",
+        })
+        : await inner;
+    // Boxed because an LSP pull legitimately resolves `undefined` (no
+    // diagnostics for this file), which must stay distinguishable from a bound
+    // firing even though both currently mean "not checked" to the caller.
+    return boxed?.value;
+}
+/** Positive finite bound, else the default. Guards NaN from env/config. */
+function boundedNumber(value, fallback) {
+    return value !== undefined && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+}
 export async function buildActionableWarningsReport(args) {
     const cwd = path.resolve(args.cwd);
     const records = [...args.dispatchWarnings];
     const lspService = getLSPService();
+    // #2504 review round 5 (F2): when each file's LSP observation FINISHED,
+    // keyed by normalized path. assembleReport used to stamp every entry with
+    // one `new Date()` taken at ASSEMBLY -- which for the deferred loop is the
+    // loop's END, so a file read 60 s and 24 files ago claimed to be
+    // milliseconds old. applyDeltaFreshnessGate compares that stamp against the
+    // file's mtime to catch an out-of-band edit made after the observation, and
+    // a stamp that late hands it a window which has already closed. Shared with
+    // the deferred closure below, so the in-band entries it carries over keep
+    // the stamps their own pass gave them.
+    const observedAtByPath = new Map();
+    // The conservative stand-in for an entry no LSP pull ever touched (a
+    // dispatch-origin warning): the moment this build began. Never LATER than
+    // the observation it stands in for, which is the direction that matters --
+    // an over-old stamp costs a line number, an over-new one leaks a stale one.
+    const buildStartedAt = new Date().toISOString();
     logActionableWarningsEvent({
         event: "report_started",
         sessionId: args.sessionId,
@@ -321,8 +475,27 @@ export async function buildActionableWarningsReport(args) {
         },
     });
     if (args.includeLspCodeActions) {
+        const fileCap = Math.floor(boundedNumber(args.lspFileCap, ACTIONABLE_WARNINGS_LSP_FILE_CAP));
+        const budgetMs = boundedNumber(args.lspBudgetMs, ACTIONABLE_WARNINGS_LSP_BUDGET_MS);
+        // #2504 (1) project-root filter. The worklist this loop is handed had
+        // accumulated paths from two other agents' scratchpads, `~/.claude/plans`
+        // and `~/.plegma/work` — none of which belong to an LSP client rooted at
+        // this project. Rejected before any file read.
+        const eligible = [];
+        let outsideRoot = 0;
         for (const file of args.files) {
             const filePath = path.resolve(cwd, file);
+            if (normalizeMapKey(filePath) === normalizeMapKey(cwd) ||
+                !isUnderDir(filePath, cwd)) {
+                outsideRoot++;
+                logActionableWarningsEvent({
+                    event: "lsp_file_skipped",
+                    sessionId: args.sessionId,
+                    filePath,
+                    metadata: { reason: "outside_project_root" },
+                });
+                continue;
+            }
             if (!lspService.supportsLSP(filePath)) {
                 logActionableWarningsEvent({
                     event: "lsp_file_skipped",
@@ -332,88 +505,400 @@ export async function buildActionableWarningsReport(args) {
                 });
                 continue;
             }
-            // Reuse the cache primed by the dispatch pipeline's touchFile earlier in
-            // this turn — but only when it is verified current. A second open+wait
-            // here costs ~1 s/file with the LSP cold, so we pass the hash of the
-            // current file bytes: getLastKnownDiagnostics returns the entry only if
-            // it was primed for the SAME content, so a previous turn's diagnostics
-            // are never served as current. On any miss (no entry, content drift, or
-            // an entry written without content) we fall through to a fresh read.
-            let diags;
-            let lspSource = "cache";
-            const currentContent = fs.existsSync(filePath)
+            eligible.push(filePath);
+        }
+        if (outsideRoot > 0) {
+            args.dbg?.(`actionable_warnings: skipped ${outsideRoot} file(s) outside the project root`);
+        }
+        // #2504 (2) file cap.
+        const capped = eligible.slice(0, fileCap);
+        if (capped.length < eligible.length) {
+            recordDegradationOnce({
+                kind: "actionable-warnings-cap",
+                subject: `${cwd}:file-cap`,
+                reason: `LSP enrichment capped at ${fileCap} file(s); ${eligible.length - capped.length} modified file(s) were not checked for code actions this turn`,
+            });
+        }
+        // Resolve every file's cache state BEFORE doing any LSP work. This is a
+        // read + a sha256 per file (sub-millisecond) and it is what tells us
+        // whether the turn primed the cache at all — the difference between a
+        // loop that costs nothing and one that costs ~880 ms per file.
+        const primed = [];
+        const cold = [];
+        for (const filePath of capped) {
+            // Reuse the cache primed by the dispatch pipeline's touchFile earlier
+            // in this turn — but only when it is verified current. A second
+            // open+wait here costs ~1 s/file with the LSP cold, so we pass the
+            // hash of the current file bytes: getLastKnownDiagnostics returns the
+            // entry only if it was primed for the SAME content, so a previous
+            // turn's diagnostics are never served as current. On any miss (no
+            // entry, content drift, or an entry written without content) the file
+            // needs a fresh read.
+            const content = fs.existsSync(filePath)
                 ? fs.readFileSync(filePath, "utf-8")
                 : undefined;
-            const contentHash = currentContent !== undefined
-                ? createHash("sha256").update(currentContent).digest("hex")
+            const contentHash = content !== undefined
+                ? createHash("sha256").update(content).digest("hex")
                 : undefined;
             const cached = contentHash !== undefined
                 ? lspService.getLastKnownDiagnostics(filePath, contentHash)
                 : undefined;
-            if (cached !== undefined) {
-                diags = cached;
+            (cached !== undefined ? primed : cold).push({
+                filePath,
+                content,
+                cached,
+            });
+        }
+        // #2504 (3) wall budget, raced against the turn's abort signal. Both
+        // bounds, per AGENTS.md: neither a cap nor a deadline alone stops a
+        // cancelled turn from paying for work nobody is waiting for.
+        const deadline = Date.now() + budgetMs;
+        const exhausted = () => args.signal?.aborted === true || Date.now() >= deadline;
+        const pullTimeoutMs = boundedNumber(args.lspPullTimeoutMs, ACTIONABLE_WARNINGS_LSP_PULL_TIMEOUT_MS);
+        // #2504 review round 2 (F3): the in-band loop gets the same per-call
+        // bound and the same once-resolved service as the deferred one — the
+        // deferral must not be the only path that is bounded.
+        const inBandDeps = {
+            lspService,
+            pullTimeoutMs,
+            // #2504 review round 4 (F2). This is the AWAITED hook: the batch
+            // budget has to bound what happens INSIDE a file, not only how many
+            // files get started.
+            deadlineAt: deadline,
+            signal: args.signal,
+            // This loop IS on the awaited hook, so its exceedances are turn_end's.
+            site: { hook: "turn_end", label: "lspEnrichmentRoundTrip" },
+        };
+        let unchecked = 0;
+        const runInBand = async (targets) => {
+            for (const target of targets) {
+                if (exhausted()) {
+                    unchecked += targets.length - targets.indexOf(target);
+                    break;
+                }
+                records.push(...(await enrichFileFromLsp(cwd, args, target, inBandDeps)));
+                // #2504 review round 5 (F2): stamped when THIS file's pull
+                // returned, not when the report is assembled.
+                observedAtByPath.set(normalizeMapKey(target.filePath), new Date().toISOString());
+            }
+        };
+        // Cached files first: they are free, and whether ANY of them exist is
+        // what decides the cold set's fate below.
+        await runInBand(primed);
+        // #2504 (4) cold-cache deferral. When the turn primed nothing, every
+        // remaining file is a full open + diagnostic wait; that whole loop is
+        // what held the terminal for 187 s. It still runs — off the awaited
+        // hook — and lands in the same `actionable-warnings` cache the in-band
+        // report goes to, so the findings reach the agent by the same channel,
+        // one turn later at worst.
+        if (cold.length > 0 && primed.length === 0) {
+            // #2504 review round 2 (F3). The pre-fix loop captured
+            // `args.signal` — the COMPLETED turn's `ctx.signal`, which
+            // `index.ts` clears from the ambient slot in its `finally`, so it
+            // could never fire. `armDeferredLspWork` returns the module slot's
+            // live signal; `resetLSPService` fires it, which is how
+            // session_shutdown, session_start and the idle reset all reach this
+            // loop. The turn's own signal is still folded in so a genuine
+            // mid-turn abort counts.
+            //
+            // #2504 review round 3 (F-A(d)): it returns `undefined` when an
+            // EARLIER deferral still holds the slot. The incumbent wins — see
+            // `armDeferredLspWork` — and this turn states its loss instead of
+            // cancelling a loop that is about to publish.
+            const deferredSignal = armDeferredLspWork();
+            if (deferredSignal === undefined) {
+                incrementDegradationCount({
+                    kind: "actionable-warnings-cap",
+                    subject: `${cwd}:deferral-declined`,
+                    // #2504 review round 4 (F1): the old wording ended "rather than
+                    // cancel it", which asserted a preservation that did not
+                    // happen -- the incumbent's report was then discarded whole by
+                    // the persisted-newer guard. With the per-file merge below it
+                    // is true, so it now says exactly WHAT survives and what does
+                    // not.
+                    reason: `an earlier deferred LSP pull is still running; ${cold.length} file(s) went unchecked for code actions this turn. What IS preserved is the incumbent loop's work: when it lands, its per-file entries are merged into whatever report is persisted then, for every file whose fileSeq has not advanced. This turn's own cold files are the loss, and nothing re-derives them -- the next report is a delta over a different file set`,
+                });
+                logActionableWarningsEvent({
+                    event: "lsp_pull_deferral_declined",
+                    sessionId: args.sessionId,
+                    metadata: { turnIndex: args.turnIndex, files: cold.length },
+                });
+                args.dbg?.(`actionable_warnings: an earlier deferred LSP pull still holds the slot — skipping ${cold.length} fresh pull(s) this turn`);
             }
             else {
-                try {
-                    if (currentContent)
-                        await lspService.openFile(filePath, currentContent);
-                    diags = await lspService.getDiagnostics(filePath);
-                    lspSource = "fresh";
-                }
-                catch (err) {
-                    args.dbg?.(`actionable_warnings: LSP diagnostics failed for ${filePath}: ${err}`);
+                const carried = [...records];
+                const deferredArgs = args;
+                const loopSignal = combineAbortSignals(args.signal, deferredSignal) ?? deferredSignal;
+                const deferredDeps = {
+                    lspService,
+                    pullTimeoutMs,
+                    signal: loopSignal,
+                    // OFF the hook by construction: this loop is the answer to
+                    // turn_end's budget, not a spender of it, and it runs on its
+                    // own ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS deadline. Charging
+                    // its exceedances to `turn_end` would make the hook look over
+                    // budget for having correctly deferred the work (#2557 F3).
+                    site: {
+                        hook: "off_hook",
+                        label: "deferredLspEnrichmentRoundTrip",
+                    },
+                };
+                const deferredWork = (async () => {
+                    // Yield a full macrotask first. Without this the loop would run
+                    // its first open+pull inside the awaited call's own microtask
+                    // drain — "deferred" only on paper, and still on the hook.
+                    await new Promise((resolve) => setTimeout(resolve, 0));
+                    const deferredRecords = [...carried];
+                    const deferredDeadline = Date.now() + ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS;
+                    // #2504 review round 4 (F2): set here, not at construction --
+                    // the deferred loop's budget starts when the loop does, one
+                    // macrotask after these deps were built.
+                    deferredDeps.deadlineAt = deferredDeadline;
+                    let deferredUnchecked = 0;
+                    let abortedMidLoop = false;
+                    for (const target of cold) {
+                        if (loopSignal.aborted || Date.now() >= deferredDeadline) {
+                            abortedMidLoop = loopSignal.aborted;
+                            deferredUnchecked += cold.length - cold.indexOf(target);
+                            break;
+                        }
+                        deferredRecords.push(...(await enrichFileFromLsp(cwd, deferredArgs, target, deferredDeps)));
+                        // #2504 review round 5 (F2). This is the loop the defect
+                        // was about: it can run for a minute, and one stamp taken
+                        // at its end described all of it.
+                        observedAtByPath.set(normalizeMapKey(target.filePath), new Date().toISOString());
+                    }
+                    if (deferredUnchecked > 0) {
+                        recordDegradationOnce({
+                            kind: "actionable-warnings-cap",
+                            subject: `${cwd}:deferred-budget`,
+                            reason: `deferred LSP enrichment stopped early; ${deferredUnchecked} file(s) were not checked for code actions`,
+                        });
+                    }
+                    // An ABORTED loop delivers nothing (#2504 review round 2, F3).
+                    // The service it was reading is gone — session_shutdown,
+                    // session_start, or the idle reset retired it — so its partial
+                    // record set describes nothing current, and publishing it would
+                    // be exactly the stale-clobber F2 guards against on the other
+                    // side.
+                    if (abortedMidLoop || loopSignal.aborted) {
+                        logActionableWarningsEvent({
+                            event: "lsp_pull_aborted",
+                            sessionId: deferredArgs.sessionId,
+                            metadata: {
+                                turnIndex: deferredArgs.turnIndex,
+                                unchecked: deferredUnchecked,
+                            },
+                        });
+                        return;
+                    }
+                    deferredArgs.onDeferredReport?.(assembleReport(cwd, deferredArgs, deferredRecords, {
+                        observedAtByPath,
+                        fallbackObservedAt: buildStartedAt,
+                    }));
+                })().catch((err) => {
+                    args.dbg?.(`actionable_warnings: deferred LSP pull failed: ${err}`);
+                });
+                registerDeferredLspWork(deferredSignal, deferredWork);
+                logActionableWarningsEvent({
+                    event: "lsp_pull_deferred",
+                    sessionId: args.sessionId,
+                    metadata: { turnIndex: args.turnIndex, files: cold.length },
+                });
+                args.dbg?.(`actionable_warnings: no LSP cache primed this turn — deferring ${cold.length} fresh pull(s) off the turn_end hook`);
+            }
+        }
+        else {
+            await runInBand(cold);
+        }
+        if (unchecked > 0) {
+            recordDegradationOnce({
+                kind: "actionable-warnings-cap",
+                subject: `${cwd}:wall-budget`,
+                reason: `LSP enrichment hit its ${Math.round(budgetMs)}ms turn budget; ${unchecked} file(s) were not checked for code actions this turn`,
+            });
+        }
+    }
+    return assembleReport(cwd, args, records, {
+        observedAtByPath,
+        fallbackObservedAt: buildStartedAt,
+    });
+}
+/**
+ * Enrich one file's LSP warnings into records. Split out of
+ * `buildActionableWarningsReport` (#2504) so the in-band loop and the deferred
+ * off-hook loop run byte-identical logic — the deferral must not become a
+ * second, drifting copy of the enrichment.
+ */
+async function enrichFileFromLsp(cwd, args, target, deps) {
+    const { lspService } = deps;
+    const { filePath } = target;
+    const out = [];
+    let diags;
+    let lspSource = "cache";
+    if (target.cached !== undefined) {
+        diags = target.cached;
+    }
+    else {
+        // #2504 review round 2 (F3): never OPEN a file once the loop has been
+        // signalled. The checks inside `boundedLspCall` cover the round trips;
+        // this one covers the decision to touch the file at all, which is what
+        // makes a session_shutdown landing mid-loop a no-op rather than one
+        // more document handed to a service that is being torn down.
+        if (deps.signal?.aborted) {
+            logActionableWarningsEvent({
+                event: "lsp_file_skipped",
+                sessionId: args.sessionId,
+                filePath,
+                metadata: { reason: "aborted" },
+            });
+            return out;
+        }
+        try {
+            if (target.content) {
+                // #2504 review round 3 (F-B), the #240 shape. `openFile` resolves
+                // `void`, so the bounded call cannot distinguish success from
+                // either bound winning unless the success path returns a value of
+                // its own. Round 2 discarded the result entirely: a 10 s timeout
+                // or an abort "succeeded" silently, and the pull below then asked
+                // the server about a document it had never received. The `[]` that
+                // answers means UNKNOWN, but it was recorded
+                // `lsp_file_checked lspSource:"fresh"` — a failed pull read as
+                // clean, which is precisely what the comment on the pull forbids.
+                const opened = await boundedLspCall(async () => {
+                    await lspService.openFile(filePath, target.content);
+                    return true;
+                }, deps);
+                if (opened === undefined) {
                     logActionableWarningsEvent({
                         event: "lsp_file_skipped",
                         sessionId: args.sessionId,
                         filePath,
-                        metadata: { reason: "lsp_error", error: String(err) },
+                        metadata: {
+                            reason: deps.signal?.aborted ? "aborted" : "open_timeout",
+                            pullTimeoutMs: deps.pullTimeoutMs,
+                        },
                     });
-                    continue;
+                    return out;
                 }
             }
-            const ranges = args.modifiedRangesByFile.get(normalizeMapKey(filePath)) ?? [];
-            const diagsWarning = diags.filter((d) => d.severity === 2);
-            let deltaFiltered = 0;
-            let enriched = 0;
-            for (const diag of diagsWarning) {
-                const line = diag.range.start.line + 1;
-                if (args.deltaOnly !== false && !lineInModifiedRanges(line, ranges)) {
-                    deltaFiltered++;
-                    continue;
-                }
-                const record = recordFromLspDiagnostic(diag, filePath, cwd);
-                try {
-                    const actions = await lspService.codeAction(filePath, diag.range.start.line, diag.range.start.character, diag.range.end.line, diag.range.end.character);
-                    record.actions = actions.map(serializeAction).slice(0, 5);
-                }
-                catch (err) {
-                    args.dbg?.(`actionable_warnings: LSP codeAction failed for ${filePath}: ${err}`);
-                }
-                if (record.actions.length > 0) {
-                    records.push(record);
-                    enriched++;
-                }
+            const pulled = await boundedLspCall(() => lspService.getDiagnostics(filePath), deps);
+            if (pulled === undefined) {
+                // Either bound won. A failed pull is NEVER read as clean (#240):
+                // the file is reported unchecked and contributes no records.
+                logActionableWarningsEvent({
+                    event: "lsp_file_skipped",
+                    sessionId: args.sessionId,
+                    filePath,
+                    metadata: {
+                        reason: deps.signal?.aborted ? "aborted" : "pull_timeout",
+                        pullTimeoutMs: deps.pullTimeoutMs,
+                    },
+                });
+                return out;
             }
+            diags = pulled;
+            lspSource = "fresh";
+        }
+        catch (err) {
+            args.dbg?.(`actionable_warnings: LSP diagnostics failed for ${filePath}: ${err}`);
             logActionableWarningsEvent({
-                event: "lsp_file_checked",
+                event: "lsp_file_skipped",
                 sessionId: args.sessionId,
                 filePath,
-                metadata: {
-                    diagsTotal: diags.length,
-                    diagsWarning: diagsWarning.length,
-                    deltaFiltered,
-                    enriched,
-                    modifiedRangesCount: ranges.length,
-                    lspSource,
-                },
+                metadata: { reason: "lsp_error", error: String(err) },
             });
+            return out;
         }
     }
+    const ranges = args.modifiedRangesByFile.get(normalizeMapKey(filePath)) ?? [];
+    const diagsWarning = diags.filter((d) => d.severity === 2);
+    let deltaFiltered = 0;
+    let enriched = 0;
+    let actionPulls = 0;
+    let actionCapped = 0;
+    let budgetStopped = 0;
+    for (const diag of diagsWarning) {
+        // #2504 review round 4 (F2). The wall budget used to be re-checked
+        // BETWEEN files only, so a single file could keep the AWAITED hook for
+        // openFile + getDiagnostics + up to 25 codeAction round trips long after
+        // the batch budget expired. The loop deadline is threaded through deps
+        // and re-read HERE, between round trips: a file already opened still
+        // finishes its cheap work, but it cannot buy more LSP time.
+        if (deps.deadlineAt !== undefined && Date.now() >= deps.deadlineAt) {
+            budgetStopped = diagsWarning.length - diagsWarning.indexOf(diag);
+            break;
+        }
+        const line = diag.range.start.line + 1;
+        if (args.deltaOnly !== false && !lineInModifiedRanges(line, ranges)) {
+            deltaFiltered++;
+            continue;
+        }
+        // #2504 review round 3 (S-2): bound the per-file codeAction fan-out.
+        if (actionPulls >= ACTIONABLE_WARNINGS_MAX_CODE_ACTIONS_PER_FILE) {
+            actionCapped++;
+            continue;
+        }
+        actionPulls++;
+        const record = recordFromLspDiagnostic(diag, filePath, cwd);
+        try {
+            const actions = await boundedLspCall(() => lspService.codeAction(filePath, diag.range.start.line, diag.range.start.character, diag.range.end.line, diag.range.end.character), deps);
+            record.actions = (actions ?? []).map(serializeAction).slice(0, 5);
+        }
+        catch (err) {
+            args.dbg?.(`actionable_warnings: LSP codeAction failed for ${filePath}: ${err}`);
+        }
+        if (record.actions.length > 0) {
+            out.push(record);
+            enriched++;
+        }
+    }
+    if (actionCapped > 0) {
+        incrementDegradationCount({
+            kind: "actionable-warnings-cap",
+            subject: `${cwd}:code-action-fanout`,
+            // #2504 review round 4 (S-2): "reported without fix actions" was
+            // wrong in both halves. A capped warning is skipped BEFORE its record
+            // is built, and a record with no action is dropped below anyway, so
+            // it is not reported at all -- it never reaches the agent on this
+            // channel.
+            reason: `a file exceeded the ${ACTIONABLE_WARNINGS_MAX_CODE_ACTIONS_PER_FILE}-warning code-action cap; ${actionCapped} warning(s) in ${toRunnerDisplayPath(cwd, filePath)} were NOT reported this turn`,
+        });
+    }
+    if (budgetStopped > 0) {
+        incrementDegradationCount({
+            kind: "actionable-warnings-cap",
+            subject: `${cwd}:in-file-budget`,
+            reason: `the LSP enrichment wall budget expired part-way through a file; ${budgetStopped} warning(s) in ${toRunnerDisplayPath(cwd, filePath)} were NOT checked for fix actions`,
+        });
+    }
+    logActionableWarningsEvent({
+        event: "lsp_file_checked",
+        sessionId: args.sessionId,
+        filePath,
+        metadata: {
+            diagsTotal: diags.length,
+            diagsWarning: diagsWarning.length,
+            deltaFiltered,
+            enriched,
+            actionCapped,
+            budgetStopped,
+            modifiedRangesCount: ranges.length,
+            lspSource,
+        },
+    });
+    return out;
+}
+/**
+ * Assemble the report from a record set. Called once for the in-band report
+ * and again, off-hook, when the deferred fresh pull completes (#2504).
+ */
+function assembleReport(cwd, args, records, stamps) {
     const merged = mergeWarnings(records);
     updateWarningState(cwd, merged);
     // legacyId is #1816 migration bookkeeping for updateWarningState above —
     // strip it before the report leaves this function, so it never lands in
-    // the `.pi-lens/cache/actionable-warnings.json` cache file or any
+    // the `<project-data-dir>/cache/actionable-warnings.json` cache file or any
     // agent-facing rendering of a warning record.
     const reportWarnings = merged.map(({ legacyId: _legacyId, ...rest }) => rest);
     const byFile = new Map();
@@ -422,36 +907,32 @@ export async function buildActionableWarningsReport(args) {
         arr.push(warning);
         byFile.set(warning.filePath, arr);
     }
+    // #2504 review round 4 (F1): every entry carries the moment it was
+    // assembled, so a report that later absorbs a deferred pull's entries can
+    // still age each half honestly. For a report built in one pass they are all
+    // the report stamp.
+    const generatedAt = new Date().toISOString();
     const files = [...byFile.entries()].map(([filePath, warnings]) => ({
         filePath,
         displayPath: toRunnerDisplayPath(cwd, filePath),
         fileSeq: args.fileSeqByPath?.get(normalizeMapKey(filePath)),
+        // #2504 review round 5 (F2): the moment THIS file was observed. The
+        // report-level stamp remains the assembly moment and is only the
+        // last-resort fallback, for a caller that supplied no observations
+        // at all.
+        generatedAt: stamps?.observedAtByPath.get(normalizeMapKey(filePath)) ??
+            stamps?.fallbackObservedAt ??
+            generatedAt,
         warnings,
     }));
-    const allActions = merged.flatMap((warning) => warning.actions);
-    const unsuppressed = merged.filter((warning) => !warning.suppressed);
-    const countTier = (tier) => unsuppressed.filter((warning) => warning.severity === tier).length;
-    const summary = {
-        warnings: merged.length,
-        unsuppressed: unsuppressed.length,
-        byTier: {
-            warning: countTier("warning"),
-            info: countTier("info"),
-            hint: countTier("hint"),
-        },
-        suppressed: merged.filter((warning) => warning.suppressed).length,
-        files: files.length,
-        actions: allActions.length,
-        autoFixEligible: allActions.filter((action) => action.autoFixEligible)
-            .length,
-    };
+    const summary = summarizeReportFiles(files);
     logActionableWarningsEvent({
         event: "report_complete",
         sessionId: args.sessionId,
         metadata: { turnIndex: args.turnIndex, summary },
     });
     return {
-        generatedAt: new Date().toISOString(),
+        generatedAt,
         scope: "turn_delta",
         sessionId: args.sessionId,
         turnIndex: args.turnIndex,
@@ -463,9 +944,356 @@ export async function buildActionableWarningsReport(args) {
         summary,
     };
 }
-export function writeActionableWarningsReport(cacheManager, cwd, report) {
+/**
+ * The report summary, derived from the per-file entries.
+ *
+ * ONE derivation (#2504 review round 4, F1): a merged report's summary has to
+ * describe the merged file set, and a second hand-rolled tally beside
+ * assembleReport's would be the mirrored-registry defect AGENTS.md names.
+ * Every warning belongs to exactly one file entry, so summing over entries and
+ * summing over the flat record list give the same numbers.
+ */
+function summarizeReportFiles(files) {
+    const warnings = files.flatMap((file) => file.warnings);
+    const unsuppressed = warnings.filter((warning) => !warning.suppressed);
+    const allActions = warnings.flatMap((warning) => warning.actions);
+    const countTier = (tier) => unsuppressed.filter((warning) => warning.severity === tier).length;
+    return {
+        warnings: warnings.length,
+        unsuppressed: unsuppressed.length,
+        byTier: {
+            warning: countTier("warning"),
+            info: countTier("info"),
+            hint: countTier("hint"),
+        },
+        suppressed: warnings.filter((warning) => warning.suppressed).length,
+        files: files.length,
+        actions: allActions.length,
+        autoFixEligible: allActions.filter((action) => action.autoFixEligible)
+            .length,
+    };
+}
+/**
+ * The ONE place an actionable-warnings report reaches disk.
+ *
+ * Deliberately NOT exported (#2504 review round 5, F1). Two writers used to
+ * publish to this key: the in-band turn_end report, which OVERWROTE blindly,
+ * and the deferred off-hook report, which read-modify-wrote. A deferred merge
+ * that landed anywhere inside turn N+1's handleTurnEnd -- the cascade settle,
+ * knip, madge, the test batch, the in-band LSP enrichment; a window seconds
+ * wide, measured at 607 ms in the reviewer's trace -- was erased by that
+ * turn's blind write, and the findings the whole deferral exists to deliver
+ * were gone with it. A blind writer and a merging writer on one key can only
+ * ever be a race. There is now one publisher and it always merges; the private
+ * scope is what keeps it that way.
+ */
+function writeActionableWarningsReport(cacheManager, cwd, report) {
     cacheManager.writeCache("actionable-warnings", report, cwd);
 }
+/**
+ * Merge a report about to be published into whatever is already persisted,
+ * PER FILE.
+ *
+ * #2504 review round 4 (F1) established the shape: a report is a MAP of
+ * per-file entries, each stamped with that file's fileSeq and its own
+ * observation time, so ordering belongs PER FILE and not to the report as a
+ * whole. Rounds 2 and 3 ordered whole reports -- publish, or discard on a
+ * newer turnIndex/projectSeqEnd -- and that composed with incumbent-wins into
+ * "publish nothing".
+ *
+ * #2504 review round 5 (F1) generalized it to BOTH publishers, because the
+ * in-band write was still blind and erased a deferred merge that landed
+ * mid-turn. The two directions are asymmetric and the asymmetry is the whole
+ * design:
+ *
+ *  - A DEFERRED publish carries the OLDER observation. Everything persisted is
+ *    newer and is kept unconditionally; the deferred entries upsert into it
+ *    wherever their file has not moved.
+ *  - An IN-BAND publish carries the NEWER observation. It is this turn's own
+ *    report, and its identity (turnIndex, projectSeq window, deltaOnly) is
+ *    published untouched. From the persisted report it carries forward ONLY
+ *    entries a deferral produced -- the scope guard, see
+ *    {@link ActionableWarningsReportFile.origin}. Carrying everything would
+ *    accumulate every prior turn's findings into a report whose scope field
+ *    says "turn_delta"; carrying nothing is the F1 defect.
+ *
+ * Where both halves hold a file the warnings are UNIONED through mergeWarnings
+ * (the same de-duplicating merge the dispatch/LSP union already uses), so a
+ * newer entry is never REPLACED by an older one -- it only gains what the
+ * older one found -- and the merged entry is aged by the OLDER of the two
+ * stamps, because it now holds both observations.
+ *
+ * Exported because the merge, not the write, is what has to be pinned: a test
+ * can hand it two reports and read the ordering decision directly.
+ */
+export function mergeActionableWarningsReports(args) {
+    const { persisted, incoming, origin } = args;
+    const deferredPublish = origin === "deferred";
+    // The newer half wins identity and fileSeq; the older half is folded in.
+    // #2504 review round 6 (F1) removed a same-sessionId gate here, reasoning
+    // that the fileSeq equality check below subsumed it: pi's telemetry
+    // sessionId is STABLE across a quit->resume (setSessionLifecycle pins it,
+    // runtime-coordinator.ts:677-682), but resetForSession clears the live
+    // _fileSeq map for the new process, so a resumed process's getFileSeq
+    // answers 0 for a file a PRE-restart deferral had recorded at a nonzero
+    // seq -- the sessionId gate could not see that (same id, stale data), the
+    // equality check could.
+    // #2504 review round 7 (F4): that reasoning breaks at fileSeq 0. A file
+    // THIS process has never touched also answers getFileSeq 0 (a fresh
+    // RuntimeCoordinator's map starts empty), and an entry a DIFFERENT
+    // process stamped at fileSeq 0 can reach the persisted report entirely
+    // unrelated to a resume: `mcp/analyze.ts` and `mcp/session.ts` register
+    // modified ranges through their OWN CacheManager, which never bumps the
+    // extension runtime's `_fileSeq` map, so an MCP-touched file can persist
+    // at seq 0 under a foreign sessionId. `0 !== 0` then reads FALSE and the
+    // entry is carried as if it were this session's own unmoved file. The
+    // sessionId gate is restored ALONGSIDE the equality check, not instead of
+    // it: equality alone catches the resume-reset case (same session, seq
+    // forcibly reset to 0), the sessionId gate alone catches the
+    // foreign-session case (different session, seq coincidentally equal,
+    // often both 0) -- neither subsumes the other.
+    const sessionMismatch = !deferredPublish &&
+        persisted?.sessionId !== undefined &&
+        persisted.sessionId !== incoming.sessionId;
+    const newerHalf = deferredPublish ? (persisted?.files ?? []) : incoming.files;
+    const olderHalf = deferredPublish ? incoming.files : (persisted?.files ?? []);
+    const newerReport = deferredPublish ? persisted : incoming;
+    const olderReport = deferredPublish ? incoming : persisted;
+    const byPath = new Map();
+    for (const entry of newerHalf) {
+        byPath.set(normalizeMapKey(entry.filePath), entry);
+    }
+    const droppedFiles = [];
+    let mergedFiles = 0;
+    for (const entry of olderHalf) {
+        // The scope guard. An in-band publish exists to add THIS turn's
+        // findings; the only thing it owes the persisted report is the deferred
+        // work that would otherwise be erased between the read and the write.
+        // #2504 review round 6 (b): the marker spend (below) means an entry
+        // carried once and then dropped here on the NEXT in-band publish is
+        // expected, not a fault -- traced to dbg (informational) rather than
+        // the degradation ledger (which is for loss the agent didn't cause).
+        if (!deferredPublish && entry.origin !== "deferred") {
+            args.dbg?.(`actionable_warnings: in-band publish dropped ${entry.displayPath || entry.filePath} -- its carry-forward window (from an earlier deferred publish) already closed`);
+            continue;
+        }
+        const key = normalizeMapKey(entry.filePath);
+        const incumbent = byPath.get(key);
+        const liveBaseline = args.getFileSeq !== undefined;
+        const baselineSeq = args.getFileSeq?.(entry.filePath) ?? incumbent?.fileSeq;
+        // #2504 review round 6 (F1): the in-band carry-forward path, when a
+        // LIVE baseline is available, requires EXACT equality rather than
+        // "baseline advanced past it". An unmoved file's live fileSeq always
+        // equals its persisted entry's recorded fileSeq; any mismatch --
+        // higher (edited since) OR lower (a resumed process whose fileSeq map
+        // was cleared, #2504 r6 F1) -- means the entry no longer describes
+        // what is on disk now. The deferred-publish path keeps the coarser
+        // ">" check: a live process's own fileSeq only ever advances, so
+        // "advanced past it" and "mismatched" agree there, and the deferred
+        // loop's entries can legitimately equal a JUST-bumped incumbent seq
+        // it upserts into.
+        const stale = !deferredPublish && liveBaseline
+            ? sessionMismatch ||
+                (typeof entry.fileSeq === "number" && baselineSeq !== entry.fileSeq)
+            : typeof baselineSeq === "number" &&
+                typeof entry.fileSeq === "number" &&
+                baselineSeq > entry.fileSeq;
+        if (stale) {
+            droppedFiles.push(entry.displayPath || entry.filePath);
+            continue;
+        }
+        mergedFiles++;
+        const merged = incumbent
+            ? {
+                ...incumbent,
+                fileSeq: incumbent.fileSeq ?? entry.fileSeq,
+                generatedAt: olderStamp(incumbent.generatedAt ?? newerReport?.generatedAt, entry.generatedAt ?? olderReport?.generatedAt),
+                warnings: mergeWarnings([...incumbent.warnings, ...entry.warnings]),
+            }
+            : { ...entry };
+        if (deferredPublish) {
+            // Mark it, so the next in-band publish carries it forward across the
+            // window in which it would otherwise be overwritten.
+            merged.origin = "deferred";
+        }
+        else {
+            // Carried forward exactly once: the marker is spent here.
+            merged.origin = undefined;
+        }
+        byPath.set(key, merged);
+    }
+    const files = [...byPath.values()];
+    if (!deferredPublish) {
+        // This turn's report, with the rescued entries folded in. Its identity
+        // is published untouched: a carried entry's provenance lives ON the
+        // entry (its own fileSeq and generatedAt), which is exactly why round 4
+        // moved those fields there, and widening turnIndex/projectSeqStart to
+        // span the older half would make the report claim a window it never
+        // observed.
+        return {
+            report: { ...incoming, files, summary: summarizeReportFiles(files) },
+            mergedFiles,
+            droppedFiles,
+            // sessionMismatch is a single flag for the whole call, not per-entry:
+            // once true, every stale check above is forced true by the `||`, so
+            // EITHER every drop in this batch is a session-boundary drop, OR none
+            // are (droppedFiles is then purely fileSeq-mismatch drops).
+            droppedForSessionMismatch: sessionMismatch && droppedFiles.length > 0,
+        };
+    }
+    const base = persisted ?? incoming;
+    return {
+        report: {
+            ...base,
+            // The report-level stamp is only the fallback for entries with none
+            // of their own (a cache file from an older build), so it takes the
+            // NEWER of the two; per-entry stamps carry the real ages.
+            generatedAt: newerStamp(persisted?.generatedAt, incoming.generatedAt) ??
+                base.generatedAt,
+            turnIndex: Math.max(base.turnIndex, incoming.turnIndex),
+            projectSeqStart: minDefined(persisted?.projectSeqStart, incoming.projectSeqStart),
+            // max, so a merged report never claims to be fresher OR staler than
+            // the newest part it holds. checkActionableWarningsReportFresh still
+            // demands exact equality with the live projectSeq and re-checks every
+            // entry's fileSeq, so this widens nothing.
+            projectSeqEnd: maxDefined(persisted?.projectSeqEnd, incoming.projectSeqEnd),
+            includeLspCodeActions: base.includeLspCodeActions || incoming.includeLspCodeActions,
+            files,
+            summary: summarizeReportFiles(files),
+        },
+        mergedFiles,
+        droppedFiles,
+        // The deferred-publish path never sets sessionMismatch (gated by
+        // `!deferredPublish` above), so its drops are always fileSeq-mismatch.
+        droppedForSessionMismatch: false,
+    };
+}
+/**
+ * Publish an actionable-warnings report: read what is persisted, merge per
+ * file, write. THE choke point (#2504 review round 5, F1) -- every publisher
+ * goes through it, so no writer can clobber another's entries.
+ *
+ * The read and the merge and the write are one synchronous block, which is
+ * what makes this safe against the deferred callback: node runs no other
+ * continuation between them, so the only interleaving left is publish-vs-
+ * publish, and that is exactly what the merge resolves.
+ */
+export function publishActionableWarningsReport(cacheManager, cwd, report, opts = {}) {
+    const origin = opts.origin ?? "in-band";
+    // No TTL: "what is already on disk" is a question about ORDERING, not
+    // freshness, so an entry old enough to have expired for a CONSUMER still
+    // has to be merged into rather than clobbered.
+    const persisted = cacheManager.readCache("actionable-warnings", cwd, Number.MAX_SAFE_INTEGER)?.data;
+    const merged = mergeActionableWarningsReports({
+        persisted,
+        incoming: report,
+        origin,
+        getFileSeq: opts.getFileSeq,
+        dbg: opts.dbg,
+    });
+    writeActionableWarningsReport(cacheManager, cwd, merged.report);
+    // The history records what THIS publish OBSERVED, not what it carried: a
+    // merged-in entry is already on the NDJSON from the publish that produced
+    // it, and appending the merged report would duplicate every carried row on
+    // every subsequent turn.
+    appendActionableWarningsHistory(cwd, report);
+    if (merged.mergedFiles > 0) {
+        opts.dbg?.(`actionable_warnings: ${origin} publish merged ${merged.mergedFiles} persisted file entry/entries`);
+    }
+    // #2504 review round 7 (F5): the deferred origin's own loss is already
+    // recorded by {@link writeDeferredActionableWarningsReport}, which calls
+    // through here first. The IN-BAND origin has the same shape of loss --
+    // this turn's own publish carries a carried-forward deferred entry
+    // forward only while its file has not moved, and a file that moved
+    // between the deferral and this publish is dropped -- but nothing counted
+    // or traced it: only the benign, expected scope-guard spend (an entry
+    // whose carry-forward window already closed) got a dbg line. Same
+    // accounting, mirrored for the origin that was silent.
+    if (origin === "in-band" && merged.droppedFiles.length > 0) {
+        // #2504 review round 8 (S2): "changed" is only true on the fileSeq-
+        // mismatch path. A foreign sessionId (a resumed process, or a
+        // different session's write) drops the same carried-forward entries
+        // without any file having moved -- name the actual cause instead of
+        // asserting a change that may not have happened.
+        const cause = merged.droppedForSessionMismatch
+            ? "the publish crossed a session boundary (a different session's write, or a resumed process) before this turn's in-band publish could keep them"
+            : "changed before this turn's in-band publish could keep them";
+        incrementDegradationCount({
+            kind: "actionable-warnings-inband-superseded",
+            subject: `${path.resolve(cwd)}:inband-carry-superseded`,
+            reason: `${merged.droppedFiles.length} carried-forward deferred file entry/entries ${cause} (${merged.droppedFiles.slice(0, 3).join(", ")}${merged.droppedFiles.length > 3 ? ", ..." : ""}); their earlier findings are LOST on this channel rather than published against content that has since moved`,
+        });
+        opts.dbg?.(`actionable_warnings: in-band publish dropped ${merged.droppedFiles.length} superseded carried-forward file entry/entries (${merged.droppedFiles.slice(0, 3).join(", ")}${merged.droppedFiles.length > 3 ? ", ..." : ""})`);
+    }
+    return merged;
+}
+/** The earlier of two ISO stamps; either may be missing or unparseable. */
+function olderStamp(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    const at = Date.parse(a);
+    const bt = Date.parse(b);
+    if (!Number.isFinite(at))
+        return b;
+    if (!Number.isFinite(bt))
+        return a;
+    return at <= bt ? a : b;
+}
+/** The later of two ISO stamps; either may be missing or unparseable. */
+function newerStamp(a, b) {
+    const older = olderStamp(a, b);
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return older === a ? b : a;
+}
+function minDefined(a, b) {
+    if (typeof a !== "number")
+        return b;
+    if (typeof b !== "number")
+        return a;
+    return Math.min(a, b);
+}
+function maxDefined(a, b) {
+    if (typeof a !== "number")
+        return b;
+    if (typeof b !== "number")
+        return a;
+    return Math.max(a, b);
+}
+/**
+ * Publish a DEFERRED off-hook report.
+ *
+ * The deferred fresh-pull loop is stamped with the ORIGINATING turn's
+ * turnIndex/projectSeq and may run for up to
+ * ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS -- many turns in a busy session. It
+ * must therefore neither overwrite a newer report nor be thrown away because
+ * one exists; see mergeActionableWarningsReports for why replace-or-discard
+ * could only ever discard. Per-file loss is the only loss left, and it is
+ * recorded rather than silent.
+ *
+ * A thin wrapper over the choke point since #2504 review round 5 (F1). It
+ * exists only to own the degradation record for the per-file loss -- the
+ * "declined the write" branches it used to carry are gone, because a publish
+ * that merges has nothing to decline.
+ */
+export function writeDeferredActionableWarningsReport(args) {
+    const { mergedFiles, droppedFiles } = publishActionableWarningsReport(args.cacheManager, args.cwd, args.report, { origin: "deferred", getFileSeq: args.getFileSeq, dbg: args.dbg });
+    if (droppedFiles.length > 0) {
+        // Bounded and counted: one subject per project, a tally per occurrence.
+        incrementDegradationCount({
+            kind: "actionable-warnings-deferred-superseded",
+            subject: `${path.resolve(args.cwd)}:deferred-file-superseded`,
+            reason: `${droppedFiles.length} file(s) changed while the deferred LSP pull was reading them (${droppedFiles.slice(0, 3).join(", ")}${droppedFiles.length > 3 ? ", ..." : ""}); their warnings are LOST on this channel rather than published against content that has since moved. Every file that did NOT change was merged into the persisted report`,
+        });
+        args.dbg?.(`turn_end: deferred actionable-warnings dropped ${droppedFiles.length} superseded file entry/entries`);
+    }
+    args.dbg?.(`turn_end: deferred actionable-warnings merged ${mergedFiles} file entry/entries into the persisted report`);
+    return { mergedFiles, droppedFiles: droppedFiles.length };
+}
 export function getActionableWarningsHistoryPath(cwd) {
     return path.join(getProjectDataDir(cwd), "actionable-warnings.jsonl");
 }
@@ -677,7 +1505,18 @@ export async function applyConservativeActionableWarningFixes(args) {
     }
     return summary;
 }
-export function formatActionableWarningsAdvisory(report) {
+/**
+ * The turn-end advisory for this report.
+ *
+ * `cwd` is REQUIRED (#2521): the advisory names where the report lives, and
+ * that location is `getProjectDataDir(cwd)`-resolved, not a constant. It was a
+ * hardcoded `.pi-lens/cache/actionable-warnings.json` — correct only for a
+ * project that already had a legacy `.pi-lens/` directory — so in every other
+ * project the agent's `cat` of the advised path failed while the report sat
+ * unread under `~/.pi-lens/projects/<slug>/cache/`. An OPTIONAL `cwd` would
+ * have kept that bug alive behind a default, so callers must pass it.
+ */
+export function formatActionableWarningsAdvisory(report, cwd) {
     if (report.summary.unsuppressed === 0)
         return undefined;
     const files = report.files.filter((file) => file.warnings.some((warning) => !warning.suppressed));
@@ -697,12 +1536,20 @@ export function formatActionableWarningsAdvisory(report) {
     const tierLine = quiet > 0
         ? `${quiet} of those are hint/info tier — style opinions, worth fixing only while you are already in that code.`
         : undefined;
+    // #2521: lead with the TOOL route. `lens_diagnostics mode=delta` reads the
+    // same cache this advisory describes, so an agent never needs to know the
+    // store's layout — which is exactly the knowledge the old hardcoded path
+    // got wrong. The resolved file stays as a named fallback for a human
+    // reading the transcript, rendered through the one helper that cannot
+    // disagree with the writer.
+    const reportPath = displayProjectDataPath(cwd, "cache", "actionable-warnings.json");
     return [
         `🟡 Fixable warnings introduced this turn: ${report.summary.unsuppressed}.${safe}`,
         tierLine,
-        `Details written to .pi-lens/cache/actionable-warnings.json`,
+        "Use lens_diagnostics with mode=delta to inspect these warnings.",
         fileList ? `Files:\n${fileList}${more}` : undefined,
-        "If continuing in these files, read that JSON and resolve warnings that are safe and relevant. Do not apply broad refactors unless requested.",
+        "If continuing in these files, resolve warnings that are safe and relevant. Do not apply broad refactors unless requested.",
+        `Raw report (only if you need the JSON): ${reportPath}`,
     ]
         .filter(Boolean)
         .join("\n");