pi-lens 4.1.2 → 4.1.4

package/dist/clients/review-graph/service.js

@@ -1,3 +1,5 @@
+import { recordDegradationOnce } from "../degradation-ledger.js";
+import { isAbsoluteFilePath, normalizeMapKey } from "../path-utils.js";
 import { computeImpactCascade as computeImpactCascadeImpl, computeTransitiveImpact as computeTransitiveImpactImpl, } from "./query.js";
 import { buildOrUpdateGraph as buildOrUpdateGraphImpl, } from "./builder.js";
 import { formatImpactCascade as formatImpactCascadeImpl } from "./format.js";
@@ -19,7 +21,57 @@ export function computeTransitiveImpact(graph, seedFile, options) {
     return computeTransitiveImpactImpl(graph, seedFile, options);
 }
 export function recordEntitySnapshotDiff(facts, filePath, nextSnapshot) {
-    const prev = facts.getSessionFact(`${ENTITY_SNAPSHOT_PREFIX}${filePath}`) ?? new Map();
+    // #2477 round 2 (reviewer F1/F2): folding `cwd` into this key was REVERTED.
+    // The writer (`clients/dispatch/runners/tree-sitter.ts`) passes `ctx.cwd`,
+    // which `createDispatchContext` (`clients/dispatch/dispatcher.ts:324-326`)
+    // sets to the file's NEAREST LANGUAGE-ROOT (`resolveLanguageRootForFile`),
+    // while the reader (`upsertChangedSymbols`, `clients/review-graph/builder.ts`,
+    // reached via `computeCascadeForFile` → `buildOrUpdateGraph`) keys off the
+    // WORKSPACE cwd. In a monorepo/cargo-workspace/go-module layout those two
+    // cwd values diverge, so a folded `(cwd, path)` key the builder reader can
+    // never hit zeroed `graphChangedSymbolCount` on every build — reproduced:
+    // master returns `["alpha","beta"]`, the folded-key version returns `[]`
+    // — and made the cascade over-fan to every symbol (`query.ts:230-238`
+    // treats an empty `changedSymbols` as "no narrowing").
+    //
+    // The #2477 cross-project collision this was meant to close cannot reach
+    // this function in production: the sole writer always passes `ctx.filePath`,
+    // which `createDispatchContext` sets via `resolveRunnerPath` to an
+    // ALWAYS-ABSOLUTE path (the #2016 invariant, `dispatcher.ts:320,327,346`).
+    // A relative `filePath` here can only happen through a caller regression.
+    // Enforce that instead of re-keying: reject a non-absolute `filePath` with
+    // a visible, bounded ledger record (never silently, per AGENTS.md) and
+    // skip the diff rather than compute one under a key the real reader could
+    // never reach anyway. `recordDegradationOnce` (not a thrown error) is used
+    // because the sole call site's surrounding try/catch
+    // (`tree-sitter.ts` — "entity snapshot / blast-radius enrichment is
+    // best-effort") is a BARE, UNLOGGED catch: a thrown error there vanishes
+    // with no trace, which is strictly worse than a ledger record.
+    if (!isAbsoluteFilePath(filePath)) {
+        recordDegradationOnce({
+            kind: "review-graph-non-absolute-entity-path",
+            subject: filePath,
+            reason: "recordEntitySnapshotDiff requires an absolute filePath (refs #2477)",
+        });
+        return { added: [], removed: [], modified: [] };
+    }
+    // Normalize once at this boundary, then reuse the folded path for both
+    // per-file facts. An unnormalized write is a key the builder reader can never
+    // hit, and an unnormalized snapshot forks a second empty diff (#2355).
+    const normalizedFilePath = normalizeMapKey(filePath);
+    const snapshotKey = `${ENTITY_SNAPSHOT_PREFIX}${normalizedFilePath}`;
+    const changedSymbolsKey = `${CHANGED_SYMBOLS_PREFIX}${normalizedFilePath}`;
+    const stored = facts.getBoundedSessionFact(snapshotKey);
+    // An evicted snapshot is unknown, not empty. Diffing against an empty Map
+    // puts every entity in `added`, which reads downstream as "the whole file
+    // changed" and schedules a blast-radius run for a file that did not change.
+    // Re-seed the snapshot and report no diff instead (#2282 review F1).
+    if (stored === undefined && facts.wasBoundedSessionFactEvicted(snapshotKey)) {
+        facts.setBoundedSessionFact(snapshotKey, new Map(nextSnapshot));
+        facts.setBoundedSessionFact(changedSymbolsKey, []);
+        return { added: [], removed: [], modified: [] };
+    }
+    const prev = stored ?? new Map();
     const added = [];
     const removed = [];
     const modified = [];
@@ -38,7 +90,7 @@ export function recordEntitySnapshotDiff(facts, filePath, nextSnapshot) {
             .map((key) => key.split(":")[1])
             .filter(Boolean)),
     ];
-    facts.setSessionFact(`${ENTITY_SNAPSHOT_PREFIX}${filePath}`, new Map(nextSnapshot));
-    facts.setSessionFact(`${CHANGED_SYMBOLS_PREFIX}${filePath}`, changedSymbols);
+    facts.setBoundedSessionFact(snapshotKey, new Map(nextSnapshot));
+    facts.setBoundedSessionFact(changedSymbolsKey, changedSymbols);
     return { added, removed, modified };
 }

package/dist/clients/review-graph/shared-extraction-ir.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { BoundedFifoMap } from "../bounded-cache.js";
 import { normalizeMapKey } from "../path-utils.js";
 /**
  * THE producer/consumer hash contract, in one place (#955 review): scanner
@@ -17,7 +18,10 @@ export function reviewGraphIrContentHash(content) {
 // registry's lifetime is the scan-to-build window, not the process lifetime.
 const MAX_ROOTS = 8;
 const MAX_FILES_PER_ROOT = 20_000;
-const roots = new Map();
+// Both levels are FIFO, matching the hand-rolled blocks these replaced: no
+// read on either map refreshed recency before #2442, and the consume-once
+// contract above means a read is normally a DELETE anyway.
+const roots = new BoundedFifoMap(MAX_ROOTS);
 let accepted = 0;
 let rejected = 0;
 function rootKey(cwd) {
@@ -33,23 +37,11 @@ export function publishReviewGraphFileIr(cwd, entry) {
     const key = rootKey(cwd);
     let files = roots.get(key);
     if (!files) {
-        files = new Map();
+        files = new BoundedFifoMap(MAX_FILES_PER_ROOT);
         roots.set(key, files);
-        while (roots.size > MAX_ROOTS) {
-            const oldest = roots.keys().next().value;
-            if (oldest === undefined)
-                break;
-            roots.delete(oldest);
-        }
     }
     const fileKey = normalizeMapKey(entry.filePath);
-    files.delete(fileKey);
-    while (files.size >= MAX_FILES_PER_ROOT) {
-        const oldest = files.keys().next().value;
-        if (oldest === undefined)
-            break;
-        files.delete(oldest);
-    }
+    files.delete(fileKey); // republish is a refresh: it becomes the newest
     files.set(fileKey, { ...entry, filePath: fileKey });
 }
 /**

package/dist/clients/review-graph/tsconfig-paths.js

@@ -2,9 +2,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import { BoundedLruCache } from "../bounded-cache.js";
 import * as path from "node:path";
-import { findGoverningTsconfigDir, getDirectoryMarkers, } from "../workspace-topology.js";
+import { findGoverningTsconfigDir, getDirectoryMarkers, registerWorkspaceTopologyReset, } from "../workspace-topology.js";
 const cache = new BoundedLruCache(64);
 const referencesCache = new BoundedLruCache(64);
+registerWorkspaceTopologyReset(() => {
+    cache.clear();
+    referencesCache.clear();
+});
 /** Strip JSONC comments and trailing commas without touching string contents. */
 function parseJsonc(content) {
     let output = "";

package/dist/clients/review-graph/workspace-modules.js

@@ -6,6 +6,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { hasCargoWorkspaceTable, readCargoDependencyNames, readCargoPackageName, readCargoWorkspaceMembers, } from "../cargo-manifest.js";
 import { getProjectIgnoreMatcher, isExcludedDirName, } from "../file-utils.js";
 import { normalizeMapKey } from "../path-utils.js";
 import { getWorkspaceManifestMarkers } from "../workspace-topology.js";
@@ -52,8 +53,12 @@ function detectWorkspaceType(cwd) {
     if (markers.hasCargoToml) {
         try {
             const content = fs.readFileSync(path.join(cwd, "Cargo.toml"), "utf-8");
-            if (content.includes("[workspace]"))
+            // The shared presence check (#2498) — see its own doc comment in
+            // cargo-manifest.ts for why a bare `.includes`/regex reimplementation
+            // of this test is wrong (comment/sentinel handling).
+            if (hasCargoWorkspaceTable(content)) {
                 return "cargo";
+            }
         }
         catch { }
     }
@@ -146,71 +151,6 @@ function extractYamlList(content, key) {
     }
     return values;
 }
-function extractTomlArray(content, key) {
-    const prefix = `${key}`;
-    let collecting = false;
-    let buffer = "";
-    for (const rawLine of content.split(/\r?\n/)) {
-        const line = rawLine.split("#", 1)[0].trim();
-        if (!line)
-            continue;
-        if (!collecting) {
-            if (!line.startsWith(prefix))
-                continue;
-            const equalsIndex = line.indexOf("=");
-            if (equalsIndex === -1 || line.slice(0, equalsIndex).trim() !== key)
-                continue;
-            const afterEquals = line.slice(equalsIndex + 1).trim();
-            if (!afterEquals.startsWith("["))
-                continue;
-            collecting = true;
-            buffer += afterEquals.slice(1);
-        }
-        else {
-            buffer += `,${line}`;
-        }
-        const closeIndex = buffer.indexOf("]");
-        if (closeIndex !== -1) {
-            buffer = buffer.slice(0, closeIndex);
-            break;
-        }
-    }
-    return buffer
-        .split(",")
-        .map((s) => stripQuotes(s.trim()))
-        .filter(Boolean);
-}
-function extractTomlSection(content, section) {
-    const lines = [];
-    let inSection = false;
-    for (const rawLine of content.split(/\r?\n/)) {
-        const trimmed = rawLine.trim();
-        if (trimmed === `[${section}]`) {
-            inSection = true;
-            continue;
-        }
-        if (inSection && trimmed.startsWith("[") && trimmed.endsWith("]"))
-            break;
-        if (inSection)
-            lines.push(rawLine);
-    }
-    return lines;
-}
-function extractTomlString(content, key) {
-    for (const rawLine of content.split(/\r?\n/)) {
-        const line = rawLine.split("#", 1)[0].trim();
-        const equalsIndex = line.indexOf("=");
-        if (equalsIndex === -1 || line.slice(0, equalsIndex).trim() !== key)
-            continue;
-        const value = line.slice(equalsIndex + 1).trim();
-        const quote = value[0];
-        if ((quote !== '"' && quote !== "'") || value.length < 2)
-            return undefined;
-        const endIndex = value.indexOf(quote, 1);
-        return endIndex === -1 ? undefined : value.slice(1, endIndex);
-    }
-    return undefined;
-}
 function moduleFromPackageJson(cwd, pkgRoot) {
     const pkgJson = readJsonSafe(path.join(pkgRoot, "package.json"));
     if (!pkgJson?.name)
@@ -250,7 +190,7 @@ function scanCargoModules(cwd) {
     let members = [];
     try {
         const content = fs.readFileSync(path.join(cwd, "Cargo.toml"), "utf-8");
-        members = extractTomlArray(content, "members");
+        members = readCargoWorkspaceMembers(content);
     }
     catch {
         return [];
@@ -260,15 +200,11 @@ function scanCargoModules(cwd) {
         const pkgRoot = path.resolve(cwd, member);
         const memberToml = path.join(pkgRoot, "Cargo.toml");
         let name = "";
-        const deps = [];
+        let deps = [];
         try {
             const content = fs.readFileSync(memberToml, "utf-8");
-            name = extractTomlString(content, "name") ?? "";
-            for (const line of extractTomlSection(content, "dependencies")) {
-                const depName = line.trim().match(/^([A-Za-z0-9_-]+)\s*=/);
-                if (depName)
-                    deps.push(depName[1]);
-            }
+            name = readCargoPackageName(content) ?? "";
+            deps = readCargoDependencyNames(content);
         }
         catch {
             continue;

package/dist/clients/review-graph-logger.js

@@ -1,10 +1,17 @@
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
+import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
-const REVIEW_GRAPH_LOG_DIR = getGlobalPiLensDir();
+import { normalizeFilePath } from "./path-utils.js";
+const REVIEW_GRAPH_LOG_DIR = getGlobalPiLensLogDir();
 const REVIEW_GRAPH_LOG_FILE = path.join(REVIEW_GRAPH_LOG_DIR, "review-graph.log");
-const writer = createNdjsonLogger({ filePath: REVIEW_GRAPH_LOG_FILE });
+// Bounded like every other global sink (#2505) — see sessionstart-logger.
+const writer = createNdjsonLogger({
+    filePath: REVIEW_GRAPH_LOG_FILE,
+    maxBytes: getMaxLogSizeMB() * 1024 * 1024,
+    backupPath: `${REVIEW_GRAPH_LOG_FILE}.1`,
+});
 /**
  * Build the one canonical graph metadata shape used by build and persist logs.
  * Counts come from the graph instance; source-file count may use the exact
@@ -27,6 +34,9 @@ export function makeReviewGraphBuildMetadata(graph, options = {}) {
             graph.persistCoverage?.sourceFilesTruncated
             ? { sourceFilesTruncated: true }
             : {}),
+        ...(options.pathNormalizeCalls === undefined
+            ? {}
+            : { pathNormalizeCalls: options.pathNormalizeCalls }),
         nodes: graph.nodes.size,
         edges: graph.edges.length,
         ...(graph.persistCoverage
@@ -34,11 +44,27 @@ export function makeReviewGraphBuildMetadata(graph, options = {}) {
             : {}),
     };
 }
+/**
+ * #2141: call sites feed this a mix of raw `cwd` params and already-normalized
+ * cache keys (`normalizeMapKey(path.resolve(cwd))`), so the same project root
+ * showed up in the log as both `C:\...\pi-free` and `C:/.../pi-free`. Rather
+ * than auditing every call site, normalize once here — the single emit
+ * seam — matching the form `normalizeFilePath` already produces for every
+ * other structured log's `cwd` field (bus-publish, disposition-publish,
+ * diagnostics-publish, format-events-publish all normalize at their publish
+ * call sites; this pulls the same conversion in-house so no future call site
+ * can regress it).
+ */
 export function logReviewGraph(entry) {
     if (isTestMode()) {
         return;
     }
-    writer.log({ ts: new Date().toISOString(), ...entry, pid: process.pid });
+    writer.log({
+        ts: new Date().toISOString(),
+        ...entry,
+        cwd: normalizeFilePath(entry.cwd),
+        pid: process.pid,
+    });
 }
 export function getReviewGraphLogPath() {
     return REVIEW_GRAPH_LOG_FILE;

package/dist/clients/runtime-agent-end.js

@@ -190,6 +190,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         changed: [],
         failed: [],
         skipped: [],
+        unavailable: [],
     };
     // #502 fix provenance: per-path {tool, kind} entries accumulated across the
     // deferred-format loop below, passed as `fixes` on the batch
@@ -348,7 +349,8 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         return !disabled;
     });
     if (formatRecords.length > 0) {
-        const work = new Array(formatRecords.length);
+        const work = [];
+        work.length = formatRecords.length;
         const started = new Set();
         let nextIndex = 0;
         const worker = async () => {
@@ -430,6 +432,18 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                     },
                 ], "format-failed");
             }
+            // #2413: an unavailable formatter is durable, not transient — record it
+            // once and DO NOT requeue. Requeuing here is exactly what made
+            // `spawn oxfmt ENOENT` re-fire on every agent_end for the same files.
+            if (result.formatUnavailable.length > 0) {
+                for (const u of result.formatUnavailable) {
+                    summary.unavailable.push({
+                        filePath,
+                        formatter: u.formatter,
+                        reason: u.reason,
+                    });
+                }
+            }
             if (result.formatChanged) {
                 summary.changed.push(filePath);
                 for (const tool of result.formattersUsed) {
@@ -663,6 +677,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
             changed: summary.changed.length,
             failed: summary.failed.length,
             skipped: summary.skipped.length,
+            unavailable: summary.unavailable.length,
         },
     });
     logLatency({
@@ -676,9 +691,10 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
             changed: summary.changed.length,
             failed: summary.failed.length,
             skipped: summary.skipped.length,
+            unavailable: summary.unavailable.length,
         },
     });
-    dbg(`agent_end deferred_format complete: formatted=${summary.formatted} changed=${summary.changed.length} failed=${summary.failed.length} skipped=${summary.skipped.length}`);
+    dbg(`agent_end deferred_format complete: formatted=${summary.formatted} changed=${summary.changed.length} failed=${summary.failed.length} skipped=${summary.skipped.length} unavailable=${summary.unavailable.length}`);
     if (summary.failed.length > 0) {
         notify(`pi-lens deferred format: ${summary.changed.length} changed, ${summary.failed.length} failed`, "warning");
     }

package/dist/clients/runtime-context.js

@@ -103,12 +103,58 @@ export function peekTestFindings(cacheManager, cwd, runtime, logDelivery = false
             {
                 role: "user",
                 content: current
-                    ? `${AUTOMATION_FRAMING}Test failures detected last turn — fix before continuing:\n\n${findings.data.content}`
+                    ? `${AUTOMATION_FRAMING}${testFindingsCurrentPrefix(findings.data.runnerErrorOnly)}\n\n${findings.data.content}`
                     : `${AUTOMATION_FRAMING}${historicalTestContent(findings.data.content, findings.data.provenance)}`,
             },
         ],
     };
 }
+/**
+ * #2522: a batch made entirely of RUNNER errors (timeout, missing
+ * provider/binary — see `TestRunnerFindingsCache.runnerErrorOnly`) is not a
+ * failure the agent introduced, so it must not read as a blocker the way a
+ * genuine failing test does.
+ */
+function testFindingsCurrentPrefix(runnerErrorOnly) {
+    return runnerErrorOnly
+        ? "Test runner could not complete last turn (advisory — not a failure introduced this turn):"
+        : "Test failures detected last turn — fix before continuing:";
+}
+/**
+ * Retire a delivered test-findings record: blank the content, keep everything a
+ * delivery does not settle.
+ *
+ * ONE function, called by both `consumeTestFindings` (the in-process context
+ * hook) and `acknowledgeTestFindings` (the MCP Stop-hook commit), because
+ * "what survives a retire" is exactly the kind of rule that rots when it is
+ * stated twice. It already had: round 2 taught the consume copy to preserve
+ * `deferredTargets` and left the acknowledge copy dropping them, and the
+ * acknowledge copy is the LIVE Stop-hook path — including the branch where
+ * `handleTurnEnd` never runs at all — so on that path the deferral set was
+ * wiped before anything could ever dispatch it (#2522 review round 3, F2).
+ *
+ * What survives, and why:
+ *  - `testRunGeneration` — nulling the slot would let a still-in-flight OLDER
+ *    batch read `undefined`, pass the strictly-greater suppression check, and
+ *    resurrect a consumed one-shot advisory with stale results.
+ *  - `deferredTargets` — delivering the advisory says the agent has SEEN the
+ *    deferral, not that those targets ran. Dropping the list silently un-defers
+ *    them and the cut batch is never finished.
+ *  - `retiredTargets` — the session-scoped deferral cap. Dropping it re-arms a
+ *    suite already measured as too slow for the batch budget, which puts the
+ *    livelock back.
+ *
+ * An empty-content record peeks as undelivered while keeping all three intact.
+ */
+function retireTestFindings(cacheManager, cwd) {
+    const prior = cacheManager.readCache("test-runner-findings", cwd)?.data;
+    cacheManager.writeCache("test-runner-findings", {
+        content: "",
+        testRunGeneration: prior?.testRunGeneration,
+        deferredTargets: prior?.deferredTargets,
+        retiredTargets: prior?.retiredTargets,
+    }, cwd);
+}
 export function consumeTestFindings(cacheManager, cwd, runtime) {
     const record = cacheManager.readCache("test-runner-findings", cwd);
     if (!record?.data?.content)
@@ -116,16 +162,7 @@ export function consumeTestFindings(cacheManager, cwd, runtime) {
     const findings = peekTestFindings(cacheManager, cwd, runtime, true);
     if (!findings)
         return;
-    // Retire the content but PRESERVE the generation high-water mark: nulling
-    // the whole slot would let a still-in-flight OLDER batch see `undefined`,
-    // pass the strictly-greater suppression check, and resurrect a consumed
-    // one-shot advisory with stale results. An empty-content record peeks as
-    // undelivered while keeping late-generation ordering intact.
-    const priorGeneration = cacheManager.readCache("test-runner-findings", cwd)?.data?.testRunGeneration;
-    cacheManager.writeCache("test-runner-findings", {
-        content: "",
-        testRunGeneration: priorGeneration,
-    }, cwd);
+    retireTestFindings(cacheManager, cwd);
     return findings;
 }
 /** Complete an acknowledged MCP delivery without re-validating or re-rendering it. */
@@ -145,11 +182,7 @@ export function acknowledgeTestFindings(cacheManager, cwd) {
     const findings = cacheManager.readCache("test-runner-findings", cwd);
     if (!findings?.data?.content)
         return;
-    // Same high-water-mark preservation as consumeTestFindings.
-    cacheManager.writeCache("test-runner-findings", {
-        content: "",
-        testRunGeneration: findings.data.testRunGeneration,
-    }, cwd);
+    retireTestFindings(cacheManager, cwd);
 }
 export function consumeSessionStartGuidance(cacheManager, cwd) {
     const guidance = cacheManager.readCache("session-start-guidance", cwd);

package/dist/clients/runtime-coordinator.js

@@ -6,6 +6,7 @@ import { appendProjectChange, } from "./project-changes.js";
 import { normalizeMapKey, pathsEqual } from "./path-utils.js";
 import { PathKeyedMap } from "./path-keyed-map.js";
 import { BoundedLruCache } from "./bounded-cache.js";
+import { PartialApplyRecordStore } from "./partial-edit-apply.js";
 import { ReadGuard } from "./read-guard.js";
 import { RUNTIME_CONFIG } from "./runtime-config.js";
 import { TurnSummaryCollector } from "./turn-summary.js";
@@ -111,6 +112,11 @@ export class RuntimeCoordinator {
     // (cheap, empty Map) but callers gate recording behind the
     // `lens-turn-summary` flag so it's a true no-op when the feature is off.
     _turnSummary = new TurnSummaryCollector();
+    // #2402/#1053: session-scoped applied-edit records for exact-retry
+    // recognition. Both producers (partial-apply commit, full native-edit
+    // success) write here; the preflight consults it before declaring an
+    // oldText miss, so an identical retry never re-executes a committed write.
+    partialApplyRecords = new PartialApplyRecordStore();
     resetForSession(startedAt = Date.now()) {
         this._sessionGeneration += 1;
         this._sessionStartedAt = startedAt;
@@ -159,6 +165,9 @@ export class RuntimeCoordinator {
         this._actionableWarningsThisTurn.clear();
         this._codeQualityWarningsThisTurn.clear();
         this._turnSummary.clear();
+        // #2402: an applied-edit record is a fact about the session that applied
+        // it; a new session must re-resolve identical payloads from content.
+        this.partialApplyRecords.clear();
     }
     get sessionStartedAt() {
         return this._sessionStartedAt;
@@ -317,9 +326,15 @@ export class RuntimeCoordinator {
     get droppedMutationReceiptCount() {
         return this._droppedMutationReceipts;
     }
-    /** Atomically records write/edit ordering before debounce can coalesce it. */
-    recordMutationToolReceipt(filePath, toolName) {
-        if (toolName === "write") {
+    /**
+     * Atomically records write/edit ordering before debounce can coalesce it.
+     *
+     * Takes the classified {@link MutationKind}, not a raw tool name (#2423):
+     * an edit-shaped tool pi-lens does not name still demotes this file to the
+     * deferred pass, which is the safe timing.
+     */
+    recordMutationToolReceipt(filePath, kind) {
+        if (kind === "write") {
             this._writtenThisTurn.set(filePath, true);
         }
         else if (this._writtenThisTurn.has(filePath)) {
@@ -329,7 +344,7 @@ export class RuntimeCoordinator {
             this._fixedThisTurn.delete(filePath);
         }
         return {
-            autofixMode: toolName === "edit" || this._autofixDemotedThisTurn.has(filePath)
+            autofixMode: kind === "edit" || this._autofixDemotedThisTurn.has(filePath)
                 ? "deferred"
                 : "immediate",
         };
@@ -734,6 +749,74 @@ export class RuntimeCoordinator {
         this._pendingInlineBlockers.delete(key);
         return true;
     }
+    /**
+     * #1950 fix-round F1: read the current delivery count WITHOUT committing
+     * an increment. `runtime-turn.ts` needs the count a delivery would reach
+     * BEFORE it knows whether that delivery will actually reach the agent —
+     * the turn-end signature dedupe (`turn-end-findings-last`) can suppress a
+     * turn whose rendered content is identical to the last one, and a
+     * suppressed turn must not advance the counter (the agent never saw it).
+     * The caller peeks, renders the tentative body, and only calls
+     * {@link incrementInlineBlockerStaleDelivery} once it knows the turn's
+     * content is NOT being suppressed.
+     */
+    peekInlineBlockerStaleDeliveryCount(filePath) {
+        const key = path.resolve(filePath);
+        return this._pendingInlineBlockers.get(key)?.staleDeliveryCount ?? 0;
+    }
+    /**
+     * #1950: commit one more turn end that re-served this record while
+     * `stale`. The caller (`runtime-turn.ts`) only calls this for a
+     * `"dependency-drift"` demotion — a `"past-eof"` demotion retires after
+     * its own single delivery (#1944, `retireDemotedPastEofBlocker`) and
+     * never accumulates a count — and only AFTER confirming the turn's
+     * content will not be suppressed by the signature dedupe (see
+     * {@link peekInlineBlockerStaleDeliveryCount}), so this counts ACTUAL
+     * deliveries the agent saw, not turn-end loop iterations. Returns the new
+     * count, or 0 when there is no entry to count against (already retired,
+     * or never recorded).
+     */
+    incrementInlineBlockerStaleDelivery(filePath) {
+        const key = path.resolve(filePath);
+        const existing = this._pendingInlineBlockers.get(key);
+        if (!existing)
+            return 0;
+        const next = (existing.staleDeliveryCount ?? 0) + 1;
+        this._pendingInlineBlockers.set(key, {
+            ...existing,
+            staleDeliveryCount: next,
+        });
+        return next;
+    }
+    /**
+     * #1950: retire a dependency-drift demotion once it has been delivered
+     * `DEPENDENCY_DRIFT_MAX_DELIVERIES` times with no re-run confirming or
+     * clearing it. Unlike {@link retireDemotedPastEofBlocker}, the record is
+     * NOT provably unrecoverable — its coordinates are still in bounds, and a
+     * fresh dispatch of the file could still confirm or clear it. This is a
+     * bounded-noise cap, not a "this can never resolve" verdict, and the
+     * caller's ledger reason must say so (`demoted-finding-retired`'s "capped,
+     * re-run can still confirm" vs. past-EOF's "retired, unrecoverable").
+     *
+     * Only ever touches this gate's OWN demotion (`staleReason ===
+     * "dependency-drift"`) — a past-EOF demotion on the same file is that
+     * gate's own record to retire, not this one's.
+     *
+     * @returns true when an entry was retired — the caller records it, so the
+     * suppression is never silent (#1432 Gap 1).
+     */
+    retireDemotedDependencyDriftBlocker(filePath) {
+        const key = path.resolve(filePath);
+        const existing = this._pendingInlineBlockers.get(key);
+        if (!existing)
+            return false;
+        if (!existing.stale)
+            return false;
+        if (existing.staleReason !== "dependency-drift")
+            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).
@@ -931,7 +1014,9 @@ export class RuntimeCoordinator {
      * for a same-kind re-touch. Callers publish each kind's first transition
      * without spamming repeated edits before `agent_end`.
      */
-    deferMutation(filePath, cwd, toolName, turnStateCwd, kind, ownerSessionId, originCwd) {
+    deferMutation(filePath, cwd, 
+    /** Host tool name; any mutating tool, not just `write`/`edit` (#2423). */
+    toolName, turnStateCwd, kind, ownerSessionId, originCwd) {
         const key = path.resolve(filePath);
         const now = Date.now();
         const resolvedOriginCwd = originCwd ?? turnStateCwd;
@@ -962,7 +1047,9 @@ export class RuntimeCoordinator {
         });
         return true;
     }
-    deferFormat(filePath, cwd, toolName, turnStateCwd, ownerSessionId, originCwd) {
+    deferFormat(filePath, cwd, 
+    /** Host tool name; any mutating tool, not just `write`/`edit` (#2423). */
+    toolName, turnStateCwd, ownerSessionId, originCwd) {
         return this.deferMutation(filePath, cwd, toolName, turnStateCwd, "format", ownerSessionId, originCwd);
     }
     get pendingDeferredFormatCount() {