@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/mutation-attribution.js

@@ -0,0 +1,368 @@
+/**
+ * Learned mutation attribution for tools pi-lens cannot classify (#2430).
+ *
+ * ## Why this module exists
+ *
+ * `clients/mutating-tool.ts` recognizes a mutation by NAME (pi's built-ins) or
+ * by input SHAPE (the adapter registry). The population of third-party edit
+ * tools is open-ended, so neither tier can ever be complete: a tool called
+ * `patch_file` taking `{target, body}` matches nothing and is dropped before
+ * the first bookkeeping call.
+ *
+ * `clients/observed-mutation.ts` closes that by WATCHING — it snapshots a
+ * bounded file set around an unclassified call and diffs it afterwards. This
+ * module is the memory of what that watching learned, so the observation is
+ * paid for at most twice per tool instead of on every call:
+ *
+ * - **First** observed mutation after tool X: `X -> mutating` for this SESSION,
+ *   plus one `unclassified-mutating-tool` degradation record naming X, so the
+ *   registry gap is visible rather than silent.
+ * - **Second**: the attribution is PERSISTED under `getProjectDataDir(cwd)`, so
+ *   a later session on the same project classifies X by name with no snapshot
+ *   at all.
+ *
+ * The dual also matters: a tool observed to change NOTHING twice stops being
+ * armed for the rest of the session. Without that, every `read`-shaped tool
+ * carrying a `path` field would pay for a snapshot on every single call, which
+ * is exactly the hot-path cost the net must not have. The settled sweep
+ * (#2430 item 3) remains the last-resort net for anything this latch stops
+ * watching.
+ *
+ * ## Lifetimes (catalog shape 17, shape 25)
+ *
+ * The session map and the loaded persisted set are SESSION state and are
+ * cleared by `resetMutationAttribution` from the `runtime-session.ts` reset
+ * block; `tests/support/session-state-registry.ts` registers them. The
+ * container lives in a process singleton, because a second module evaluation
+ * holding its own copy would re-emit the degradation record and re-write the
+ * persisted file from a stale view (catalog shape 25).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeFileAtomic } from "./atomic-write.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
+import { BoundedFifoMap } from "./bounded-cache.js";
+import { getProjectDataDir } from "./file-utils.js";
+import { getProcessSingleton } from "./process-singletons.js";
+/** Persisted-file schema version. A file of any other version is ignored. */
+export const MUTATION_ATTRIBUTION_FILE_VERSION = 1;
+/** File under `getProjectDataDir(cwd)` holding the learned attributions. */
+export const MUTATION_ATTRIBUTION_FILE = "observed-mutating-tools.json";
+/**
+ * Observations needed before an attribution is written to disk. One is enough
+ * to classify for THIS session (the observation itself proved it); a second is
+ * required before the claim outlives the session, so a single coincidental
+ * co-occurrence — an unrelated tool call that happened to overlap a background
+ * write — cannot durably mislabel a tool for every future session.
+ */
+export const PERSIST_AFTER_OBSERVATIONS = 2;
+/**
+ * Consecutive clean observations after which an UNATTRIBUTED tool stops being
+ * armed for the session. Two, not one: a mutating tool whose FIRST call
+ * happened to be a no-op (an edit that changed nothing) still gets a second
+ * chance.
+ */
+export const CLEAN_OBSERVATION_ARM_LIMIT = 2;
+/**
+ * Consecutive clean observations after which a SESSION-learned attribution is
+ * forgotten (#2449 review round 2, F4).
+ *
+ * The session map is a claim about a tool made from ONE disk observation, and
+ * a claim made from evidence has to be revisable by evidence. Three armed
+ * observations in a row where the tool's own target did not move is the
+ * signal that the first observation was a coincidence — a background write, a
+ * formatter, another agent — and the tool goes back to unattributed rather
+ * than staying mislabelled for the rest of the session.
+ *
+ * CONSECUTIVE is literal, and it is the run tracked by `ToolObservation.cleanRun`
+ * rather than the lifetime `clean` total (#2449 review round 3, S4): an
+ * observation the net could not COMPLETE — a truncated directory watch, a cut
+ * capture — is not evidence of cleanliness, so it breaks the run instead of
+ * voting in it.
+ *
+ * Higher than {@link CLEAN_OBSERVATION_ARM_LIMIT} on purpose: forgetting is
+ * the more consequential direction, so it takes strictly more evidence than
+ * merely deciding to stop watching. It applies only BEFORE persistence — an
+ * attribution that already earned {@link PERSIST_AFTER_OBSERVATIONS} is not
+ * armed any more, so nothing can un-learn it by accident.
+ */
+export const DEATTRIBUTE_AFTER_CLEAN_OBSERVATIONS = 3;
+/** Bound on distinct tool names remembered, in-memory and on disk. */
+export const MUTATION_ATTRIBUTION_MAX_TOOLS = 64;
+const ATTRIBUTION_FAMILY = "mutation-attribution";
+/**
+ * Bumped to 2 (#2449 review round 5, F3): `session` changed shape from a
+ * plain `Map` to a `BoundedFifoMap` without a version bump at the time, so a
+ * cell built by an older process (still alive in a multi-agent session, or
+ * surviving a hot reload) is adopted here as if it already had the newer
+ * shape. `getProcessSingleton`'s adoption check only compares the version
+ * NUMBER — it has no way to see that a v1 cell's `session` lacks
+ * `entriesArray()` — so every read of it throws, and there is no fallback:
+ * the mismatch is discovered mid-call, not at adoption (reviewer PROBE-A).
+ * The version bump makes `getProcessSingleton` discard the old-shaped cell
+ * and rebuild fresh instead of handing out a value this build cannot use.
+ */
+const ATTRIBUTION_VERSION = 2;
+function state() {
+    return getProcessSingleton(ATTRIBUTION_FAMILY, ATTRIBUTION_VERSION, () => ({
+        session: new BoundedFifoMap(MUTATION_ATTRIBUTION_MAX_TOOLS),
+        fromDisk: undefined,
+        primedCwd: undefined,
+    }));
+}
+function observationFor(toolName) {
+    const current = state().session.get(toolName);
+    if (current)
+        return current;
+    const created = {
+        mutating: 0,
+        clean: 0,
+        cleanRun: 0,
+        unverifiable: 0,
+        persisted: false,
+    };
+    state().session.set(toolName, created);
+    return created;
+}
+function attributionFilePath(cwd) {
+    return path.join(getProjectDataDir(cwd), MUTATION_ATTRIBUTION_FILE);
+}
+function isPersistedEntry(entry) {
+    const candidate = entry;
+    return (typeof candidate?.name === "string" &&
+        candidate.name.length > 0 &&
+        typeof candidate.observations === "number");
+}
+function readPersisted(cwd) {
+    try {
+        const raw = fs.readFileSync(attributionFilePath(cwd), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== MUTATION_ATTRIBUTION_FILE_VERSION)
+            return undefined;
+        if (!Array.isArray(parsed.tools))
+            return undefined;
+        return {
+            version: MUTATION_ATTRIBUTION_FILE_VERSION,
+            tools: parsed.tools
+                .filter(isPersistedEntry)
+                .slice(0, MUTATION_ATTRIBUTION_MAX_TOOLS)
+                .map((entry) => ({
+                name: entry.name,
+                observations: entry.observations,
+                lastSeen: typeof entry.lastSeen === "number" ? entry.lastSeen : 0,
+            })),
+        };
+    }
+    catch {
+        // Missing or corrupt file: start with nothing learned. Never throw — a
+        // broken attribution file must not break a session.
+        return undefined;
+    }
+}
+/**
+ * Adopt this project's persisted attributions. Called once from the
+ * `session_start` reset block, AFTER `resetMutationAttribution`, so a session
+ * classifies a tool a previous session learned about with no snapshot.
+ *
+ * Synchronous by design: `classifyMutatingTool` is synchronous and on the
+ * tool-event hot path, so the file is read once at a session boundary rather
+ * than lazily from inside classification.
+ */
+export function primePersistedMutationAttribution(cwd) {
+    const current = state();
+    current.primedCwd = cwd;
+    current.fromDisk = new Set();
+    if (!cwd)
+        return;
+    const file = readPersisted(cwd);
+    if (!file)
+        return;
+    for (const entry of file.tools)
+        current.fromDisk.add(entry.name);
+}
+/**
+ * `"session"` or `"persisted"` when this tool has been attributed as mutating,
+ * `undefined` otherwise. This is the lookup `classifyMutatingTool` consults for
+ * its `provenance: "learned"` branch.
+ */
+export function lookupLearnedMutatingTool(toolName) {
+    const current = state();
+    if ((current.session.get(toolName)?.mutating ?? 0) > 0)
+        return "session";
+    return current.fromDisk?.has(toolName) === true ? "persisted" : undefined;
+}
+/**
+ * Whether a SESSION attribution exists but has not yet earned persistence.
+ *
+ * This is the window in which the tool IS classified by name (so #2430's
+ * second acceptance criterion holds) and is STILL watched, because the second
+ * observation that makes the attribution durable can only come from another
+ * real disk diff. `runtime-tool-call.ts` consults this alongside
+ * `classifyMutatingTool` when deciding whether to arm.
+ */
+export function isProvisionalLearnedAttribution(toolName) {
+    const current = state();
+    if (current.fromDisk?.has(toolName) === true)
+        return false;
+    const observation = current.session.get(toolName);
+    if (!observation || observation.persisted)
+        return false;
+    return (observation.mutating > 0 &&
+        observation.mutating < PERSIST_AFTER_OBSERVATIONS);
+}
+/**
+ * Whether a call to `toolName` should still pay for a snapshot.
+ *
+ * Three states, in order:
+ *
+ * 1. **Attributed durably** — persisted this session, or adopted from disk at
+ *    `session_start`. Never armed: classification no longer needs the diff.
+ * 2. **Attributed provisionally** — one observation, not yet persisted. STILL
+ *    armed. The first cut returned `false` the moment
+ *    `lookupLearnedMutatingTool` went non-`undefined`, which is after ONE
+ *    observation, so `PERSIST_AFTER_OBSERVATIONS = 2` was unreachable on the
+ *    production path and no attribution ever reached disk (#2449 review round
+ *    2, F2). The only test that "proved" persistence called
+ *    `noteObservedMutation` directly, so it proved the counter, not the path.
+ * 3. **Unattributed** — armed until observed clean
+ *    {@link CLEAN_OBSERVATION_ARM_LIMIT} times (it is not an edit tool, and
+ *    re-proving that on every call is the hot-path cost this latch removes).
+ */
+export function shouldArmObservationForTool(toolName) {
+    const observation = state().session.get(toolName);
+    if ((observation?.mutating ?? 0) > 0)
+        return isProvisionalLearnedAttribution(toolName);
+    if (state().fromDisk?.has(toolName) === true)
+        return false;
+    return (observation?.clean ?? 0) < CLEAN_OBSERVATION_ARM_LIMIT;
+}
+/**
+ * Record that a mutation was observed after `toolName` ran.
+ *
+ * Emits ONE `unclassified-mutating-tool` degradation per tool (the ledger's
+ * own once-key does the deduping), so a session report names every tool whose
+ * edits pi-lens could only find by watching the disk.
+ */
+export function noteObservedMutation(toolName, cwd) {
+    const observation = observationFor(toolName);
+    observation.mutating += 1;
+    observation.clean = 0;
+    observation.cleanRun = 0;
+    recordDegradationOnce({
+        kind: "unclassified-mutating-tool",
+        subject: toolName,
+        reason: "tool mutated a tracked file but matched no built-in name and no mutation shape adapter; classified by disk observation (#2430)",
+    });
+    let persisted = false;
+    if (observation.mutating >= PERSIST_AFTER_OBSERVATIONS &&
+        !observation.persisted) {
+        persisted = persistAttribution(toolName, cwd, observation.mutating);
+        observation.persisted = persisted;
+    }
+    return { observations: observation.mutating, persisted };
+}
+/**
+ * Record that an armed observation found the tool's own target unchanged.
+ *
+ * Also the DE-ATTRIBUTION point (#2449 review round 2, F4). A session
+ * attribution that then goes {@link DEATTRIBUTE_AFTER_CLEAN_OBSERVATIONS}
+ * consecutive armed observations without its target moving is withdrawn: the
+ * one observation behind it was a coincidence, and leaving it standing would
+ * keep a read-shaped tool labelled as mutating for the rest of the session.
+ *
+ * Withdrawing resets BOTH counters (#2449 review round 3, S4). The first cut
+ * zeroed `mutating` and left `clean` at three, which is a state no evidence
+ * can leave: `shouldArmObservationForTool` reads three cleans as "not worth
+ * watching", so the tool was never armed again and therefore could never be
+ * RE-learned — a terminal verdict reached from three no-ops, dressed up as a
+ * revisable one. Zeroing both puts the tool back exactly where it started, and
+ * that is bounded, not unbounded: two more cleans latch the watching off again
+ * through the ordinary {@link CLEAN_OBSERVATION_ARM_LIMIT} path, and only a
+ * real disk diff re-attributes it.
+ */
+export function noteObservedClean(toolName) {
+    const observation = observationFor(toolName);
+    observation.clean += 1;
+    observation.cleanRun += 1;
+    if (observation.mutating > 0 &&
+        !observation.persisted &&
+        observation.cleanRun >= DEATTRIBUTE_AFTER_CLEAN_OBSERVATIONS) {
+        observation.mutating = 0;
+        observation.clean = 0;
+        observation.cleanRun = 0;
+    }
+}
+/**
+ * Record that an armed observation could not be COMPLETED (#2449 review round
+ * 3, S3/S4): the tool named a directory wider than the net may watch, or a
+ * bound cut the capture short.
+ *
+ * This is deliberately neither a clean nor a mutating observation. It does not
+ * advance {@link CLEAN_OBSERVATION_ARM_LIMIT}, because "we stopped looking" is
+ * not evidence the tool changes nothing — scoring it as clean is exactly how a
+ * real codemod over an 84-entry directory de-attributed itself. And it BREAKS
+ * the de-attribution run, because three-in-a-row means three, not two plus a
+ * shrug.
+ *
+ * The cost that buys: a tool whose target is permanently too wide stays armed
+ * for the session. That is bounded per call (one `readdir` plus at most
+ * {@link MUTATION_ATTRIBUTION_MAX_TOOLS}-independent
+ * `OBSERVED_TARGET_DIR_MAX_ENTRIES` stat/hash pairs) and bounded per turn by
+ * the net's own wall-clock budget, and it is the direction that loses a little
+ * time rather than a real mutation.
+ */
+export function noteObservedUnverifiable(toolName) {
+    const observation = observationFor(toolName);
+    observation.unverifiable += 1;
+    observation.cleanRun = 0;
+}
+function persistAttribution(toolName, cwd, observations) {
+    const root = cwd ?? state().primedCwd;
+    if (!root)
+        return false;
+    try {
+        const existing = readPersisted(root) ?? {
+            version: MUTATION_ATTRIBUTION_FILE_VERSION,
+            tools: [],
+        };
+        const tools = existing.tools.filter((entry) => entry.name !== toolName);
+        tools.push({ name: toolName, observations, lastSeen: Date.now() });
+        // Oldest-first drop keeps the cap honest without a second data structure.
+        tools.sort((a, b) => a.lastSeen - b.lastSeen);
+        const bounded = tools.slice(-MUTATION_ATTRIBUTION_MAX_TOOLS);
+        const dir = getProjectDataDir(root);
+        fs.mkdirSync(dir, { recursive: true });
+        writeFileAtomic(path.join(dir, MUTATION_ATTRIBUTION_FILE), JSON.stringify({
+            version: MUTATION_ATTRIBUTION_FILE_VERSION,
+            tools: bounded,
+        }));
+        state().fromDisk?.add(toolName);
+        return true;
+    }
+    catch {
+        // Persistence is an optimization for LATER sessions; this session already
+        // has the attribution in memory, so a failed write must not break it.
+        return false;
+    }
+}
+/**
+ * Session boundary (#2430). Clears the learned map and the adopted disk set so
+ * a new session re-primes from disk instead of inheriting the previous
+ * project's attributions — a `pi --session` switch can change project root.
+ */
+export function resetMutationAttribution() {
+    const current = state();
+    current.session.clear();
+    current.fromDisk = undefined;
+    current.primedCwd = undefined;
+}
+/** Test seam: the learned map, as plain data. */
+export function _mutationAttributionSnapshotForTests() {
+    const current = state();
+    return {
+        session: current.session
+            .entriesArray()
+            .map(([name, obs]) => [name, { ...obs }]),
+        fromDisk: current.fromDisk ? [...current.fromDisk] : undefined,
+    };
+}

package/node_modules/pi-lens/dist/clients/mutation-bridge.js

@@ -0,0 +1,240 @@
+/**
+ * Generic mutation-recording bridge for pi-lens (#2423).
+ *
+ * ## Trust model — explicitly advisory
+ *
+ * Sibling of `clients/read-bridge.ts` and it inherits that module's trust
+ * model verbatim: any code sharing this Node.js process already has full access
+ * to pi-lens's internal state, so the bridge is not a security boundary. What
+ * it provides is a stable API surface, one place for flag and scope checks, and
+ * defensive validation that catches integration bugs early.
+ *
+ * ## What it is for
+ *
+ * `clients/mutating-tool.ts` classifies mutations pi-lens SEES as tool events.
+ * A producer that writes a file some other way — a co-process extension with
+ * its own registered tool, or pi-lens's own `ast_grep_replace` running
+ * `--update-all` — is invisible to that path. It records the mutation here
+ * instead, and the same downstream bookkeeping runs: read-guard staleness
+ * stamp, turn-state modified ranges, an attributed change-log receipt, and a
+ * DEFERRED autofix and format pass at `agent_settled`.
+ *
+ * Deferred, not immediate, is deliberate: a bulk rewrite usually touches many
+ * files, and formatting each one as it lands fights the producer that is still
+ * writing.
+ *
+ * Protocol (producer side)
+ * ────────────────────────
+ *
+ *   const bridge = (globalThis as any)[Symbol.for("pi-lens:mutation-bridge")];
+ *   bridge?.recordMutation({
+ *     filePath,      // absolute path
+ *     kind,          // "write" (whole file authored) or "edit" (part changed)
+ *     touchedLines,  // optional [start, end], 1-based inclusive
+ *     editRanges,    // optional [start, end][] for a scattered multi-range edit
+ *     consumer,      // optional identifier, e.g. "my-extension"
+ *   });
+ *
+ * Check `bridge.version` before calling. A bridge whose version you do not
+ * recognize is unsupported. Calling before pi-lens is loaded, or when the guard
+ * is disabled, is safe: the bridge is absent or the call is dropped.
+ *
+ * `recordMutation` returns `true` when pi-lens took the record and `false` when
+ * it dropped it (malformed payload, out-of-scope path, or a bookkeeping error),
+ * so a producer can count its own drops.
+ *
+ * Protocol (registration side, internal to pi-lens)
+ * ──────────────────────────────────────────────────
+ * `registerMutationBridge` is called once from the extension factory, next to
+ * `registerReadBridge`, behind a module-level singleton guard so factory
+ * re-activations do not mount a second bridge. Every dep is a GETTER resolved
+ * at call time, so a replaced runtime or cache manager is picked up without
+ * re-registration — the same live-getter discipline the read bridge uses.
+ */
+import { classifyBridgeMutation, } from "./mutating-tool.js";
+import { noteMutationHandled } from "./observed-mutation.js";
+import { getProcessBridge, registerProcessBridge } from "./process-bridge.js";
+/** Stable Symbol key — identical across module reloads in the same process. */
+export const MUTATION_BRIDGE_KEY = Symbol.for("pi-lens:mutation-bridge");
+function isValidRange(value) {
+    if (!Array.isArray(value) || value.length !== 2)
+        return false;
+    const [start, end] = value;
+    return (typeof start === "number" &&
+        typeof end === "number" &&
+        Number.isInteger(start) &&
+        Number.isInteger(end) &&
+        start >= 1 &&
+        end >= start);
+}
+/**
+ * Validate a raw entry from an untrusted caller. Deliberately lightweight, for
+ * the same reason `read-bridge.ts` gives: this is an advisory protocol between
+ * same-process extensions, so the goal is catching typos and bad numbers rather
+ * than enforcing a boundary.
+ */
+export function isValidMutationEntry(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const e = entry;
+    if (typeof e["filePath"] !== "string" || e["filePath"] === "")
+        return false;
+    const kind = e["kind"];
+    if (kind !== "write" && kind !== "edit")
+        return false;
+    if (e["touchedLines"] !== undefined && !isValidRange(e["touchedLines"]))
+        return false;
+    const editRanges = e["editRanges"];
+    if (editRanges !== undefined) {
+        if (!Array.isArray(editRanges) || editRanges.length === 0)
+            return false;
+        if (!editRanges.every(isValidRange))
+            return false;
+    }
+    if (e["consumer"] !== undefined && typeof e["consumer"] !== "string")
+        return false;
+    if (e["importsChanged"] !== undefined &&
+        typeof e["importsChanged"] !== "boolean")
+        return false;
+    if (e["deferAutofix"] !== undefined && typeof e["deferAutofix"] !== "boolean")
+        return false;
+    // #2430: only the observational net's two values are accepted. An unknown
+    // string is rejected rather than silently downgraded, so a producer that
+    // invents a provenance learns about it instead of publishing a wrong one.
+    const provenance = e["provenance"];
+    if (provenance !== undefined &&
+        provenance !== "observed" &&
+        provenance !== "settled-sweep")
+        return false;
+    return true;
+}
+/**
+ * The one range the change log records for this mutation. A multi-range edit
+ * records its bounding box, matching how `runtime-tool-result.ts` collapses a
+ * multi-hunk diff (`singleRange`) — the change log carries one range per entry.
+ */
+function resolveChangedRange(classification, deps, filePath) {
+    if (classification.touchedLines) {
+        const [start, end] = classification.touchedLines;
+        return { start, end };
+    }
+    if (classification.editRanges && classification.editRanges.length > 0) {
+        const starts = classification.editRanges.map(([start]) => start);
+        const ends = classification.editRanges.map(([, end]) => end);
+        return { start: Math.min(...starts), end: Math.max(...ends) };
+    }
+    // No range stated. A write replaced the whole file, and an edit whose ranges
+    // the producer could not name is treated the same way: the safe
+    // over-approximation is the entire file, never an empty set.
+    return { start: 1, end: Math.max(1, deps.countFileLines(filePath)) };
+}
+/**
+ * The mutation-recording body, exported so tests drive it against a real
+ * `RuntimeCoordinator` and `CacheManager` without mounting the global
+ * singleton.
+ */
+export function recordMutationThroughSeam(entry, deps) {
+    if (!isValidMutationEntry(entry)) {
+        deps.dbg?.("mutation_bridge: dropped malformed entry");
+        return false;
+    }
+    if (!deps.isRecordable(entry.filePath)) {
+        deps.dbg?.(`mutation_bridge: out of scope ${entry.filePath}`);
+        return false;
+    }
+    const classification = classifyBridgeMutation(entry);
+    const filePath = entry.filePath;
+    const runtime = deps.getRuntime();
+    const projectRoot = deps.getProjectRoot();
+    const dispatchCwd = deps.getDispatchCwd(filePath);
+    try {
+        // 1. Staleness stamp: the file changed under pi-lens, so a later edit is
+        //    judged by read coverage rather than by this write. #2465: gated on
+        //    `shouldStampReadGuard` (the `no-read-guard` flag) ALONE — the
+        //    `isRecordable` check above already passed, so the write itself is
+        //    still bookkept below whether or not the stamp fires.
+        if (deps.shouldStampReadGuard?.() ?? true) {
+            runtime.readGuard?.recordWritten?.(filePath);
+        }
+        // 2. Turn state: this is the insert that leaves `turn-state.json` `files`
+        //    non-empty for a mutation no `tool_result` described. `importsChanged`
+        //    defaults to `false` (the historical, pre-#2450 behavior every
+        //    existing producer that doesn't compute it still gets); a producer
+        //    that DOES know the real value threads it through the entry instead
+        //    of this seam silently understating it (#2450 review round 2, F1).
+        const changedRange = resolveChangedRange(classification, deps, filePath);
+        deps
+            .getCacheManager()
+            .addModifiedRange?.(filePath, changedRange, entry.importsChanged ?? false, projectRoot, runtime.telemetrySessionId);
+        // 3. Attributed change-log receipt. The source carries the producer's
+        //    identity instead of collapsing onto `agent-edit`, so a report can
+        //    tell an extension's rewrite apart from the model's own edit.
+        runtime.recordProjectMutation?.({
+            filePath,
+            source: `agent-tool:${classification.toolName}`,
+            cwd: projectRoot,
+            changedRange,
+            onAppendError: (err) => deps.dbg?.(`mutation_bridge: change log append failed: ${err}`),
+        });
+        // #2430: this file is now accounted for this run, so the `agent_settled`
+        // sweep re-baselines it instead of reporting the same bytes as drift no
+        // tool call explains. Every in-process producer passes through here, so
+        // this is the one place that has to say so.
+        //
+        // It sits OUTSIDE the `deferAutofix` guard below and must stay there
+        // (#2465). "pi-lens accounted for this write" and "pi-lens will also
+        // format this file later" are different questions: the LSP
+        // mutation-bridge fallback passes `deferAutofix: false` precisely
+        // because an LSP-applied edit is not this seam's to format, and it is
+        // still a write pi-lens recorded. Move this inside the guard and every
+        // such write is re-read by the settled sweep as unattributed drift.
+        noteMutationHandled(filePath);
+        // 4. Deferred autofix and format at `agent_settled` — never immediate.
+        //    Skippable per entry (`deferAutofix: false`, #2450 review round 2 F3):
+        //    the LSP mutation-bridge fallback (`clients/lsp-mutation.ts`) sets
+        //    this because `bookkeepLspMutation`'s direct path never enqueues a
+        //    deferred pass for an LSP-applied edit — the two branches must stay
+        //    behaviorally equivalent for the same write. Every other producer
+        //    (ast_grep_replace, a third-party extension) omits the field and
+        //    keeps deferring, unchanged.
+        if (entry.deferAutofix !== false) {
+            for (const kind of ["autofix", "format"]) {
+                runtime.deferMutation?.(filePath, dispatchCwd, classification.toolName, projectRoot, kind, runtime.telemetrySessionId, projectRoot);
+            }
+        }
+    }
+    catch (err) {
+        // Bookkeeping must never break a producer's own write path.
+        deps.dbg?.(`mutation_bridge: recording failed for ${filePath}: ${err}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Mount the bridge singleton. Call once from inside the extension factory,
+ * protected by the caller's module-level flag. Subsequent calls are no-ops
+ * (first-wins, `clients/process-bridge.ts` owns the mount body — see that
+ * module's header, #2437).
+ */
+export function registerMutationBridge(deps) {
+    registerProcessBridge(MUTATION_BRIDGE_KEY, () => ({
+        version: 1,
+        recordMutation(entry) {
+            return recordMutationThroughSeam(entry, deps);
+        },
+    }));
+}
+/**
+ * The mounted bridge, or `undefined` when pi-lens has not registered one (or
+ * a differently-versioned bridge is mounted, or the mounted value is missing
+ * `recordMutation`).
+ *
+ * In-repo producers use this instead of reaching for `globalThis` themselves,
+ * so there is one spelling of the key and one version check.
+ */
+export function getMutationBridge() {
+    const candidate = getProcessBridge(MUTATION_BRIDGE_KEY, 1);
+    return typeof candidate?.recordMutation === "function"
+        ? candidate
+        : undefined;
+}