pi-lens 4.1.2 → 4.1.4

package/dist/clients/runtime-tool-result.js

@@ -4,16 +4,21 @@ import * as path from "node:path";
 import { noteAuthoritativeContentAttachment } from "./agent-nudge.js";
 import { captureFileStats, diffFileStats, getOpaqueBaselineStore, recoverOpaqueChangesViaGit, } from "./opaque-mutation-scan.js";
 import { normalizeMapKey } from "./path-utils.js";
-import { extractReadPathsFromCommand, extractDeletedPathsFromCommand, extractGrepSearchReadsFromOutput, extractWrittenPathsFromCommand, } from "./bash-file-access.js";
+import { extractReadPathsFromCommand, extractDeletedPathsFromCommand, extractGrepSearchReadsFromOutput, extractWrittenPathsFromCommand, tokenizeShellCommand, } from "./bash-file-access.js";
 import { registerSearchReads, } from "./search-read-registration.js";
 import { createFileTime } from "./file-time.js";
 import { publishFormatQueued } from "./format-events-publish.js";
-import { isPathIgnoredByProject } from "./file-utils.js";
+import { invalidateProjectIgnoreMatcherForPath, isPathIgnoredByProject, } from "./file-utils.js";
+import { invalidateFormatterCacheForPath } from "./formatters.js";
 import { getFormatService } from "./format-service.js";
 import { isExternalOrVendorFile, normalizeEphemeralMapKey, pathsEqual, } from "./path-utils.js";
 import { PathKeyedMap } from "./path-keyed-map.js";
 import { resolveLanguageRootForFile } from "./language-profile.js";
 import { logLatency } from "./latency-logger.js";
+import { classifyMutatingTool, PI_LENS_SYNTHETIC_MUTATION_FIELD, } from "./mutating-tool.js";
+import { hasPendingObservation, noteMutationHandled, settleObservedMutation, } from "./observed-mutation.js";
+import { replayThroughMutationBridge, storedLineHashesFor, } from "./observed-mutation-sources.js";
+import { getAmbientAbortSignal } from "./safe-spawn.js";
 import { resolveToolCallCorrelationId } from "./tool-event.js";
 import { boundedIndexesForCount, createReadGuardEditBatchSummary, getReadGuardCorrelationId, logReadGuardEvent, } from "./read-guard-logger.js";
 import { notifyExternalFileChange } from "./lsp/index.js";
@@ -22,7 +27,72 @@ import { renderPostAutofixNotice, } from "./post-autofix-notice.js";
 import { syncGitGuardRecord } from "./git-guard.js";
 import { scheduleWordIndexPersist } from "./word-index.js";
 import { RUNTIME_CONFIG } from "./runtime-config.js";
+import { getActiveSessionId } from "./session-lifecycle.js";
 const AUTHORITATIVE_CONTENT_MAX_BYTES = RUNTIME_CONFIG.pipeline.lspMaxFileBytes;
+/**
+ * Git subcommands that import ANOTHER commit's content into the index. The
+ * whole family, with a verdict for each (#2060):
+ * - merge, rebase, cherry-pick, pull, revert, am: IN. Each stages the other
+ *   side's clean files beside the unmerged ones. `pull` is fetch+merge and
+ *   `am --3way` reaches the same unmerged state, both probed on git 2.55.
+ * - stash pop / stash apply: OUT. A conflicted pop leaves `M ` entries too,
+ *   but that content is the agent's OWN stashed work. Excluding it would
+ *   destroy exactly what opaque recovery exists to capture.
+ * - checkout -m: OUT. Its "incoming" side is the agent's local modifications
+ *   carried across the switch, so the same reasoning applies.
+ * - apply -3 / --3way: OUT. The patch is normally one the agent wrote, and
+ *   `apply` is far more often used without conflicts, so the narrower default
+ *   is to keep capturing.
+ * Membership only ARMS the filter; it still needs a real unmerged entry to do
+ * anything, so a non-integration use of a listed subcommand is inert.
+ */
+const GIT_INTEGRATION_SUBCOMMANDS = new Set([
+    "merge",
+    "rebase",
+    "cherry-pick",
+    "pull",
+    "revert",
+    "am",
+]);
+const GIT_GLOBAL_OPTIONS_WITH_VALUE = new Set([
+    "-C",
+    "-c",
+    "--config-env",
+    "--git-dir",
+    "--namespace",
+    "--work-tree",
+]);
+/**
+ * Failed integration commands are the one opaque-recovery case where Git's
+ * index contains changes made by the other branch rather than the agent.
+ * Keep this narrow: ordinary scripts and successful Git operations retain the
+ * normal recovery contract.
+ */
+export function isFailedGitIntegrationCommand(command, isError) {
+    if (isError !== true)
+        return false;
+    return tokenizeShellCommand(command).some(({ tokens, unsupported }) => {
+        if (unsupported)
+            return false;
+        const executable = path.win32
+            .basename(tokens[0] ?? "")
+            .toLowerCase()
+            .replace(/\.(?:cmd|exe)$/, "");
+        if (executable !== "git")
+            return false;
+        for (let index = 1; index < tokens.length; index += 1) {
+            const token = tokens[index] ?? "";
+            if (GIT_GLOBAL_OPTIONS_WITH_VALUE.has(token)) {
+                index += 1;
+                continue;
+            }
+            if (token.startsWith("-"))
+                continue;
+            return GIT_INTEGRATION_SUBCOMMANDS.has(token);
+        }
+        return false;
+    });
+}
 function parseDiffRanges(diff) {
     const changedLines = [];
     for (const line of diff.split("\n")) {
@@ -66,6 +136,102 @@ const lastAnalyzedStateByFile = new PathKeyedMap(normalizeEphemeralMapKey);
 export function clearLastAnalyzedStateCache() {
     lastAnalyzedStateByFile.clear();
 }
+/**
+ * Register one in-flight pipeline and hand back the inner map it landed in.
+ *
+ * Paired with {@link releaseInFlightPipeline}; split out of
+ * `dispatchPipelineAnalysis` so registration and deregistration are one seam
+ * with one owner (#2464 review round 3, F1) rather than two open-coded blocks
+ * ~80 lines apart whose invariants only line up if a reader checks both.
+ *
+ * Exported for the isolation red in
+ * `tests/clients/observed-mutation-integration.test.ts`: with
+ * `claimPipelineDispatch` below now consulted by BOTH dispatch call sites, the
+ * identity guard in the release has no reachable production trigger left, so
+ * the only honest way to prove it is to drive the seam directly.
+ */
+export function registerInFlightPipeline(filePath, stateHash, pipeline) {
+    let filePipelines = inFlightPipelines.get(filePath);
+    if (!filePipelines) {
+        filePipelines = new Map();
+        inFlightPipelines.set(filePath, filePipelines);
+    }
+    filePipelines.set(stateHash, pipeline);
+    return filePipelines;
+}
+/**
+ * Release one in-flight pipeline, pruning the per-file inner map once it is
+ * empty so a file touched once this session doesn't leave a permanent empty
+ * entry in the outer map.
+ *
+ * The IDENTITY check on the outer delete is load-bearing (#2464 review round 3,
+ * F1). `registered` is a reference captured BEFORE the pipeline await. Deleting
+ * by path alone assumes the outer entry still IS that map, and when it is not —
+ * anything that replaced it while this pipeline ran — the delete evicts a LIVE,
+ * unrelated pipeline's registration: its concurrent duplicates then stop
+ * deduping and its `participantIds`/`participantTotal` under-count. Delete only
+ * when the outer map still points at the very map this registration went into.
+ */
+export function releaseInFlightPipeline(filePath, stateHash, registered) {
+    registered.delete(stateHash);
+    if (registered.size === 0 && inFlightPipelines.get(filePath) === registered) {
+        inFlightPipelines.delete(filePath);
+    }
+}
+/**
+ * The two pre-conditions EVERY pipeline dispatch shares (#2464 review round 3,
+ * F1): the in-flight dedup for a concurrent call on the same post-write state,
+ * and the already-analysed latch for a sequential duplicate in the same turn.
+ *
+ * Both call sites of {@link dispatchPipelineAnalysis} consult this, so the
+ * PRE-conditions are as by-construction as the post-conditions that helper
+ * already owns. The observed-mutation path shipped without either check in
+ * round 2: two concurrent observed `tool_result`s for one file+hash both
+ * registered, the second overwrote the first's entry in the per-file map, and
+ * the first's release then evicted the whole outer entry — taking a live,
+ * unrelated classified pipeline's registration with it.
+ *
+ * ## Why this is SYNCHRONOUS and hands the join promise back
+ *
+ * Check-then-act here has to be atomic against the microtask queue.
+ * `dispatchPipelineAnalysis` registers synchronously before its own first
+ * await, so a caller that claims and then dispatches with no `await` in between
+ * cannot be interleaved. An `async` pre-check would reintroduce exactly that
+ * interleave — both racers see an empty registry, both resume, both dispatch —
+ * so the join's `await` is deliberately left to the caller.
+ *
+ * ## Why this is NOT folded into `dispatchPipelineAnalysis`
+ *
+ * On the classified chain the latch check sits ABOVE `addModifiedRange` and
+ * `recordProjectChange`. Moving it down into the helper would write
+ * `turn-state.json` ranges and an attributed change-log receipt for a state
+ * already analysed this turn — the duplicate-recording inversion #2464 exists
+ * to remove.
+ */
+export function claimPipelineDispatch(args) {
+    const { filePath, stateHash, turnIndex, participantId, dbg } = args;
+    // Deduplicate concurrent calls for the same final file state (pi can fire one
+    // tool_result per edit hunk). Do not dedupe by file alone: a distinct later
+    // same-turn edit to this file must still be analyzed.
+    const inFlight = inFlightPipelines.get(filePath)?.get(stateHash);
+    if (inFlight) {
+        dbg(`tool_result: skipping duplicate concurrent state for ${filePath}`);
+        if (inFlight.participantIds.length < 100) {
+            inFlight.participantIds.push(participantId);
+        }
+        inFlight.participantTotal += 1;
+        return { proceed: false, joined: inFlight.promise };
+    }
+    // Deduplicate sequential duplicate events for the same post-write state in
+    // the same turn while allowing later same-file edits whose content changed.
+    const lastAnalyzed = lastAnalyzedStateByFile.get(filePath);
+    if (lastAnalyzed?.turnIndex === turnIndex &&
+        lastAnalyzed.stateHash === stateHash) {
+        dbg(`tool_result: skipping already-analyzed file state this turn for ${filePath}`);
+        return { proceed: false, joined: undefined };
+    }
+    return { proceed: true };
+}
 const debouncedPipelines = new PathKeyedMap(normalizeEphemeralMapKey);
 const DEFAULT_DEBOUNCE_MS = 0;
 const MAX_DEBOUNCE_MS = 1000;
@@ -167,21 +333,32 @@ function getFileStateHash(filePath) {
         return `unreadable:${code}`;
     }
 }
-function getRequestedEditCount(event) {
-    if (event.toolName === "write")
+function getRequestedEditCount(event, kind) {
+    if (kind === "write")
         return 1;
     const edits = event.input?.edits;
     return Array.isArray(edits) && edits.length > 0 ? edits.length : 1;
 }
-function getRequestedEditIndexes(event) {
-    return boundedIndexesForCount(getRequestedEditCount(event));
+function getRequestedEditIndexes(event, kind) {
+    return boundedIndexesForCount(getRequestedEditCount(event, kind));
 }
-function sourceForToolName(toolName, details) {
+/**
+ * Change-log attribution for one classified mutation (#2423).
+ *
+ * A third-party tool gets its OWN source (`agent-tool:<name>`) rather than
+ * being folded into `agent-edit`: a report that attributes a change to "the
+ * model's edit tool" must not silently absorb an extension's rewrite.
+ */
+function sourceForMutation(classification, details) {
     if (details
         ?.piLensPartialApply) {
         return "partial-apply";
     }
-    return toolName === "write" ? "agent-write" : "agent-edit";
+    if (classification.provenance === "builtin" ||
+        classification.provenance === "bash-derived") {
+        return classification.kind === "write" ? "agent-write" : "agent-edit";
+    }
+    return `agent-tool:${classification.toolName}`;
 }
 function singleRange(ranges) {
     return ranges?.length === 1 ? ranges[0] : undefined;
@@ -198,8 +375,299 @@ function recordProjectChange(args) {
         onAppendError: (err) => args.dbg(`project change log append failed for ${args.filePath}: ${err}`),
     });
 }
+/**
+ * #2402 applied-edit records for a native edit tool, so an identical retry is
+ * recognized as already-applied instead of escalating through the
+ * oldText-not-found ladder. `input` carries the EXECUTED args (post-autopatch),
+ * the same text the preflight resolves against.
+ *
+ * Extracted (#2449 review round 4, S4) because the observational-settle skip
+ * path needs the IDENTICAL records: the mutation bridge does not write them, so
+ * an early return that skipped this block left every retry of an observed
+ * tool's edit looking unapplied. One body, two call sites — a second copy on the
+ * skip path is the drift this repo keeps catching.
+ */
+function recordNativeAppliedPairs(args) {
+    const pairs = [];
+    if (args.kind !== "edit")
+        return pairs;
+    const appliedInput = args.input;
+    const record = (oldText, newText) => {
+        if (typeof oldText === "string" && oldText.length > 0) {
+            args.runtime.partialApplyRecords.record(args.filePath, oldText, newText, args.stateHash);
+            pairs.push({ oldText, newText });
+        }
+    };
+    if (Array.isArray(appliedInput.edits)) {
+        for (const edit of appliedInput.edits)
+            record(edit.oldText, edit.newText);
+    }
+    else {
+        record(appliedInput.oldText, appliedInput.newText);
+    }
+    return pairs;
+}
+/**
+ * Keep `cachedExports` in sync after each write/edit so the pre-write STOP check
+ * does not fire on names that were removed from this file this session.
+ *
+ * Extracted for the same reason as {@link recordNativeAppliedPairs} (#2449
+ * review round 4, S4): the mutation bridge does not touch this cache, so the
+ * observational-settle skip path left it holding names an observed tool had
+ * just deleted.
+ */
+function refreshCachedExports(runtime, filePath) {
+    if (runtime.cachedExports.size === 0 || !nodeFs.existsSync(filePath))
+        return;
+    const exportRe = new RegExp("export\\s+(?:async\\s+)?(?:function|class|const|let|type|interface)\\s+(\\w+)", "g");
+    for (const [name, file] of runtime.cachedExports) {
+        if (path.resolve(file) === path.resolve(filePath)) {
+            runtime.cachedExports.delete(name);
+        }
+    }
+    try {
+        const freshContent = nodeFs.readFileSync(filePath, "utf-8");
+        for (const match of freshContent.matchAll(exportRe)) {
+            const name = match[1];
+            if (!runtime.cachedExports.has(name)) {
+                runtime.cachedExports.set(name, filePath);
+            }
+        }
+    }
+    catch {
+        // Non-fatal — stale entry is worse than a missing one
+    }
+}
+/**
+ * #2464: the pipeline's own lint/diagnostics dispatch, factored out of the
+ * block below that ALSO writes `turn-state.json` modified ranges and the
+ * attributed change-log receipt (`cacheManager.addModifiedRange` /
+ * `recordProjectChange`). The classified chain in `handleToolResult` still
+ * does both, in the same order as before this split — see the call site
+ * right after `recordProjectChange` below, which is byte-identical to what
+ * used to be inlined there.
+ *
+ * The observed-mutation early return (#2430/#2449 round 4, S4) is the SECOND
+ * caller: the mutation bridge already recorded the turn-state range and the
+ * change-log receipt for that edit, so it calls this helper for analysis
+ * WITHOUT asking for the recording a second time — which a shared "run the
+ * pipeline AND record" block could not express.
+ */
+async function dispatchPipelineAnalysis(args) {
+    const { deps, runtime, filePath, dispatchCwd, turnStateCwd, autofixMode, modifiedRanges, writeIndex, initialStateHash, readGuardCorrelationId, requestedEditIndexes, requestedEditTotal, isPartialApplyResult, toolResultStart, nativeAppliedPairs, } = args;
+    const { event, getFlag, getFlagSource, dbg, biomeClient, ruffClient, metricsClient, resetLSPService, } = deps;
+    const pipelinePromise = runPipeline({
+        filePath,
+        cwd: dispatchCwd,
+        projectRoot: turnStateCwd,
+        toolName: event.toolName,
+        autofixMode,
+        modifiedRanges,
+        telemetry: {
+            model: runtime.telemetryModel,
+            sessionId: runtime.telemetrySessionId,
+            turnIndex: runtime.turnIndex,
+            writeIndex,
+            modelId: runtime.telemetryModelId,
+            provider: runtime.telemetryProviderId,
+        },
+        getFlag,
+        getFlagSource,
+        dbg,
+        // #451: hand the deferred cascade live sequence accessors so the
+        // review-graph builder can skip its per-build O(project) sweep when
+        // only pi-observed edits happened. projectSeq is a function because the
+        // cascade runs after this returns (#450) — read current, not captured.
+        seqState: {
+            projectSeq: () => runtime.projectSeq,
+            getFilesChangedSince: (seq) => runtime.getFilesChangedSince(seq),
+        },
+        // The settle clock is live because the deferred cascade may reach its
+        // budget derivation before or after turn_end starts waiting.
+        turnEndCascadeSettleStart: () => runtime.getTurnEndCascadeSettleStart(),
+        // #348 phase 2: live reference so the deferred cascade can update the
+        // warm word index in place at the same seam as the graph rebuild.
+        // `runtime.wordIndex` is read fresh (not captured) via this closure-free
+        // property access being re-evaluated at object-literal construction
+        // time here — that's fine because runPipeline reads `ctx.wordIndex`
+        // synchronously into computeCascadeForFile's options before returning
+        // (the deferred part is the cascade's OWN execution, not this handoff).
+        wordIndex: runtime.wordIndex,
+        onWordIndexUpdated: (index) => {
+            scheduleWordIndexPersist(dispatchCwd, index, dbg);
+        },
+    }, {
+        biomeClient,
+        ruffClient,
+        metricsClient,
+        getFormatService,
+        fixedThisTurn: runtime.fixedThisTurn,
+    });
+    const pipelineTelemetry = {
+        promise: pipelinePromise,
+        participantIds: [...new Set(args.participantIds)].slice(0, 100),
+        participantTotal: args.participantTotal,
+    };
+    // Synchronous, and the FIRST thing after `runPipeline` handed back its
+    // promise: `claimPipelineDispatch` at each call site is only atomic because
+    // nothing awaits between the claim and this registration.
+    const registeredPipelines = registerInFlightPipeline(filePath, initialStateHash, pipelineTelemetry);
+    let result;
+    try {
+        result = await pipelinePromise;
+    }
+    catch (pipelineErr) {
+        if (getFlag("lens-guard")) {
+            runtime.markGitGuardCacheUnknown("pipeline_crash");
+        }
+        dbg(`runPipeline crashed: ${pipelineErr}`);
+        logReadGuardEvent({
+            event: "edit_post_edit_pipeline_failed",
+            correlationId: readGuardCorrelationId,
+            filePath,
+            metadata: {
+                tool: event.toolName,
+                commitStatus: "committed",
+                reasonCode: "pipeline_failed",
+            },
+        });
+        logReadGuardEvent({
+            event: "edit_batch_summary",
+            correlationId: readGuardCorrelationId,
+            filePath,
+            metadata: {
+                tool: event.toolName,
+                editBatchSummary: createReadGuardEditBatchSummary({
+                    requestedIndexes: requestedEditIndexes,
+                    requestedTotal: requestedEditTotal,
+                    resolvedIndexes: requestedEditIndexes,
+                    resolvedTotal: requestedEditTotal,
+                    appliedIndexes: requestedEditIndexes,
+                    appliedTotal: requestedEditTotal,
+                    participantIds: pipelineTelemetry.participantIds,
+                    participantTotal: pipelineTelemetry.participantTotal,
+                    commitStatus: "committed",
+                    postEditStatus: "failed",
+                    terminalStatus: "failed",
+                    durationMs: Date.now() - toolResultStart,
+                }),
+            },
+        });
+        dbg(`runPipeline crash stack: ${pipelineErr.stack}`);
+        // The LSP fleet is process-wide, but a pipeline crash belongs to one
+        // evaluation. A registered primary owns the fleet; a known secondary
+        // must not tear it down. Keep the historical reset when no registration
+        // exists because synthetic callers and early startup have no role evidence.
+        const activePrimarySessionId = getActiveSessionId();
+        const crashBelongsToPrimary = activePrimarySessionId === undefined ||
+            activePrimarySessionId === runtime.telemetrySessionId;
+        if (!getFlag("no-lsp") && crashBelongsToPrimary) {
+            resetLSPService({ fast: true, reason: "pipeline_crash" });
+        }
+        logLatency({
+            type: "tool_result",
+            toolName: event.toolName,
+            filePath,
+            durationMs: Date.now() - toolResultStart,
+            result: "pipeline_crash",
+        });
+        const notice = runtime.formatPipelineCrashNotice(filePath, pipelineErr);
+        return {
+            crashed: true,
+            response: {
+                content: notice
+                    ? [...event.content, { type: "text", text: notice }]
+                    : event.content,
+                isError: true,
+            },
+        };
+    }
+    finally {
+        releaseInFlightPipeline(filePath, initialStateHash, registeredPipelines);
+    }
+    if (!isPartialApplyResult) {
+        const postEditStatus = result.isError ? "failed" : "succeeded";
+        if (result.isError) {
+            logReadGuardEvent({
+                event: "edit_post_edit_pipeline_failed",
+                correlationId: readGuardCorrelationId,
+                filePath,
+                metadata: {
+                    tool: event.toolName,
+                    commitStatus: "committed",
+                    reasonCode: "pipeline_failed",
+                },
+            });
+        }
+        logReadGuardEvent({
+            event: "edit_batch_summary",
+            correlationId: readGuardCorrelationId,
+            filePath,
+            metadata: {
+                tool: event.toolName,
+                editBatchSummary: createReadGuardEditBatchSummary({
+                    requestedIndexes: requestedEditIndexes,
+                    requestedTotal: requestedEditTotal,
+                    resolvedIndexes: requestedEditIndexes,
+                    resolvedTotal: requestedEditTotal,
+                    appliedIndexes: requestedEditIndexes,
+                    appliedTotal: requestedEditTotal,
+                    participantIds: pipelineTelemetry.participantIds,
+                    participantTotal: pipelineTelemetry.participantTotal,
+                    commitStatus: "committed",
+                    postEditStatus,
+                    terminalStatus: postEditStatus === "failed" ? "failed" : "success",
+                    durationMs: Date.now() - toolResultStart,
+                }),
+            },
+        });
+    }
+    // ── Post-pipeline post-conditions (#2464 review round 2, S1) ───────────────
+    // These live INSIDE the helper rather than at its call sites so EVERY
+    // provenance gets them by construction. The observed path used to discard
+    // `result` entirely, so under `--immediate-format` the pipeline rewrote the
+    // file and none of the three below ran: the next edit was then blocked with
+    // a spurious `file_modified` (the read-guard staleness stamp was never
+    // re-taken), an identical retry escalated through the oldText-not-found
+    // ladder (the #2402 after-write hash was never stamped), and a duplicate
+    // tool_result for the same bytes analysed the file a second time (the
+    // already-analysed latch was never set).
+    const finalStateHash = getFileStateHash(filePath);
+    lastAnalyzedStateByFile.set(filePath, {
+        turnIndex: runtime.turnIndex,
+        stateHash: finalStateHash,
+    });
+    // #2402: pi-lens' own immediate format/autofix may have rewritten the file
+    // after the native edit was recorded by the caller. Stamp the post-pipeline
+    // state so an identical retry against the formatted bytes is still
+    // recognized as already-applied. Only the pairs recorded this invocation are
+    // stamped, and only when the pipeline actually changed the bytes.
+    // `initialStateHash` IS the post-write hash at both call sites — the
+    // classified chain passes `postWriteStateHash` verbatim, the observed path
+    // passes the same pre-settle digest.
+    if (finalStateHash !== initialStateHash) {
+        for (const pair of nativeAppliedPairs) {
+            runtime.partialApplyRecords.noteAfterWriteHash(filePath, pair.oldText, pair.newText, finalStateHash);
+        }
+    }
+    // The model's write/edit and pi-lens' own immediate format/autofix are now
+    // reflected on disk. Refresh read-guard staleness stamps so a follow-up edit
+    // is judged by read-range coverage, not by our own previous write.
+    if (!getFlag("no-read-guard")) {
+        const changedForReadGuard = new Set([
+            path.resolve(filePath),
+            ...(result.changedFiles ?? []).map((changedFile) => path.resolve(changedFile)),
+        ]);
+        for (const changedFile of changedForReadGuard) {
+            if (nodeFs.existsSync(changedFile)) {
+                deps.readGuard?.recordWritten(changedFile);
+            }
+        }
+    }
+    return { crashed: false, result };
+}
 export async function handleToolResult(deps) {
-    const { event, getFlag, getFlagSource, dbg, runtime, cacheManager, biomeClient, ruffClient, metricsClient, resetLSPService, agentBehaviorRecord, formatBehaviorWarnings, } = deps;
+    const { event, getFlag, dbg, runtime, cacheManager, agentBehaviorRecord, formatBehaviorWarnings, } = deps;
     const rawFilePath = event.input.path;
     const workspaceRoot = runtime.projectRoot || process.cwd();
     // #1642: a gitignored worktree edit got re-attributed onto a
@@ -269,6 +737,10 @@ export async function handleToolResult(deps) {
             ? rawFilePath
             : path.resolve(resolutionBasis, rawFilePath)
         : rawFilePath;
+    if (filePath) {
+        invalidateProjectIgnoreMatcherForPath(filePath);
+        invalidateFormatterCacheForPath(filePath);
+    }
     // Purely diagnostic: tool_call's call-time verdict (computed on ITS OWN
     // resolved path, which may since have been superseded) disagreed with
     // what actually executed. This does NOT gate anything by itself — the
@@ -351,16 +823,41 @@ export async function handleToolResult(deps) {
             }
             else if (pending.strategy === "git") {
                 // Git-first: no universe cap - works on any repo size.
-                const recovery = await recoverOpaqueChangesViaGit(scanRoot, pending.startedAt);
+                const recovery = await recoverOpaqueChangesViaGit(scanRoot, pending.startedAt, {
+                    excludeIndexOnlyWhenUnmerged: isFailedGitIntegrationCommand(command, event.isError),
+                });
                 if (recovery.verdict === "recovered") {
                     opaquePaths = recovery.paths.filter((p) => !isExternalOrVendorFile(p, scanRoot) &&
                         !isPathIgnoredByProject(p, scanRoot, false));
                 }
-                else if (recovery.verdict === "unknown" && recognized.length > 0) {
-                    // Git hiccup on a partially-recognized command: the
-                    // remainder's coverage is unknown, never clean-by-default.
+                else if (recovery.verdict === "unknown") {
+                    // #2060: deliberately WIDER than the old `recognized.length > 0`
+                    // guard. A fully opaque command whose probe failed is the shape
+                    // whose coverage is least knowable, and it used to record
+                    // nothing at all.
                     unknownReason = recovery.unknownReason;
                 }
+                // #2060: both counts are bounded (one record per tool_result, no
+                // per-path logging) and exist because filtering is invisible in
+                // production otherwise - the dropped paths simply never appear.
+                if ((recovery.excludedIncomingCount ?? 0) > 0) {
+                    logLatency({
+                        type: "phase",
+                        phase: "opaque_mutation_incoming_excluded",
+                        filePath: command.slice(0, 80),
+                        durationMs: Date.now() - started,
+                        result: `excluded:${recovery.excludedIncomingCount}`,
+                    });
+                }
+                if ((recovery.unknownStatusCount ?? 0) > 0) {
+                    logLatency({
+                        type: "phase",
+                        phase: "opaque_mutation_status_pair_unknown",
+                        filePath: command.slice(0, 80),
+                        durationMs: Date.now() - started,
+                        result: `kept:${recovery.unknownStatusCount}`,
+                    });
+                }
             }
             else if (pending.stats) {
                 const outcome = await captureFileStats(scanRoot, {
@@ -427,6 +924,10 @@ export async function handleToolResult(deps) {
                 toolName: "write",
                 input: { path: wp },
                 isError: false,
+                // #2423: pi-lens SYNTHESIZED this write from a bash command, so the
+                // seam reports `provenance: "bash-derived"` and a consumer can tell
+                // it apart from the host's own write tool.
+                [PI_LENS_SYNTHETIC_MUTATION_FIELD]: "bash",
             };
             const syntheticResult = await handleToolResult({
                 ...deps,
@@ -525,8 +1026,254 @@ export async function handleToolResult(deps) {
             });
         }
     }
-    if (event.toolName !== "write" && event.toolName !== "edit") {
-        dbg(`tool_result: skipped turn tracking - toolName="${event.toolName}" (not write/edit)`);
+    // #2423: THE inbound gate. Everything below this line is the mutation
+    // bookkeeping chain — read-guard staleness stamp, turn state, change-log
+    // receipt, deferred autofix and format. Before the seam this compared
+    // `event.toolName` to two literals, so a host or extension edit tool under
+    // any other name was dropped here with the path already resolved.
+    // `recognizeOnly` (#2423 review round 1, finding F5): the tool_call side
+    // already ran the adapters against the PRE-edit file and logged what they
+    // resolved. Re-running them here logged a second `touched_lines_detected`
+    // for every edit and an `edit_preflight_blocked` for edits that were never
+    // blocked, and any anchor it re-resolved would be resolved against content
+    // the edit has already rewritten. The seam carries the tool_call ranges
+    // forward by `toolCallId` instead.
+    const mutation = classifyMutatingTool(event, {
+        filePath: filePath || undefined,
+        sessionId: deps.sessionId,
+        recognizeOnly: true,
+    });
+    // #2430: settle the observational baseline BEFORE the classification gate
+    // returns. On the FIRST call of an unknown tool nothing below this line will
+    // run — that is the bug — so the disk diff is the only thing that can put
+    // the file in `turn-state.json`, and it replays through the mutation bridge
+    // to get the identical bookkeeping a `write` gets.
+    //
+    // The PROBE is synchronous and is the first thing asked, so the
+    // overwhelmingly common call — no baseline armed — pays one map lookup and
+    // nothing else (#2449 round 2, F1).
+    //
+    // The SETTLE is async (#2449 round 3, T4: no synchronous filesystem work on
+    // this path), so it yields. `handleToolResult` has no other `await` before
+    // it registers with `debouncedPipelines`/`inFlightPipelines`, and
+    // `tests/clients/runtime-tool-result-debounce.test.ts` asserts that a
+    // racing second tool_result for the same path cannot miss the first's
+    // entry — so everything the chain below derives from the file's POST-RESULT
+    // bytes is read HERE, before the yield. Otherwise the racing call rewrites
+    // the file while this one is awaiting and this one registers under the
+    // OTHER call's state hash, collapsing two distinct pipelines into one.
+    const observationPending = !getFlag("no-read-guard") &&
+        hasPendingObservation(resolveToolCallCorrelationId(event));
+    // #2464 review round 2 (S2): NOT gated on `mutation !== undefined` any more.
+    // The observed path now dispatches on call ONE of an unknown tool too, and
+    // that call is by definition unclassified — gating the pre-yield digest on a
+    // classification that does not exist yet would have left exactly the racing
+    // re-read this hoist exists to prevent.
+    const preSettleStateHash = observationPending && filePath ? getFileStateHash(filePath) : undefined;
+    let observedReplayed = 0;
+    let observedChangedPaths = [];
+    if (observationPending) {
+        const observed = await settleObservedMutation({
+            toolCallId: resolveToolCallCorrelationId(event),
+            toolName: event.toolName,
+            sessionGeneration: runtime.sessionGeneration,
+            turnIndex: runtime.turnIndex,
+            signal: getAmbientAbortSignal(),
+            record: replayThroughMutationBridge,
+            getStoredLineHashes: (candidate) => storedLineHashesFor(deps.readGuard, candidate),
+            isRecordable: (candidate) => !isExternalOrVendorFile(candidate, workspaceRoot) &&
+                !isPathIgnoredByProject(candidate, workspaceRoot, false),
+            dbg,
+        });
+        observedReplayed = observed.replayed;
+        observedChangedPaths = observed.changedPaths;
+        if (observed.replayed > 0) {
+            dbg(`tool_result: observed ${observed.replayed} mutation(s) from tool "${event.toolName}"`);
+        }
+        else if (observed.reason) {
+            dbg(`tool_result: observation for "${event.toolName}" did not settle: ${observed.reason}`);
+        }
+    }
+    // #2464 review round 2 (S5): ONE clock, started above BOTH exits, so
+    // `edit_batch_summary.durationMs` and the `tool_result` latency row measure
+    // the same span whichever provenance a tool takes. The observed path used to
+    // start its clock at the dispatch call itself, so its durations were
+    // pipeline-only and silently incomparable with the classified path's.
+    // Deliberately below the settle: neither path should be charged for the
+    // observational disk diff, which is arm-time work, not tool_result work.
+    const toolResultStart = Date.now();
+    // #2449 review round 3 (S2), narrowed in round 4 (S4). A tool learned from
+    // ONE observation is classified by NAME from here on AND is still armed —
+    // that second property is what makes a second observation, and therefore
+    // persistence, reachable at all (round 2, F2). Both halves then recorded the
+    // same physical edit: the settle above replayed it through the mutation
+    // bridge with measured ranges, and the chain below recorded it AGAIN as a
+    // whole-file change, so a three-edit session produced four change-log
+    // receipts.
+    //
+    // The settle wins, deliberately. It ran the disk diff, so it knows which
+    // LINES moved; the chain, reached through `recognizeOnly`, has no ranges for
+    // an unknown tool and over-approximates to the file. Skipping the arm
+    // instead would be the other way to fix this, and it is the wrong one — it
+    // makes PERSIST_AFTER_OBSERVATIONS unreachable again.
+    //
+    // ## What this return skips, stated in full (round 4, S4; #2464)
+    //
+    // The first cut called this "skipping turn tracking" and returned. It skipped
+    // considerably more than turn tracking, and THREE of those steps have no
+    // counterpart in `recordMutationThroughSeam`, so nothing else ran them. Those
+    // three run here, before the return:
+    //
+    //   - the #2402 applied-edit records — without them an identical retry of
+    //     the observed tool's edit escalates through the oldText-not-found ladder
+    //     instead of being recognized as already applied;
+    //   - `recordMutationToolReceipt`, the write→edit sticky turn transition,
+    //     which is pure ordering state the bridge never touches;
+    //   - the `cachedExports` refresh — without it the pre-write STOP check keeps
+    //     firing on names this very edit removed.
+    //
+    // What stays skipped is skipped because the BRIDGE already did it: the
+    // read-guard staleness stamp, the `turn-state.json` modified ranges, the
+    // attributed change-log receipt, and the deferred autofix/format pair —
+    // `recordMutationThroughSeam` steps 1-4. #2464 pulled the pipeline's own
+    // lint/diagnostics dispatch (`dispatchPipelineAnalysis`, defined above) out
+    // of the block below that also writes those same turn-state ranges and the
+    // change-log receipt, so it can be called HERE too — analysis without asking
+    // for the recording a second time.
+    //
+    // ## Why this sits ABOVE the classification gates (#2464 review round 2, S2)
+    //
+    // It used to sit BELOW `mutation === undefined`, which meant CALL ONE of every
+    // unknown tool — the call the observational net exists for — was recorded by
+    // the bridge and then returned unanalysed: `runPipeline` was never reached, so
+    // the file was fixed and formatted by the `agent_settled` drain but never
+    // linted, and AC2 ("an observed mutation gets its pipeline analysis in the
+    // same turn") was met on the second call only. `observedReplayed > 0` is the
+    // whole condition now: the bridge recorded this edit, whoever the tool is.
+    if (observedReplayed > 0) {
+        // ## The `hostToolResultFailed` asymmetry, stated rather than hidden
+        //
+        // The classified chain returns below on `event.isError === true` with a
+        // `commitStatus: "failed"` receipt; this block does not consult it, so an
+        // unknown tool that reports failure and STILL moved bytes is recorded,
+        // analysed, and receipted as `committed`. That is deliberate: the
+        // observation is disk evidence, not a claim — the bytes changed whatever
+        // the tool says about itself — and the classified early return is safe
+        // only because a failed host edit did not write. Reading a third-party
+        // tool's self-reported status as authority over what is on disk is the
+        // exact gap the observational net exists to close.
+        //
+        // The gates below (`mutation === undefined` / `!filePath` /
+        // `isExternalOrVendorFile`) are deliberately NOT consulted for the SKIP:
+        // once the bridge has recorded the edit, re-running the classified chain
+        // double-records it regardless of how the tool classifies. They are
+        // consulted for what this block can still usefully DO.
+        if (filePath && !isExternalOrVendorFile(filePath, workspaceRoot)) {
+            // On call ONE the tool is not classified at all, so there is no
+            // `mutation.kind` to read. The observation itself is the authority and
+            // it only ever records "edit" (`settleObservedMutation` hard-codes
+            // `kind: "edit"`, and #2430 tier 4 only ever classifies a learned tool
+            // as "edit"), so the two agree wherever both exist.
+            const observedKind = mutation?.kind ?? "edit";
+            const observedStateHash = preSettleStateHash ?? getFileStateHash(filePath);
+            const observedAppliedPairs = recordNativeAppliedPairs({
+                runtime,
+                input: event.input,
+                kind: observedKind,
+                filePath,
+                stateHash: observedStateHash,
+            });
+            const receiptOutcome = runtime.recordMutationToolReceipt?.call(runtime, filePath, observedKind);
+            refreshCachedExports(runtime, filePath);
+            // Same fallback formula the classified chain uses below, minus its
+            // `_bypassDebounce` branch (#2464 review round 2, S3): that branch was
+            // unreachable here. Both callers that set `_bypassDebounce` arrive with
+            // no pending baseline — `scheduleDebounced`'s re-entry because THIS
+            // call already consumed it at the settle above, and the bash-derived
+            // synthetic write because `runtime-tool-call.ts` excludes `bash` from
+            // arming outright (`toolName !== "bash"`). `observedKind` is always
+            // "edit", so the un-receipted default is "deferred" either way.
+            const observedAutofixMode = receiptOutcome?.autofixMode ??
+                (observedKind === "edit" ? "deferred" : "immediate");
+            // Analyse the file the observation actually RECORDED, not merely the
+            // one the tool named: a directory-target tool names a path that is not
+            // a file at all, and `runPipeline` on it is meaningless. `changedPaths`
+            // is already filtered by the `isRecordable` predicate handed to the
+            // settle above, so membership here also implies not-vendored and
+            // not-gitignored — the same two gates the classified chain applies
+            // before its own dispatch.
+            if (observedChangedPaths.some((candidate) => pathsEqual(candidate, filePath))) {
+                const observedReadGuardCorrelationId = getReadGuardCorrelationId(event);
+                // #2464 review round 3 (F1): the SAME two pre-conditions the
+                // classified site consults, through the same shared claim. Round 2
+                // dispatched here with neither, so two concurrent observed
+                // `tool_result`s for one file+hash both registered and both ran
+                // `runPipeline` — two autofix/format writers racing on one file — the
+                // second overwrote the first's registry entry, and the first's
+                // release then evicted the outer entry a live, unrelated classified
+                // pipeline had since re-created under it.
+                const observedClaim = claimPipelineDispatch({
+                    filePath,
+                    stateHash: observedStateHash,
+                    turnIndex: runtime.turnIndex,
+                    participantId: observedReadGuardCorrelationId,
+                    dbg,
+                });
+                if (!observedClaim.proceed) {
+                    if (observedClaim.joined) {
+                        await observedClaim.joined;
+                    }
+                    // Same terminal value as the block's own exit below: the bridge
+                    // already recorded this edit, and the analysis it would have asked
+                    // for is either running or already done.
+                    return syntheticWriteContent.length > 0
+                        ? { content: [...event.content, ...syntheticWriteContent] }
+                        : undefined;
+                }
+                const observedDispatchOutcome = await dispatchPipelineAnalysis({
+                    deps,
+                    runtime,
+                    filePath,
+                    dispatchCwd: resolveLanguageRootForFile(filePath, workspaceRoot),
+                    turnStateCwd: path.resolve(workspaceRoot),
+                    autofixMode: observedAutofixMode,
+                    // #2423: no adapter/diff ranges exist for a "learned" (unnamed)
+                    // tool — the classified chain below hits the same gap for this
+                    // provenance and also leaves `modifiedRanges` undefined, so the
+                    // dispatch runs unscoped (whole-file) exactly as it would there.
+                    modifiedRanges: undefined,
+                    writeIndex: runtime.nextWriteIndex(),
+                    initialStateHash: observedStateHash,
+                    readGuardCorrelationId: observedReadGuardCorrelationId,
+                    requestedEditIndexes: getRequestedEditIndexes(event, observedKind),
+                    requestedEditTotal: getRequestedEditCount(event, observedKind),
+                    isPartialApplyResult: (event.details ?? {})
+                        .piLensPartialApply === true,
+                    participantIds: [observedReadGuardCorrelationId],
+                    participantTotal: 1,
+                    toolResultStart,
+                    nativeAppliedPairs: observedAppliedPairs,
+                });
+                if (observedDispatchOutcome.crashed) {
+                    // #2464 review round 2, S6: parity with the classified chain — a
+                    // pipeline crash surfaces its notice to the agent instead of being
+                    // swallowed into a dbg line the model never sees. The recorded
+                    // edit stands either way; only the analysis was lost.
+                    dbg(`tool_result: pipeline analysis crashed for the observed mutation on ${filePath}; the recorded edit stands, analysis did not run this turn`);
+                    return observedDispatchOutcome.response;
+                }
+                dbg(`tool_result: the observational settle already recorded ${observedReplayed} mutation(s) for "${event.toolName}"; kept the applied-edit records, mutation receipt, cachedExports refresh, and ran the pipeline dispatch (#2464); skipped the bridge-covered staleness stamp / turn-state ranges / change-log receipt / deferred autofix+format`);
+            }
+            else {
+                dbg(`tool_result: the observational settle recorded ${observedReplayed} mutation(s) for "${event.toolName}", none of them ${filePath} — nothing to analyse under the named path`);
+            }
+        }
+        return syntheticWriteContent.length > 0
+            ? { content: [...event.content, ...syntheticWriteContent] }
+            : undefined;
+    }
+    if (mutation === undefined) {
+        dbg(`tool_result: skipped turn tracking - toolName="${event.toolName}" is not a classified mutation`);
         return syntheticWriteContent.length > 0
             ? { content: [...event.content, ...syntheticWriteContent] }
             : undefined;
@@ -539,11 +1286,15 @@ export async function handleToolResult(deps) {
         dbg(`tool_result: skipped pipeline - file outside project root or in node_modules: ${filePath}`);
         return;
     }
+    // #2430: a classified mutation is accounted for by the chain below, so the
+    // `agent_settled` sweep must re-baseline this file rather than report the
+    // same bytes as unexplained drift.
+    noteMutationHandled(filePath);
     const readGuardCorrelationId = getReadGuardCorrelationId(event);
     const resultDetails = (event.details ?? {});
     const isPartialApplyResult = resultDetails.piLensPartialApply === true;
-    const requestedEditIndexes = getRequestedEditIndexes(event);
-    const requestedEditTotal = getRequestedEditCount(event);
+    const requestedEditIndexes = getRequestedEditIndexes(event, mutation.kind);
+    const requestedEditTotal = getRequestedEditCount(event, mutation.kind);
     const participantIds = [
         ...(deps._telemetryParticipantIds ?? []),
         readGuardCorrelationId,
@@ -576,16 +1327,37 @@ export async function handleToolResult(deps) {
         });
         return { content: event.content, isError: true };
     }
+    // One post-result raw-byte hash, reused for the applied-edit records below and
+    // for the pipeline dedup key (`initialStateHash`) further down (finding 3):
+    // nothing between here and that point rewrites the file, so a second read
+    // would only re-derive the same digest.
+    //
+    // `preSettleStateHash` is that same digest taken BEFORE the observational
+    // settle's yield, on the only path that has one (#2449 round 3, T4). Reusing
+    // it is not an optimization: re-reading here would read whatever a racing
+    // tool_result wrote while this call was awaiting.
+    const postWriteStateHash = preSettleStateHash ?? getFileStateHash(filePath);
+    // #2402: a fully-applied native edit is also an applied record, so an
+    // identical retry is recognized as already-applied instead of escalating
+    // through the oldText-not-found ladder. `event.input` carries the EXECUTED
+    // args (post-autopatch), the same text the preflight resolves against.
+    const nativeAppliedPairs = recordNativeAppliedPairs({
+        runtime,
+        input: event.input,
+        kind: mutation.kind,
+        filePath,
+        stateHash: postWriteStateHash,
+    });
     // Must happen before debounce admission: latestDeps intentionally retains only
     // the latest event, but write -> edit is a sticky turn transition.
     const receipt = runtime
         .recordMutationToolReceipt;
     const autofixMode = deps._bypassDebounce
         ? (deps._autofixMode ??
-            (event.toolName === "edit" ? "deferred" : "immediate"))
+            (mutation.kind === "edit" ? "deferred" : "immediate"))
         : receipt
-            ? receipt.call(runtime, filePath, event.toolName).autofixMode
-            : event.toolName === "edit"
+            ? receipt.call(runtime, filePath, mutation.kind).autofixMode
+            : mutation.kind === "edit"
                 ? "deferred"
                 : "immediate";
     // Coalesce sequential edits to the same file into one pipeline run against
@@ -607,47 +1379,29 @@ export async function handleToolResult(deps) {
     deps.readGuard?.recordWritten(filePath);
     // Keep cachedExports in sync after each write/edit so the pre-write STOP
     // check doesn't fire on names that were removed from this file this session.
-    if (runtime.cachedExports.size > 0 && nodeFs.existsSync(filePath)) {
-        const exportRe = /export\s+(?:async\s+)?(?:function|class|const|let|type|interface)\s+(\w+)/g;
-        for (const [name, file] of runtime.cachedExports) {
-            if (path.resolve(file) === path.resolve(filePath)) {
-                runtime.cachedExports.delete(name);
-            }
-        }
-        try {
-            const freshContent = nodeFs.readFileSync(filePath, "utf-8");
-            for (const match of freshContent.matchAll(exportRe)) {
-                const name = match[1];
-                if (!runtime.cachedExports.has(name)) {
-                    runtime.cachedExports.set(name, filePath);
-                }
-            }
-        }
-        catch {
-            // Non-fatal — stale entry is worse than a missing one
-        }
-    }
-    const initialStateHash = getFileStateHash(filePath);
-    // Deduplicate concurrent calls for the same final file state (pi can fire one
-    // tool_result per edit hunk). Do not dedupe by file alone: a distinct later
-    // same-turn edit to this file must still be analyzed.
-    const inFlight = inFlightPipelines.get(filePath)?.get(initialStateHash);
-    if (inFlight) {
-        dbg(`tool_result: skipping duplicate concurrent state for ${filePath}`);
-        const duplicateId = readGuardCorrelationId;
-        if (inFlight.participantIds.length < 100) {
-            inFlight.participantIds.push(duplicateId);
+    refreshCachedExports(runtime, filePath);
+    // Reuse the hash taken right after the write landed (finding 3): the file is
+    // unchanged between that read and here, so this is byte-identical.
+    const initialStateHash = postWriteStateHash;
+    // #2464 review round 3 (F1): the in-flight dedup and the already-analysed
+    // latch moved into `claimPipelineDispatch`, shared verbatim with the observed
+    // call site, which shipped round 2 with NEITHER check. The position is
+    // unchanged — still ABOVE `addModifiedRange`/`recordProjectChange`, so a
+    // duplicate state still writes no turn-state range and no change-log
+    // receipt. Nothing may await between this claim and the dispatch below: the
+    // claim is only atomic because `dispatchPipelineAnalysis` registers before
+    // its own first await.
+    const classifiedClaim = claimPipelineDispatch({
+        filePath,
+        stateHash: initialStateHash,
+        turnIndex: runtime.turnIndex,
+        participantId: readGuardCorrelationId,
+        dbg,
+    });
+    if (!classifiedClaim.proceed) {
+        if (classifiedClaim.joined) {
+            await classifiedClaim.joined;
         }
-        inFlight.participantTotal += 1;
-        await inFlight.promise;
-        return;
-    }
-    // Deduplicate sequential duplicate events for the same post-write state in the
-    // same turn while allowing later same-file edits whose content changed.
-    const lastAnalyzed = lastAnalyzedStateByFile.get(filePath);
-    if (lastAnalyzed?.turnIndex === runtime.turnIndex &&
-        lastAnalyzed.stateHash === initialStateHash) {
-        dbg(`tool_result: skipping already-analyzed file state this turn for ${filePath}`);
         return;
     }
     const sessionFileTime = createFileTime("default");
@@ -658,7 +1412,9 @@ export async function handleToolResult(deps) {
         const readGuard = runtime.readGuard;
         readGuard?.recordWritten?.(filePath);
     }
-    const toolResultStart = Date.now();
+    // `toolResultStart` is hoisted above both provenance exits (#2464 review
+    // round 2, S5) so the two paths' durations are comparable — see its
+    // declaration right after the observational settle.
     dbg(`tool_result: tracking turn state for ${event.toolName} on ${filePath}`);
     if (isPathIgnoredByProject(filePath, workspaceRoot, false)) {
         dbg(`tool_result: skipping gitignored file ${filePath}`);
@@ -678,6 +1434,14 @@ export async function handleToolResult(deps) {
     // see the `telemetry:` block handed to `runPipeline` below.
     const writeIndex = runtime.nextWriteIndex();
     let modifiedRanges;
+    // #2423: ranges a shape adapter resolved from the tool's own input. Only a
+    // classified non-native edit shape sets these — a plain host `edit` carries
+    // its ranges in `details.diff` and is handled by the branch below.
+    const adapterRanges = mutation.editRanges && mutation.editRanges.length > 0
+        ? mutation.editRanges.map(([start, end]) => ({ start, end }))
+        : mutation.touchedLines
+            ? [{ start: mutation.touchedLines[0], end: mutation.touchedLines[1] }]
+            : undefined;
     try {
         // #1334 S6: the host DECLARES this payload (`EditToolDetails`, a
         // type-only export), so use it instead of re-declaring `{ diff?: string }`
@@ -688,7 +1452,7 @@ export async function handleToolResult(deps) {
         // has always relied on.
         const details = event.details;
         dbg(`tool_result: details.diff=${details?.diff ? "present" : "missing"}, details keys: ${Object.keys(event.details || {}).join(", ")}`);
-        if (event.toolName === "edit" && details?.diff) {
+        if (mutation.kind === "edit" && details?.diff) {
             const diff = details.diff;
             dbg(`tool_result: diff content (first 500 chars): ${diff.substring(0, 500)}`);
             const ranges = parseDiffRanges(diff);
@@ -701,7 +1465,37 @@ export async function handleToolResult(deps) {
             }
             dbg(`tool_result: turn state after add: ${JSON.stringify(cacheManager.readTurnState(turnStateCwd))}`);
         }
-        else if (event.toolName === "write" && nodeFs.existsSync(filePath)) {
+        else if (mutation.kind === "edit" &&
+            adapterRanges &&
+            nodeFs.existsSync(filePath)) {
+            // #2423: a third-party edit tool ships no host `details.diff`, so the
+            // diff branch above never fires and the file used to leave `files: {}`
+            // empty in turn-state.json. The shape adapter already resolved which
+            // lines the call touched — use those.
+            const content = nodeFs.readFileSync(filePath, "utf-8");
+            const importsChanged = /^import\s/m.test(content);
+            modifiedRanges = adapterRanges;
+            for (const range of adapterRanges) {
+                cacheManager.addModifiedRange(filePath, range, importsChanged, turnStateCwd, runtime.telemetrySessionId);
+            }
+        }
+        else if (mutation.kind === "edit" &&
+            mutation.provenance === "declared" &&
+            nodeFs.existsSync(filePath)) {
+            // #2423 review round 1 (F1): a third-party edit whose anchors did not
+            // resolve — a stale anchor, or the read-guard preflight never ran to
+            // resolve them — still CHANGED the file. Recording the whole file is a
+            // deliberate superset: turn state exists to say "this file changed,
+            // format and attribute it", and an empty `files` map is the exact
+            // symptom the issue reports. A host `edit` keeps its old behavior,
+            // because its ranges come from `details.diff` above.
+            const content = nodeFs.readFileSync(filePath, "utf-8");
+            const lineCount = content.split("\n").length;
+            const importsChanged = /^import\s/m.test(content);
+            modifiedRanges = [{ start: 1, end: lineCount }];
+            cacheManager.addModifiedRange(filePath, { start: 1, end: lineCount }, importsChanged, turnStateCwd, runtime.telemetrySessionId);
+        }
+        else if (mutation.kind === "write" && nodeFs.existsSync(filePath)) {
             const content = nodeFs.readFileSync(filePath, "utf-8");
             const lineCount = content.split("\n").length;
             const hasImports = /^import\s/m.test(content);
@@ -718,7 +1512,7 @@ export async function handleToolResult(deps) {
         cwd: turnStateCwd,
         filePath,
         source: deps._mutationSourceOverride ??
-            sourceForToolName(event.toolName, event.details),
+            sourceForMutation(mutation, event.details),
         changedRange: singleRange(modifiedRanges),
         dbg,
     });
@@ -731,187 +1525,39 @@ export async function handleToolResult(deps) {
         durationMs: turnStateMs,
     });
     dbg(`tool_result fired for: ${filePath} (turn_state: ${turnStateMs}ms)`);
-    let result;
-    const pipelinePromise = runPipeline({
+    // #2464: the pipeline dispatch itself now lives in `dispatchPipelineAnalysis`
+    // (defined above `handleToolResult`), shared with the observed-mutation
+    // early return. This call site is otherwise unchanged — same arguments, same
+    // crash-then-return / success-then-continue shape as before the split.
+    const dispatchOutcome = await dispatchPipelineAnalysis({
+        deps,
+        runtime,
         filePath,
-        cwd: dispatchCwd,
-        projectRoot: turnStateCwd,
-        toolName: event.toolName,
+        dispatchCwd,
+        turnStateCwd,
         autofixMode,
         modifiedRanges,
-        telemetry: {
-            model: runtime.telemetryModel,
-            sessionId: runtime.telemetrySessionId,
-            turnIndex: runtime.turnIndex,
-            writeIndex,
-            modelId: runtime.telemetryModelId,
-            provider: runtime.telemetryProviderId,
-        },
-        getFlag,
-        getFlagSource,
-        dbg,
-        // #451: hand the deferred cascade live sequence accessors so the
-        // review-graph builder can skip its per-build O(project) sweep when
-        // only pi-observed edits happened. projectSeq is a function because the
-        // cascade runs after this returns (#450) — read current, not captured.
-        seqState: {
-            projectSeq: () => runtime.projectSeq,
-            getFilesChangedSince: (seq) => runtime.getFilesChangedSince(seq),
-        },
-        // The settle clock is live because the deferred cascade may reach its
-        // budget derivation before or after turn_end starts waiting.
-        turnEndCascadeSettleStart: () => runtime.getTurnEndCascadeSettleStart(),
-        // #348 phase 2: live reference so the deferred cascade can update the
-        // warm word index in place at the same seam as the graph rebuild.
-        // `runtime.wordIndex` is read fresh (not captured) via this closure-free
-        // property access being re-evaluated at object-literal construction
-        // time here — that's fine because runPipeline reads `ctx.wordIndex`
-        // synchronously into computeCascadeForFile's options before returning
-        // (the deferred part is the cascade's OWN execution, not this handoff).
-        wordIndex: runtime.wordIndex,
-        onWordIndexUpdated: (index) => {
-            scheduleWordIndexPersist(dispatchCwd, index, dbg);
-        },
-    }, {
-        biomeClient,
-        ruffClient,
-        metricsClient,
-        getFormatService,
-        fixedThisTurn: runtime.fixedThisTurn,
-    });
-    const pipelineTelemetry = {
-        promise: pipelinePromise,
-        participantIds: [...new Set(participantIds)].slice(0, 100),
+        writeIndex,
+        initialStateHash,
+        readGuardCorrelationId,
+        requestedEditIndexes,
+        requestedEditTotal,
+        isPartialApplyResult,
+        participantIds,
         participantTotal,
-    };
-    let filePipelines = inFlightPipelines.get(filePath);
-    if (!filePipelines) {
-        filePipelines = new Map();
-        inFlightPipelines.set(filePath, filePipelines);
-    }
-    filePipelines.set(initialStateHash, pipelineTelemetry);
-    try {
-        result = await pipelinePromise;
-    }
-    catch (pipelineErr) {
-        if (getFlag("lens-guard")) {
-            runtime.markGitGuardCacheUnknown("pipeline_crash");
-        }
-        dbg(`runPipeline crashed: ${pipelineErr}`);
-        logReadGuardEvent({
-            event: "edit_post_edit_pipeline_failed",
-            correlationId: readGuardCorrelationId,
-            filePath,
-            metadata: {
-                tool: event.toolName,
-                commitStatus: "committed",
-                reasonCode: "pipeline_failed",
-            },
-        });
-        logReadGuardEvent({
-            event: "edit_batch_summary",
-            correlationId: readGuardCorrelationId,
-            filePath,
-            metadata: {
-                tool: event.toolName,
-                editBatchSummary: createReadGuardEditBatchSummary({
-                    requestedIndexes: requestedEditIndexes,
-                    requestedTotal: requestedEditTotal,
-                    resolvedIndexes: requestedEditIndexes,
-                    resolvedTotal: requestedEditTotal,
-                    appliedIndexes: requestedEditIndexes,
-                    appliedTotal: requestedEditTotal,
-                    participantIds: pipelineTelemetry.participantIds,
-                    participantTotal: pipelineTelemetry.participantTotal,
-                    commitStatus: "committed",
-                    postEditStatus: "failed",
-                    terminalStatus: "failed",
-                    durationMs: Date.now() - toolResultStart,
-                }),
-            },
-        });
-        dbg(`runPipeline crash stack: ${pipelineErr.stack}`);
-        if (!getFlag("no-lsp")) {
-            resetLSPService({ fast: true, reason: "pipeline_crash" });
-        }
-        logLatency({
-            type: "tool_result",
-            toolName: event.toolName,
-            filePath,
-            durationMs: Date.now() - toolResultStart,
-            result: "pipeline_crash",
-        });
-        const notice = runtime.formatPipelineCrashNotice(filePath, pipelineErr);
-        return {
-            content: notice
-                ? [...event.content, { type: "text", text: notice }]
-                : event.content,
-            isError: true,
-        };
-    }
-    finally {
-        // Prune the per-file inner map once it's empty so a file touched once
-        // this session doesn't leave a permanent empty entry in the outer map.
-        filePipelines.delete(initialStateHash);
-        if (filePipelines.size === 0) {
-            inFlightPipelines.delete(filePath);
-        }
-    }
-    if (!isPartialApplyResult) {
-        const postEditStatus = result.isError ? "failed" : "succeeded";
-        if (result.isError) {
-            logReadGuardEvent({
-                event: "edit_post_edit_pipeline_failed",
-                correlationId: readGuardCorrelationId,
-                filePath,
-                metadata: {
-                    tool: event.toolName,
-                    commitStatus: "committed",
-                    reasonCode: "pipeline_failed",
-                },
-            });
-        }
-        logReadGuardEvent({
-            event: "edit_batch_summary",
-            correlationId: readGuardCorrelationId,
-            filePath,
-            metadata: {
-                tool: event.toolName,
-                editBatchSummary: createReadGuardEditBatchSummary({
-                    requestedIndexes: requestedEditIndexes,
-                    requestedTotal: requestedEditTotal,
-                    resolvedIndexes: requestedEditIndexes,
-                    resolvedTotal: requestedEditTotal,
-                    appliedIndexes: requestedEditIndexes,
-                    appliedTotal: requestedEditTotal,
-                    participantIds: pipelineTelemetry.participantIds,
-                    participantTotal: pipelineTelemetry.participantTotal,
-                    commitStatus: "committed",
-                    postEditStatus,
-                    terminalStatus: postEditStatus === "failed" ? "failed" : "success",
-                    durationMs: Date.now() - toolResultStart,
-                }),
-            },
-        });
-    }
-    lastAnalyzedStateByFile.set(filePath, {
-        turnIndex: runtime.turnIndex,
-        stateHash: getFileStateHash(filePath),
+        toolResultStart,
+        nativeAppliedPairs,
     });
-    // The model's write/edit and pi-lens' own immediate format/autofix are now
-    // reflected on disk. Refresh read-guard staleness stamps so a follow-up edit
-    // is judged by read-range coverage, not by our own previous write.
-    if (!getFlag("no-read-guard")) {
-        const changedForReadGuard = new Set([
-            path.resolve(filePath),
-            ...(result.changedFiles ?? []).map((changedFile) => path.resolve(changedFile)),
-        ]);
-        for (const changedFile of changedForReadGuard) {
-            if (nodeFs.existsSync(changedFile)) {
-                deps.readGuard?.recordWritten(changedFile);
-            }
-        }
+    if (dispatchOutcome.crashed) {
+        return dispatchOutcome.response;
     }
+    // #2464 review round 2 (S1): the three post-pipeline post-conditions that
+    // used to be written out here — the already-analysed latch, the #2402
+    // after-write hash stamp, and the read-guard staleness re-stamp over
+    // `result.changedFiles` — now live INSIDE `dispatchPipelineAnalysis`, so the
+    // observed path gets them by construction rather than by a second author
+    // remembering to copy them.
+    const result = dispatchOutcome.result;
     let autofixNewlyQueued = false;
     if (!result.isError &&
         autofixMode === "deferred" &&
@@ -942,7 +1588,12 @@ export async function handleToolResult(deps) {
             publishFormatQueued({
                 filePath,
                 cwd: dispatchCwd,
-                tool: event.toolName,
+                // The v1 `pilens:format:queued` payload declares
+                // `tool: "write" | "edit"`, so a third-party tool publishes under
+                // its KIND rather than its name. Widening the published field is a
+                // public-API decision tracked in #2421; until then the kind is the
+                // honest projection.
+                tool: mutation.kind,
                 dbg,
                 kinds: autofixMode === "deferred" ? ["autofix", "format"] : ["format"],
             });
@@ -952,13 +1603,15 @@ export async function handleToolResult(deps) {
         publishFormatQueued({
             filePath,
             cwd: dispatchCwd,
-            tool: event.toolName,
+            // Same #2421 projection as the queued-with-format publish above.
+            tool: mutation.kind,
             kinds: ["autofix"],
             dbg,
         });
     }
     for (const changedFile of result.changedFiles ?? []) {
         const resolvedChanged = path.resolve(changedFile);
+        invalidateFormatterCacheForPath(resolvedChanged);
         if (!nodeFs.existsSync(resolvedChanged))
             continue;
         recordProjectChange({