@herbertgao/pi-extensions 2026.8.7 → 2026.8.8

package/node_modules/pi-lens/dist/clients/review-graph/builder.js

@@ -27,7 +27,9 @@ import { flushReviewGraphLogSync, logReviewGraph, makeReviewGraphBuildMetadata,
 import { getSharedTreeSitterClient } from "../tree-sitter-shared.js";
 import { TreeSitterSymbolExtractor, } from "../tree-sitter-symbol-extractor.js";
 import { withTreeSitterRoot } from "../tree-sitter-shared.js";
+import { incrementDegradationCount } from "../degradation-ledger.js";
 import { resolveGitIdentity } from "./git-identity.js";
+import { formatReviewGraphRevisionDriftNote, } from "./revision-drift.js";
 import { buildSymbolId } from "./symbol-id.js";
 import { clearReviewGraphFileIr, getFreshReviewGraphFileIr, reviewGraphIrContentHash, } from "./shared-extraction-ir.js";
 // v3 (#260): test files are no longer indexed. Bumping the version makes
@@ -92,10 +94,21 @@ const MAIN_KIND_EXTENSIONS = Array.from(MAIN_KINDS).flatMap((kind) => KIND_EXTEN
 export const REVIEW_GRAPH_SOURCE_EXTENSIONS = MAIN_KIND_EXTENSIONS;
 const CHANGED_SYMBOLS_PREFIX = "session.reviewGraph.changedSymbols:";
 const extractorCache = new Map();
-// Per-invocation Promise cache: deduplicates concurrent buildOrUpdateGraph calls
-// for the same (cwd, changedFiles). Cleared at the start of each pipeline
-// invocation. A separate workspace cache below preserves the expensive parsed
-// graph across invocations when source file mtimes/sizes have not changed.
+// IN-FLIGHT Promise cache: deduplicates CONCURRENT buildOrUpdateGraph calls for
+// the same (cwd, changedFiles). A separate workspace cache below preserves the
+// expensive parsed graph across invocations when source file mtimes/sizes have
+// not changed.
+//
+// #1962: an entry lives only while its build is PENDING — `buildOrUpdateGraph`
+// deletes it on settle, success or failure alike. It used to delete only on
+// rejection, so a settled promise for a SKIPPED or COMPLETED build answered
+// every later call for the same key forever. The pipeline's `clearGraphCache()`
+// (pipeline.ts) was the only thing that ever removed it, and the background
+// build project_report kicks off never goes through the pipeline: four
+// project_report calls over 37s produced ONE build_started, while the tool told
+// the agent a retry had been started each time. That is the process-lifetime
+// latch shape from AGENTS.md — dedupe state whose lifetime must be the
+// operation's, not the process's.
 const _buildCache = new Map();
 const _workspaceGraphCache = new Map();
 const REVIEW_GRAPH_MAX_WARM_WORKSPACES = 8;
@@ -117,13 +130,37 @@ function clearWorkspaceGraphTimer(entry) {
         clearTimeout(entry.idleTimer);
     entry.idleTimer = undefined;
 }
+/**
+ * The canonical workspace identity for a `_buildCache` key (#1962 review F2).
+ *
+ * `path.resolve` collapses `.`/`..` segments and anchors a relative path on
+ * every OS; `normalizeMapKey` folds separator and casing, and it does that by
+ * probing the filesystem (`realpathSync.native`) rather than branching on
+ * `process.platform`. Both steps are idempotent, so feeding this an
+ * already-canonical key — which the two read sites below do — returns it
+ * unchanged.
+ */
+function buildCacheWorkspaceKey(cwd) {
+    return normalizeMapKey(path.resolve(cwd));
+}
+/**
+ * The workspace half of an existing `_buildCache` key. `buildCacheKey`
+ * canonicalizes that half at construction, so this is a plain split.
+ */
+function buildCacheKeyWorkspace(buildKey) {
+    const separator = buildKey.indexOf("|");
+    return separator >= 0 ? buildKey.slice(0, separator) : undefined;
+}
 function evictWorkspaceGraph(key, entry) {
     if (_workspaceGraphCache.get(key) !== entry)
         return;
     clearWorkspaceGraphTimer(entry);
+    // `key` is a workspace-cache key; run it through the build-key derivation so
+    // both sides of this comparison are canonical the same way. Idempotent, so
+    // an already-canonical key passes through untouched (#1962 review F2).
+    const buildWorkspace = buildCacheWorkspaceKey(key);
     for (const buildKey of _buildCache.keys()) {
-        const separator = buildKey.indexOf("|");
-        if (separator >= 0 && normalizeMapKey(buildKey.slice(0, separator)) === key) {
+        if (buildCacheKeyWorkspace(buildKey) === buildWorkspace) {
             _buildCache.delete(buildKey);
         }
     }
@@ -254,8 +291,12 @@ export function clearReviewGraphWorkspaceCache(cwd) {
     }
     else {
         const normalized = normalizeMapKey(cwd);
+        // Compare the key's WORKSPACE half only, both sides canonicalized the same
+        // way. The old form normalized the whole key, changed-file list included,
+        // which is neither meaningful nor cheap (#1962 review F2).
+        const buildWorkspace = buildCacheWorkspaceKey(cwd);
         for (const key of _buildCache.keys()) {
-            if (normalizeMapKey(key).startsWith(`${normalized}|`)) {
+            if (buildCacheKeyWorkspace(key) === buildWorkspace) {
                 _buildCache.delete(key);
             }
         }
@@ -440,8 +481,11 @@ export function getCachedReviewGraph(cwd) {
     // skip the disk read. loadPersistedGraph already rebuilt the indexes.
     // #300: this read is BLIND — nothing downstream content-verifies it, so a
     // stamped snapshot from a different HEAD/worktree must be dropped here.
+    // #1961: a snapshot stamped for a DIFFERENT WORKTREE is dropped here; one
+    // stamped at a different HEAD is served and marked drifted. See
+    // loadPersistedGraph for the one-policy rationale.
     const disk = loadPersistedGraph(cwd, {
-        verifyGitStamp: true,
+        verifyWorktreeIdentity: true,
         allowPartial: true,
     });
     if (!disk)
@@ -451,9 +495,39 @@ export function getCachedReviewGraph(cwd) {
         fileSignatures: disk.fileSignatures,
         fileHashes: disk.fileHashes,
         graph: disk.graph,
+        // Durable half of the drift fact. The current-HEAD half is never cached
+        // beside it — see getReviewGraphRevisionDrift (#1961 review F3).
+        ...(disk.stampedHead ? { snapshotStampedHead: disk.stampedHead } : {}),
     });
     return disk.graph;
 }
+/**
+ * Revision drift for `cwd`'s currently cached graph, computed NOW (#1961).
+ *
+ * Returns the stamped/current commit pair when the warm entry came from a disk
+ * snapshot whose stamp names a commit other than the worktree's HEAD at this
+ * instant, and `undefined` otherwise — including the case where HEAD has moved
+ * BACK to the stamped commit, which resolves the drift and must clear the note.
+ *
+ * Derived, never stored: caching the pair is what made the first version of
+ * this feature report a commit that had since stopped being HEAD, and keep
+ * reporting drift after it was resolved. Callers ask on every render.
+ */
+export function getReviewGraphRevisionDrift(cwd) {
+    const entry = _workspaceGraphCache.get(normalizeMapKey(cwd));
+    const stampedHead = entry?.snapshotStampedHead;
+    if (!stampedHead)
+        return undefined;
+    const current = resolveGitIdentity(cwd);
+    // Unresolvable identity is "can't tell", never "drifted" — the same
+    // fail-open rule loadPersistedGraph applies to the worktree check.
+    if (!current || current.headCommit === stampedHead)
+        return undefined;
+    return { stampedHead, currentHead: current.headCommit };
+}
+// Re-exported so a consumer that already imports the builder dynamically
+// (module_report) gets the accessor and its renderer from one place (#1961).
+export { formatReviewGraphRevisionDriftNote };
 function makeCtx(filePath, cwd, facts) {
     return {
         filePath,
@@ -888,6 +962,29 @@ const LEGACY_GRAPH_CACHE_FILENAME = "review-graph.json";
 // laundered to a consumer as a complete graph. It is read back exclusively by
 // the full-build resume path (`loadReviewGraphCheckpoint`).
 const GRAPH_CHECKPOINT_FILENAME = "review-graph.checkpoint.json.gz";
+/**
+ * Record what the blind read decided about a stamped snapshot (#1961).
+ *
+ * Bounded the way AGENTS.md requires and `bounded-telemetry.ts` documents: the
+ * ledger counts EVERY occurrence exactly, and only the rising edge per
+ * (verdict, cwd) also writes the detailed `review-graph.log` record. The
+ * accessor runs on every module_report / lens-engine / project_report call, so
+ * an unbounded record here would flood the log during a single navigation
+ * session. No second latch: the rising edge comes from the ledger's own tally.
+ */
+function logSnapshotReadVerdict(cwd, phase, reason) {
+    const verdict = phase === "snapshot_read_dropped" ? "dropped" : "drifted";
+    const isRisingEdge = incrementDegradationCount({
+        kind: "review-graph-snapshot-read",
+        // Subject keeps BOTH discriminators, so aggregation still answers which
+        // workspace and which verdict after the detailed records stop.
+        subject: `${verdict}:${normalizeMapKey(cwd)}`,
+        reason,
+    });
+    if (!isRisingEdge)
+        return;
+    logReviewGraph({ cwd, phase, reason });
+}
 function loadPersistedGraph(cwd, opts) {
     const cacheDir = path.join(getProjectDataDir(cwd), "cache");
     const cachePath = path.join(cacheDir, GRAPH_CACHE_FILENAME);
@@ -907,24 +1004,33 @@ function loadPersistedGraph(cwd, opts) {
             return null;
         if (data.coverage?.partial && !opts?.allowPartial)
             return null;
-        if (opts?.verifyGitStamp && data.gitStamp) {
-            // #300: a stamped snapshot must match the CURRENT repo identity. This
-            // closes the "worktree removed + re-added at the same path for a
-            // different branch" edge — the data-dir slug is reused, but the stamp
-            // mismatch forces a cold rebuild instead of serving the old branch's
-            // graph. Opt-in per call site: only the BLIND read path
-            // (getCachedReviewGraph) verifies — the build path's tier-2 load is
-            // already content-verified downstream (signature + #202 hash confirm),
-            // and dropping there on every HEAD move would nuke the cold cache
-            // after each commit. Any resolution failure (non-git, unreadable HEAD)
-            // yields undefined from resolveGitIdentity — treated as "can't
-            // verify," not a mismatch, so it does NOT drop the snapshot.
+        // #1961: ONE verification policy across both load paths — verify tree
+        // IDENTITY, never revision. A HEAD move says nothing about file contents,
+        // and the build path's tier-2 load has said so since #300 (see the comment
+        // above its `loadPersistedGraph(cwd)` call): dropping on every HEAD move
+        // forces a full whole-repo rebuild after each plain `git commit`. The BLIND
+        // read path used to do exactly that, which is why a snapshot survived a
+        // median of ~12 minutes before every reader saw "graph: cold".
+        //
+        // What stays: `worktreeRoot`. A snapshot stamped for a DIFFERENT worktree
+        // reached this data dir through slug reuse, so it describes another tree
+        // and nothing downstream would catch it — this read is blind. What goes:
+        // the `headCommit` equality drop. A revision difference is now REPORTED
+        // (`stampedHead` below → `getReviewGraphRevisionDrift` → computeTrust and
+        // module_report) instead of hiding the graph. Any resolution failure
+        // (non-git, unreadable HEAD) yields undefined from resolveGitIdentity —
+        // "can't verify," not a mismatch, so it does not drop the snapshot.
+        let stampedHead;
+        if (opts?.verifyWorktreeIdentity && data.gitStamp) {
             const current = resolveGitIdentity(cwd);
-            if (current &&
-                (current.headCommit !== data.gitStamp.headCommit ||
-                    current.worktreeRoot !== data.gitStamp.worktreeRoot)) {
+            if (current && current.worktreeRoot !== data.gitStamp.worktreeRoot) {
+                logSnapshotReadVerdict(cwd, "snapshot_read_dropped", "worktree_mismatch");
                 return null;
             }
+            if (current && current.headCommit !== data.gitStamp.headCommit) {
+                stampedHead = data.gitStamp.headCommit;
+                logSnapshotReadVerdict(cwd, "snapshot_read_drifted", "head_moved");
+            }
         }
         const graph = {
             version: data.version,
@@ -944,6 +1050,7 @@ function loadPersistedGraph(cwd, opts) {
             fileSignatures: new Map(data.fileSignatures ?? []),
             fileHashes: new Map(data.fileHashes ?? []),
             graph,
+            ...(stampedHead ? { stampedHead } : {}),
         };
     }
     catch {
@@ -1951,8 +2058,13 @@ function deleteReviewGraphCheckpoint(cwd) {
 /**
  * Read back a checkpoint for `cwd`, gated on the graph version (single source of
  * truth: {@link REVIEW_GRAPH_VERSION}) and, when both stamps resolve, the git
- * identity — the same drop-on-mismatch guard `loadPersistedGraph` uses. Returns
- * null (and best-effort deletes an unusable file) when absent/stale/corrupt.
+ * WORKTREE identity — the same one-policy guard `loadPersistedGraph` uses, and
+ * for the same reason (#1961): the resume path content-verifies every processed
+ * file by hash below (`contentHashEntry` vs `processedHashes`) and evicts the
+ * stale ones, so revision equality proves nothing the hashes do not already
+ * prove. Dropping on a HEAD move threw away a whole resumable partial build
+ * after each plain `git commit`. Returns null (and best-effort deletes an
+ * unusable file) when absent/stale/corrupt.
  * The returned graph carries `persistCoverage.inProgress` so it can never be
  * mistaken for a complete graph if it escapes the resume path.
  */
@@ -1984,13 +2096,11 @@ function loadReviewGraphCheckpoint(cwd) {
     }
     if (data.gitStamp) {
         const current = resolveGitIdentity(cwd);
-        if (current &&
-            (current.headCommit !== data.gitStamp.headCommit ||
-                current.worktreeRoot !== data.gitStamp.worktreeRoot)) {
+        if (current && current.worktreeRoot !== data.gitStamp.worktreeRoot) {
             logReviewGraph({
                 cwd,
                 phase: "checkpoint_discarded",
-                reason: "git_stamp_mismatch",
+                reason: "worktree_mismatch",
             });
             deleteReviewGraphCheckpoint(cwd);
             return null;
@@ -3904,6 +4014,15 @@ async function _doBuildGraph(cwd, changedFiles, facts, seqHint, buildId) {
     const graph = resumed?.graph ?? createEmptyGraph();
     const filesToExtract = resumed?.remaining ?? filesToBuild;
     const treeSitterClient = getSharedTreeSitterClient();
+    // #1941: grow the tree cache to span THIS pass's actual per-parse working
+    // set before parsing starts — filesToExtract, not filesToBuild. On a cold
+    // build they're the same array; on a resumed build filesToExtract is only
+    // the checkpoint's remaining (unprocessed) files, since resumed files are
+    // reused from the checkpoint graph and never re-parsed here. Sizing to
+    // filesToBuild on a resume would over-grow the cache for files this pass
+    // never touches. Same #1715 pattern as scanner.ts:147 — monotonic and
+    // ceiling-bounded inside ensureTreeCacheCapacity itself.
+    treeSitterClient?.ensureTreeCacheCapacity(filesToExtract.length);
     const extractionStartedAt = Date.now();
     // Seeded with the reused files' hashes on resume so the completed snapshot
     // still records a hash for every file (needed by #202 incremental next time).
@@ -4045,8 +4164,42 @@ async function _doBuildGraph(cwd, changedFiles, facts, seqHint, buildId) {
     facts.setSessionFact("session.reviewGraph", graph);
     return graph;
 }
+/**
+ * The one place the in-flight dedupe key is derived — and the one place its
+ * workspace half is normalized (#1962 review F2).
+ *
+ * The key used to interpolate the caller's RAW `cwd`. Callers hand in whatever
+ * path they hold: `runtime-session.ts:1562`, `lens-map.ts:1243`, and
+ * `mcp/cli.ts:59` pass an unnormalized root, while project_report's trigger
+ * passes `normalizeMapKey(path.resolve(cwd))`. On Windows those differ by
+ * separator and casing alone, so ONE workspace produced two live `_buildCache`
+ * entries: two concurrent full builds of the same repo (the #256 two-build OOM
+ * shape), and an `isGraphBuildInFlight` probe that answered about a key nobody
+ * else used. Folding here makes every caller land on one key without any of
+ * them having to know that.
+ *
+ * The derivation lives in {@link buildCacheWorkspaceKey}, which the two sites
+ * that read build keys BACK also use, so write and read agree by construction
+ * rather than by coincidence.
+ */
+function buildCacheKey(cwd, changedFiles) {
+    return `${buildCacheWorkspaceKey(cwd)}|${[...changedFiles].sort((a, b) => a.localeCompare(b)).join(",")}`;
+}
+/**
+ * Whether a build for this exact (cwd, changedFiles) key is PENDING right now
+ * (#1962). Callers that report to a user — project_report's cold-path trigger —
+ * read this BEFORE calling `buildOrUpdateGraph`, so "a retry was started" is
+ * only said when a build actually started rather than when an in-flight one
+ * absorbed the call. Check and call must happen in the same synchronous block;
+ * anything awaited between them reopens the race this exists to close.
+ */
+export function isGraphBuildInFlight(cwd, changedFiles = []) {
+    return _buildCache.has(buildCacheKey(cwd, changedFiles));
+}
 export function buildOrUpdateGraph(cwd, changedFiles, facts, seqHint) {
-    const cacheKey = `${cwd}|${[...changedFiles].sort((a, b) => a.localeCompare(b)).join(",")}`;
+    const cacheKey = buildCacheKey(cwd, changedFiles);
+    // Only a PENDING build is here (see `_buildCache`), so this dedupes genuine
+    // concurrency and nothing else.
     const cached = _buildCache.get(cacheKey);
     if (cached)
         return cached;
@@ -4117,7 +4270,6 @@ export function buildOrUpdateGraph(cwd, changedFiles, facts, seqHint) {
         return graph;
     })
         .catch((err) => {
-        _buildCache.delete(cacheKey);
         const reason = err instanceof Error ? err.message : String(err);
         recordBuildAttempt(cwd, "failed", reason, buildId);
         logReviewGraph({
@@ -4138,6 +4290,17 @@ export function buildOrUpdateGraph(cwd, changedFiles, facts, seqHint) {
         throw err;
     });
     _buildCache.set(cacheKey, promise);
+    // #1962: the entry's lifetime is the BUILD's, not the process's. Settling —
+    // fulfilled, skipped, or rejected — releases the key so the next caller
+    // really builds. The identity guard means a newer build that already claimed
+    // the key survives this older build's cleanup. `then(fn, fn)` rather than
+    // `finally` so the derived promise handles the rejection instead of raising
+    // an unhandled one; the returned `promise` is unchanged either way.
+    const release = () => {
+        if (_buildCache.get(cacheKey) === promise)
+            _buildCache.delete(cacheKey);
+    };
+    promise.then(release, release);
     return promise;
 }
 /**

package/node_modules/pi-lens/dist/clients/review-graph/revision-drift.js

@@ -0,0 +1,21 @@
+/**
+ * Revision-drift evidence for a served review-graph snapshot, and the one
+ * wording every consumer renders it with (#1961).
+ *
+ * A separate module on purpose. `project-report.ts` and `module-report.ts`
+ * import the builder DYNAMICALLY, to keep that large module (and its
+ * tree-sitter dependencies) off their eager load path. Both still need this
+ * caveat's wording synchronously, and two hand-written copies of a warning
+ * sentence drift apart. This file imports nothing, so depending on it costs
+ * nothing.
+ */
+/**
+ * The one wording for the drift caveat, so `project_report`'s trust note and
+ * `module_report`'s warning cannot say different things about the same fact.
+ * Short commit ids only.
+ */
+export function formatReviewGraphRevisionDriftNote(drift) {
+    return (`Graph was built at commit ${drift.stampedHead.slice(0, 8)}; HEAD is now ` +
+        `${drift.currentHead.slice(0, 8)}. Results below reflect the earlier ` +
+        "revision — run pilens_rebuild or re-analyze to refresh.");
+}

package/node_modules/pi-lens/dist/clients/review-graph/workspace-modules.js

@@ -490,11 +490,14 @@ export function getModuleSourceFiles(moduleRoot, maxFiles = 20) {
             }
             if (!entry.isFile())
                 continue;
+            // #1974: extension gate before isIgnored — isIgnored recompiles
+            // minimatch patterns per ancestor dir per call, so it should only run
+            // for files the cheap extension check already flags as source.
+            if (!SOURCE_EXTS.has(path.extname(entry.name).toLowerCase()))
+                continue;
             if (ignoreMatcher.isIgnored(fullPath, false))
                 continue;
-            if (SOURCE_EXTS.has(path.extname(entry.name).toLowerCase())) {
-                files.push(normalizeMapKey(fullPath));
-            }
+            files.push(normalizeMapKey(fullPath));
         }
     };
     visit(root, 0);

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

@@ -610,6 +610,50 @@ export class RuntimeCoordinator {
         });
         return true;
     }
+    /**
+     * #1944: retire a past-EOF demotion after its ONE degraded delivery.
+     *
+     * The past-EOF gate demotes and re-arms, but nothing ever retired the
+     * record, so a blocker whose file shrank past the cited lines re-served on
+     * every turn end for the rest of the session — measured live at 80+
+     * minutes on session 01a0234c. The re-serve is unbounded, not the six
+     * turns the first evidence window suggested.
+     *
+     * It is unbounded because the record cannot resolve itself. The two
+     * clearing events (`clearInlineBlockers` on a later dispatch of the same
+     * path, `retireInlineBlockerOnConfirmedClean` on a fresh clean verdict)
+     * both need the file to be looked at again, and the agent has no reason to
+     * look: the coordinates it was handed do not exist. "Re-run to confirm" is
+     * an instruction this record makes impossible to follow.
+     *
+     * So the delivery surface retires it after serving it once, degraded. That
+     * is a DROP, which #1419's demote-not-drop rule normally forbids; the
+     * exception is narrow and stated here. The finding was already delivered
+     * this turn with its dead coordinates annotated, and what remains is a
+     * message pinned to a line the file does not have. `deadLines` is required
+     * and must be non-empty, so a record stale for any OTHER reason, or
+     * past-EOF with no identified dead line, still stands.
+     *
+     * @returns true when an entry was retired — the caller records it, so the
+     * suppression is never silent (#1432 Gap 1).
+     */
+    retireDemotedPastEofBlocker(filePath, deadLines) {
+        if (deadLines.length === 0)
+            return false;
+        const key = path.resolve(filePath);
+        const existing = this._pendingInlineBlockers.get(key);
+        if (!existing)
+            return false;
+        // Only this gate's own demotion. A dependency-drift demotion (#1631)
+        // keeps in-bounds coordinates the agent CAN re-run against, so it stays
+        // in the store until a fresh verdict clears it.
+        if (!existing.stale)
+            return false;
+        if ((existing.staleReason ?? "past-eof") !== "past-eof")
+            return false;
+        this._pendingInlineBlockers.delete(key);
+        return true;
+    }
     /**
      * Retire a file's inline blocker because a FRESH, content-bound diagnostic
      * verdict proved it gone (#1561).

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

@@ -19,6 +19,7 @@ import { canRunStartupHeavyScans } from "./language-policy.js";
 import { detectProjectLanguageProfile, getDefaultStartupTools, } from "./language-profile.js";
 import { logLatency } from "./latency-logger.js";
 import { runLogCleanup } from "./log-cleanup.js";
+import { resetCascadeTierSessionState } from "./lsp/cascade-tier.js";
 import { initLSPConfig, loadLSPConfig } from "./lsp/config.js";
 import { resetWorkspaceDiagnosticsCacheSession } from "./lsp/workspace-diagnostics-session.js";
 import { resetDirectLspCommandAvailability } from "./lsp/server.js";
@@ -1680,6 +1681,14 @@ export async function handleSessionStart(deps) {
     // concrete KnipClient. Session reset is an optional lifecycle capability;
     // its absence must not make session_start fail.
     knipClient.resetSessionState?.();
+    // #1910: the tier-3 cascade outstanding-touch registry and its
+    // sweep-scoped expired/evicted counters (clients/lsp/cascade-tier.ts) are
+    // a per-SESSION claim about touches THIS session fired. #1899 bounded the
+    // registry between sweeps but, by its own review, left the session
+    // boundary unwired — a session replacement inherited the prior session's
+    // outstanding touches and misattributed a stray expiry/eviction to the
+    // next session's first reconcile gauge.
+    resetCascadeTierSessionState();
     runtime.resetForSession(sessionStartMs);
     logLatency({
         type: "phase",
@@ -1857,6 +1866,38 @@ export async function handleSessionStart(deps) {
         log(`Active tools: ${quickTools.join(", ")}`);
         dbg(`session_start tools: ${quickTools.join(", ") || "deferred (quick mode)"}`);
         dbg("session_start: quick mode active - skipping slow tool probes, language profiling, preinstall, scans, and error debt baseline");
+        // #1911: the debug line above says WHICH steps were skipped, but nothing
+        // bounded or structured said so — quick mode's absence of work and an
+        // absent LOGGER read identically in latency.log. This record is that
+        // line's structured twin: one bounded gauge per quick-mode session_start,
+        // naming exactly the step set skipped, so a reader can tell "quick mode
+        // correctly skipped these" from "the probes silently never ran".
+        logLatency({
+            type: "phase",
+            phase: "session_start_skipped_steps",
+            filePath: cwd,
+            durationMs: 0,
+            metadata: {
+                mode: startupMode,
+                reason: deps.sessionReason,
+                // #1911 review F3: this `if (quickMode)` branch is an early return —
+                // the whole quick path — so there is no enumerable list of "steps
+                // run vs. skipped" this array could be derived from mechanically. It
+                // is DESCRIPTIVE documentation of what the early return skips,
+                // matching the `dbg()` line above word for word; keep both in sync by
+                // hand if either changes. It also does NOT narrow under
+                // `getFlag("no-lsp")` — quick mode skips the same five steps either
+                // way; the LSP flag instead affects `quickTools` above, a separate
+                // record.
+                steps: [
+                    "slow_tool_probes",
+                    "language_profiling",
+                    "tool_preinstall",
+                    "startup_scans",
+                    "error_debt_baseline",
+                ],
+            },
+        });
         const totalDurationMs = Date.now() - sessionStartMs;
         dbg(`session_start total: ${totalDurationMs}ms (interactive path)`);
         logLatency({

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

@@ -34,6 +34,8 @@ import { sweepInlineBlockerPastEof } from "./blocker-past-eof.js";
 // #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 { degradeDemotedFindingBody, formatRetirementNote, } from "./demoted-finding-render.js";
 import { STALE_LINE_MARKER } from "./stale-marker.js";
 import { getWidgetBlockingFilesForSweep, markWidgetFileBlockersStale, } from "./widget-state.js";
 /**
@@ -358,7 +360,9 @@ export async function handleTurnEnd(deps) {
             total: blockerPastEof.total,
             checked: blockerPastEof.checked,
             demoted: blockerPastEof.demoted,
-            healed: blockerPastEof.healed,
+            // #1944 review F3: `healed` is gone. Retirement makes the falling edge
+            // unreachable on this store, so the field could only ever log zero —
+            // see `BlockerPastEofCounts`.
         },
     });
     // #1631: freshness gate. A cached blocker is a verdict about the file AND
@@ -395,14 +399,38 @@ export async function handleTurnEnd(deps) {
     // Re-surface inline blockers from this turn that the agent didn't fix.
     // These were shown inline during write/edit but the agent moved on without resolving them.
     const unresolvedBlockers = runtime.getInlineBlockersSnapshot();
+    /** #1944: past-EOF demotions retired after their single degraded delivery. */
+    let demotedFindingsRetired = 0;
     for (const { filePath: bPath, summary, stale } of unresolvedBlockers) {
         const displayPath = toRunnerDisplayPath(cwd, bPath);
         if (stale) {
             // #1631: demoted — out of the authoritative blocker channel and into the
             // advisory channel with a stale marker, so the agent is told to re-run
             // rather than pressured by a verdict that may already be resolved.
+            //
+            // #1944: the CHANNEL change is not enough. Until this call the advisory
+            // embedded the blocker body verbatim, so the agent read "🔴 STOP — 11
+            // issue(s) must be fixed" with dead line numbers under a hedge line it
+            // ignored. Degrade the body itself, and — when the file shrank past the
+            // cited lines, so no re-run can ever confirm it — retire the record
+            // after this ONE delivery instead of re-serving it for the rest of the
+            // session.
+            const deadLines = blockerPastEof.deadLinesByPath.get(bPath) ?? [];
+            const degraded = degradeDemotedFindingBody(summary, { deadLines });
+            const retired = runtime.retireDemotedPastEofBlocker(bPath, deadLines);
+            if (retired) {
+                demotedFindingsRetired += 1;
+                // Bounded by the ledger's own per-kind/subject tally, and the subject
+                // keeps the discriminating identity (which store, which file).
+                incrementDegradationCount({
+                    kind: "demoted-finding-retired",
+                    subject: `inline-blocker:${displayPath}`,
+                    reason: `file shrank past cited line(s) ${deadLines.join(", ")}; retired after one degraded delivery`,
+                });
+            }
             // @delivery-surface: runtime-turn:unresolved-inline-blocker
-            advisoryParts.push(`${STALE_LINE_MARKER} ${displayPath}:\n${summary}`);
+            advisoryParts.push(`${STALE_LINE_MARKER} ${displayPath}:\n${degraded.body}` +
+                (retired ? `\n${formatRetirementNote(deadLines)}` : ""));
         }
         else {
             // @delivery-surface: runtime-turn:unresolved-inline-blocker
@@ -1906,6 +1934,18 @@ export async function handleTurnEnd(deps) {
     runtime.fixedThisTurn.clear();
     runtime.clearActionableWarnings();
     runtime.clearCodeQualityWarnings();
+    if (demotedFindingsRetired > 0) {
+        // #1944: the retired payload must not survive as a SUPPRESSION key.
+        // `turn-end-findings-last` holds a content signature used to silence a
+        // duplicate re-prompt; live evidence found the demoted payload still on
+        // disk 80+ minutes after the file shrank. It is not a delivery source —
+        // `runtime-context.ts` never reads it, and the read at the top of this
+        // function is gated on the current `sessionId`, so it cannot resurrect
+        // the finding in a later session. It CAN, however, silence a genuinely
+        // new report of content the store no longer holds. Drop it with the
+        // record it describes.
+        cacheManager.clearCache("turn-end-findings-last", cwd);
+    }
     logLatency({
         type: "tool_result",
         toolName: "turn_end",
@@ -1924,6 +1964,11 @@ export async function handleTurnEnd(deps) {
             blockerSections: blockerParts.length,
             staleSecretSections: staleSecretParts.length,
             advisorySections: advisoryParts.length,
+            // #1944 AC3: an empty advisory section on its own cannot say whether
+            // the turn had nothing to report or dropped something. This counter
+            // answers that from latency.log even when the payload is empty, and
+            // the payload itself carries the retirement note when it is not.
+            demotedFindingsRetired,
         },
     });
     resetFormatService();