@herbertgao/pi-extensions 2026.10.1 → 2026.10.2

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

@@ -1,1324 +0,0 @@
-import { randomBytes } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { logCascade } from "./cascade-logger.js";
-import { appendProjectChange, } from "./project-changes.js";
-import { normalizeMapKey, pathsEqual } from "./path-utils.js";
-import { PathKeyedMap } from "./path-keyed-map.js";
-import { BoundedLruCache } from "./bounded-cache.js";
-import { PartialApplyRecordStore } from "./partial-edit-apply.js";
-import { ReadGuard } from "./read-guard.js";
-import { RUNTIME_CONFIG } from "./runtime-config.js";
-import { TurnSummaryCollector } from "./turn-summary.js";
-import { deriveProviderFromModelId } from "./model-provider.js";
-import { beginTurnContext, setTurnContextSession } from "./turn-context.js";
-import { recordDegradationOnce } from "./degradation-ledger.js";
-/** Keep deferred cascade admission bounded without dropping late findings. */
-export const MAX_PENDING_CASCADE_RUNS = 32;
-/**
- * Bounded receipt ring capacity (defect shape 9: bound the axis that grows —
- * per-mutation receipts are unbounded across a long session). Oldest receipts
- * evict first; eviction is counted and surfaced via
- * {@link RuntimeCoordinator.droppedMutationReceiptCount} so a consumer that
- * needs a complete window knows the answer was truncated, never silently
- * incomplete (#936 honesty rule).
- */
-const MAX_MUTATION_RECEIPTS = 512;
-/**
- * Bound on in-flight tool_call → tool_result correlations. A tool_result
- * follows its tool_call almost immediately, so this only needs to cover
- * calls genuinely in flight; sized generously above any realistic
- * in-flight-batch width so a slow paired result is never evicted before use.
- */
-const TOOL_CALL_ATTRIBUTION_CAPACITY = 256;
-/**
- * A recorded attribution older than this is treated as expired (as if it
- * were never recorded) rather than trusted — defense in depth against a host
- * that reuses a call id, or a pathologically delayed/duplicated tool_result,
- * outliving the LRU capacity bound. Generous relative to any real tool
- * round-trip; only guards against genuine identity reuse, not slow tools.
- */
-const TOOL_CALL_ATTRIBUTION_TTL_MS = 5 * 60_000;
-export class RuntimeCoordinator {
-    _projectRoot = normalizeMapKey(process.cwd());
-    _sessionGeneration = 0;
-    _sessionStartedAt = Date.now();
-    _errorDebtBaseline = null;
-    _pipelineCrashCounts = new Map();
-    _cachedExports = new Map();
-    _startupScansInFlight = new Map();
-    _cascadeRuns = [];
-    _turnEndCascadeSettleStarts = new Map();
-    _nextCascadeSettleToken = 0;
-    // Cascade computes are kicked off unawaited by the pipeline (#450); their
-    // promises park here until turn_end drains them via settleCascadeRuns. Each is
-    // guaranteed non-rejecting by the pipeline's .catch.
-    _pendingCascadeRuns = [];
-    _cascadeSessionStats = {
-        runs: 0,
-        diagnosticsSurfaced: 0,
-        coldSnapshotTouches: 0,
-    };
-    _complexityBaselines = new Map();
-    _fixedThisTurn = new PathKeyedMap(normalizeMapKey);
-    _writtenThisTurn = new PathKeyedMap(normalizeMapKey);
-    _autofixDemotedThisTurn = new PathKeyedMap(normalizeMapKey);
-    _reportedThisTurn = new Set();
-    _mutationReceipts = [];
-    _droppedMutationReceipts = 0;
-    _projectRulesScan = {
-        rules: [],
-        hasCustomRules: false,
-    };
-    _telemetrySessionId = `lens-${Date.now().toString(36)}`;
-    _lifecycleReason;
-    _hasStableSessionId = false;
-    _telemetryModel = "unknown";
-    // Raw model/provider identity, separate from the combined `provider/model`
-    // display string above — worklog/disposition attribution (#1448) wants the
-    // two fields apart, blank when the host never supplied them. `_telemetryProvider`
-    // is the explicit host value when given, else derived from the model id
-    // (deriveProviderFromModelId, blank on ambiguity — never guessed).
-    _telemetryModelId = "";
-    _telemetryProvider = "";
-    // True once a host has supplied an explicit provider this session. An
-    // explicit provider is never downgraded by a derivation from a later
-    // model-only call; a DERIVED provider, by contrast, is re-derived on
-    // every model-only call so a mid-session model switch (e.g. gpt-5-mini →
-    // claude-sonnet-4-5) doesn't leave a stale provider from the old model.
-    _telemetryProviderIsExplicit = false;
-    _turnIndex = 0;
-    _writeIndex = 0;
-    _projectSeq = 0;
-    _turnStartProjectSeq = 0;
-    _fileSeq = new Map();
-    // File key → the projectSeq value at that file's most recent bump (#451). Lets
-    // the review-graph builder ask "which files changed since I last built?" and
-    // skip its per-build O(project) walk+stat sweep when only pi-observed edits
-    // occurred. Keyed identically to _fileSeq (normalizeMapKey + path.resolve).
-    _fileLastProjectSeq = new Map();
-    _gitGuardHasBlockers = false;
-    _gitGuardSummary = "";
-    _gitGuardCacheUnknownReason;
-    callGraph = null;
-    wordIndex = null;
-    _readGuard = null;
-    _pendingDeferredMutations = new PathKeyedMap(normalizeMapKey);
-    /** tool_call → tool_result path-attribution correlation (#1642). */
-    _toolCallAttributions = new BoundedLruCache(TOOL_CALL_ATTRIBUTION_CAPACITY);
-    _lspReadWarmState = new Map();
-    _pendingInlineBlockers = new PathKeyedMap(normalizeMapKey);
-    _actionableWarningsThisTurn = new Map();
-    _codeQualityWarningsThisTurn = new Map();
-    // #484: opt-in per-RUN summary of diagnostics/autofixes/formats,
-    // accumulated across the run's turns and consumed once at the
-    // agent_settled quiet window. The collector itself is always constructed
-    // (cheap, empty Map) but callers gate recording behind the
-    // `lens-turn-summary` flag so it's a true no-op when the feature is off.
-    _turnSummary = new TurnSummaryCollector();
-    // #2402/#1053: session-scoped applied-edit records for exact-retry
-    // recognition. Both producers (partial-apply commit, full native-edit
-    // success) write here; the preflight consults it before declaring an
-    // oldText miss, so an identical retry never re-executes a committed write.
-    partialApplyRecords = new PartialApplyRecordStore();
-    resetForSession(startedAt = Date.now()) {
-        this._sessionGeneration += 1;
-        this._sessionStartedAt = startedAt;
-        this._complexityBaselines.clear();
-        this._pipelineCrashCounts.clear();
-        this._cachedExports.clear();
-        this.wordIndex = null;
-        this._startupScansInFlight.clear();
-        this._cascadeRuns = [];
-        this._pendingCascadeRuns = [];
-        this._turnEndCascadeSettleStarts.clear();
-        this._cascadeSessionStats = {
-            runs: 0,
-            diagnosticsSurfaced: 0,
-            coldSnapshotTouches: 0,
-        };
-        this._fixedThisTurn.clear();
-        this._writtenThisTurn.clear();
-        this._autofixDemotedThisTurn.clear();
-        this._reportedThisTurn.clear();
-        this._mutationReceipts = [];
-        this._droppedMutationReceipts = 0;
-        this._telemetrySessionId = `lens-${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
-        this._hasStableSessionId = false;
-        this._telemetryModel = "unknown";
-        this._telemetryModelId = "";
-        this._telemetryProvider = "";
-        this._telemetryProviderIsExplicit = false;
-        this._turnIndex = 0;
-        this._writeIndex = 0;
-        this._projectSeq = 0;
-        this._turnStartProjectSeq = 0;
-        this._fileSeq.clear();
-        this._fileLastProjectSeq.clear();
-        this._gitGuardHasBlockers = false;
-        this._gitGuardSummary = "";
-        this._gitGuardCacheUnknownReason = undefined;
-        this._readGuard = null;
-        this._pendingDeferredMutations.clear();
-        // #1642 F5: every sibling correlation/state map is cleared here. A
-        // per-session-numbered host reusing tool-call ids across sessions must
-        // not let a NEW session inherit a DEAD session's recorded skip verdict.
-        this._toolCallAttributions.clear();
-        this._lspReadWarmState.clear();
-        this._pendingInlineBlockers.clear();
-        this._actionableWarningsThisTurn.clear();
-        this._codeQualityWarningsThisTurn.clear();
-        this._turnSummary.clear();
-        // #2402: an applied-edit record is a fact about the session that applied
-        // it; a new session must re-resolve identical payloads from content.
-        this.partialApplyRecords.clear();
-    }
-    get sessionStartedAt() {
-        return this._sessionStartedAt;
-    }
-    get cascadeSessionStats() {
-        return this._cascadeSessionStats;
-    }
-    recordCascadeRun(diagnosticsSurfaced, coldSnapshotTouches) {
-        this._cascadeSessionStats.runs += 1;
-        this._cascadeSessionStats.diagnosticsSurfaced += diagnosticsSurfaced;
-        this._cascadeSessionStats.coldSnapshotTouches += coldSnapshotTouches;
-    }
-    /**
-     * Record the turn-end policy verdict on every live inline-blocker record
-     * (#3248): `true` for a file whose every blocker the policy suppressed,
-     * `false` for every other record in the map.
-     *
-     * ONE writer, rewriting the WHOLE axis each turn end, so the verdict can
-     * never outlive the pass that made it: a record demoted since, or one whose
-     * survivors came back because the file's bytes moved under a content-bound
-     * anchor, is cleared by the same call that sets its sibling. A fresh
-     * dispatch replaces the record wholesale (`recordInlineBlockers`), so a NEW
-     * blocker is never born pre-suppressed (#1198 ordering).
-     *
-     * @returns how many records this call CHANGED — 0 means the gate's view of
-     * the map is already what the policy just decided.
-     */
-    applyInlineBlockerPolicyVerdicts(suppressedFilePaths) {
-        const suppressed = new Set(suppressedFilePaths.map((filePath) => path.resolve(filePath)));
-        let changed = 0;
-        for (const [key, entry] of this._pendingInlineBlockers.entries()) {
-            const policySuppressed = suppressed.has(path.resolve(entry.filePath));
-            if (!!entry.policySuppressed === policySuppressed)
-                continue;
-            this._pendingInlineBlockers.set(key, { ...entry, policySuppressed });
-            changed += 1;
-        }
-        return changed;
-    }
-    updateGitGuardStatus(hasBlockers, output) {
-        // The status is an aggregate over the current per-file map. A clean B
-        // result must not erase an unresolved A result; the pipeline records/clears
-        // the edited file immediately before this method runs.
-        // #3248: every live record except one whose whole blocker set the
-        // turn-end disposition policy suppressed. The record itself stays in the
-        // map — the policy is content-bound and re-derived from the record's
-        // diagnostics at every turn end, so dropping it there would be silencing
-        // rather than filtering (AGENTS.md shape 10); it just stops counting for
-        // the gate the agent was shown nothing for.
-        const blocking = this.getInlineBlockersSnapshot().filter((entry) => !entry.policySuppressed);
-        this._gitGuardHasBlockers = hasBlockers || blocking.length > 0;
-        if (!this._gitGuardHasBlockers) {
-            this._gitGuardSummary = "";
-            return;
-        }
-        const firstLine = output
-            .split("\n")
-            .map((line) => line.trim())
-            .find((line) => line.length > 0);
-        const summaries = blocking
-            .map((entry) => entry.summary.trim())
-            .filter(Boolean);
-        this._gitGuardSummary = (summaries[0] ??
-            firstLine ??
-            "Unresolved blockers detected").slice(0, 160);
-    }
-    get gitGuardHasBlockers() {
-        return this._gitGuardHasBlockers;
-    }
-    get gitGuardSummary() {
-        return this._gitGuardSummary;
-    }
-    markGitGuardCacheUnknown(reason) {
-        this._gitGuardCacheUnknownReason = reason;
-    }
-    clearGitGuardCacheUnknown() {
-        this._gitGuardCacheUnknownReason = undefined;
-    }
-    get gitGuardCacheUnknownReason() {
-        return this._gitGuardCacheUnknownReason;
-    }
-    beginTurn() {
-        // #1443: runs sitting here at turn_start were appended AFTER the last
-        // turn_end drained them (consumeCascadeRuns) — the quiet-window reconcile's
-        // late re-injection (`onResolvedFound`, clients/lsp/cascade-tier.ts) lands
-        // in exactly that window. Wiping them dead-ended that delivery path: the
-        // finding was computed, formatted, appended, and then deleted before any
-        // turn_end could render it. Carry them into THIS turn instead, exactly
-        // once: `carriedTurns` is stamped on the way through and a run that the
-        // next turn_end still did not consume is dropped here with a log line
-        // rather than queued forever (a stale finding must not outlive the state
-        // it describes, and an unbounded queue would replay it every turn).
-        this._cascadeRuns = this._cascadeRuns.flatMap((run) => {
-            const carriedTurns = (run.carriedTurns ?? 0) + 1;
-            if (carriedTurns > 1) {
-                logCascade({
-                    phase: "cascade_carry_over_drop",
-                    filePath: run.filePath,
-                    neighborCount: run.neighborCount,
-                    diagnosticCount: run.diagnosticCount,
-                    metadata: { carriedTurns, turnIndex: this._turnIndex },
-                });
-                return [];
-            }
-            return [{ ...run, carriedTurns }];
-        });
-        // _pendingCascadeRuns is deliberately NOT cleared here: a cascade compute
-        // still in flight past last turn_end's settle cap (fresh graph builds have
-        // measured up to ~19s) must surface on the NEXT turn_end, not be dropped —
-        // pre-#450 those findings were always awaited, never lost. Session reset
-        // still clears it.
-        // Inline blockers are session-scoped per-file state. They are cleared only
-        // when that file is re-analyzed clean or the session resets; a new turn must
-        // not let a clean unrelated file erase an unresolved blocker.
-        this._actionableWarningsThisTurn.clear();
-        this._codeQualityWarningsThisTurn.clear();
-        // _turnSummary is deliberately NOT cleared here (#484 rework): the
-        // summary entry is emitted once per RUN at the agent_settled quiet
-        // window (sendMessage during a live stream would STEER the agent, and
-        // turn_end can fire mid-stream), so the collector must accumulate
-        // across the run's turns. It is cleared only by consume() at emit and
-        // by resetForSession().
-        this._turnStartProjectSeq = this._projectSeq;
-        this._turnIndex += 1;
-        beginTurnContext(this._telemetrySessionId);
-        this._writeIndex = 0;
-        this._reportedThisTurn.clear();
-        this._writtenThisTurn.clear();
-        this._autofixDemotedThisTurn.clear();
-    }
-    /**
-     * THE one mutation seam. Every producer of an in-project file mutation —
-     * native write/edit, recognized bash writes, format/autofix, LSP workspace
-     * edits, and (phase 2) opaque script-write recovery — records through here,
-     * once: it bumps the seq store (`bumpFileSeq`), appends a bounded attributed
-     * receipt, and optionally appends the durable change-log entry. Consumers
-     * derive from `getFilesChangedSince` / `getMutationsSince`; no producer or
-     * consumer may hand-roll a parallel bump+log pairing (#2000 phase 1).
-     *
-     * Receipt recording never throws; change-log append failures route to
-     * `onAppendError` (default: swallowed) so telemetry cannot break dispatch.
-     */
-    recordProjectMutation(args) {
-        const { projectSeq, fileSeq, key } = this.bumpFileSeq(args.filePath);
-        if (this._mutationReceipts.length >= MAX_MUTATION_RECEIPTS) {
-            this._mutationReceipts.shift();
-            this._droppedMutationReceipts += 1;
-        }
-        this._mutationReceipts.push({
-            seq: projectSeq,
-            // Reuse the bump's normalized key (a realpath syscall: ~200us on
-            // Windows, ~1.8us on POSIX since #3098) — never re-derive it here.
-            filePath: key,
-            source: args.source,
-            turnIndex: this._turnIndex,
-            ts: Date.now(),
-        });
-        if (args.cwd !== undefined) {
-            try {
-                appendProjectChange(args.cwd, {
-                    seq: projectSeq,
-                    timestamp: new Date().toISOString(),
-                    sessionId: this.telemetrySessionId,
-                    turnIndex: this.turnIndex,
-                    source: args.source,
-                    filePath: path.resolve(args.filePath),
-                    fileSeq,
-                    changedRange: args.changedRange,
-                });
-            }
-            catch (err) {
-                args.onAppendError?.(err);
-            }
-        }
-        return { projectSeq, fileSeq };
-    }
-    /**
-     * Attributed mutations whose seq is strictly after `seq` — the receipt-level
-     * counterpart of {@link getFilesChangedSince}. Bounded: entries evicted by
-     * the ring cap are gone; compare `droppedMutationReceiptCount` against zero
-     * before treating the result as a complete window.
-     */
-    getMutationsSince(seq) {
-        // Shallow copies: a consumer mutating a returned receipt must not
-        // corrupt the ring's internal state.
-        return this._mutationReceipts
-            .filter((r) => r.seq > seq)
-            .map((r) => ({ ...r }));
-    }
-    get droppedMutationReceiptCount() {
-        return this._droppedMutationReceipts;
-    }
-    /**
-     * Atomically records write/edit ordering before debounce can coalesce it.
-     *
-     * Takes the classified {@link MutationKind}, not a raw tool name (#2423):
-     * an edit-shaped tool pi-lens does not name still demotes this file to the
-     * deferred pass, which is the safe timing.
-     */
-    recordMutationToolReceipt(filePath, kind) {
-        if (kind === "write") {
-            this._writtenThisTurn.set(filePath, true);
-        }
-        else if (this._writtenThisTurn.has(filePath)) {
-            this._autofixDemotedThisTurn.set(filePath, true);
-            // A later edit establishes a new final state that must be eligible for
-            // the deferred pass even if the preceding write was fixed immediately.
-            this._fixedThisTurn.delete(filePath);
-        }
-        return {
-            autofixMode: kind === "edit" || this._autofixDemotedThisTurn.has(filePath)
-                ? "deferred"
-                : "immediate",
-        };
-    }
-    get reportedThisTurn() {
-        return this._reportedThisTurn;
-    }
-    nextWriteIndex() {
-        this._writeIndex += 1;
-        return this._writeIndex;
-    }
-    peekWriteIndex() {
-        return this._writeIndex;
-    }
-    setTelemetryIdentity(identity) {
-        if (identity.sessionId && identity.sessionId.trim()) {
-            this._telemetrySessionId = identity.sessionId.trim();
-            setTurnContextSession(this._telemetrySessionId);
-        }
-        const model = identity.model?.trim();
-        const provider = identity.provider?.trim();
-        if (model && provider) {
-            this._telemetryModel = `${provider}/${model}`;
-        }
-        else if (model) {
-            this._telemetryModel = model;
-        }
-        else if (provider) {
-            this._telemetryModel = provider;
-        }
-        if (model)
-            this._telemetryModelId = model;
-        if (provider) {
-            this._telemetryProvider = provider;
-            this._telemetryProviderIsExplicit = true;
-        }
-        else if (model && !this._telemetryProviderIsExplicit) {
-            // No explicit provider has ever been reported this session, so the
-            // provider is (still) a derivation — re-derive it from the CURRENT
-            // model id every time. Without this, a stale derived provider from
-            // an earlier model would survive a mid-session model switch (e.g.
-            // gpt-5-mini → claude-sonnet-4-5 with no explicit provider on
-            // either call) because the old "has any provider ever been set"
-            // guard treated the derived value as sticky. An explicit provider,
-            // once set, is never touched here regardless of later model calls.
-            this._telemetryProvider = deriveProviderFromModelId(model);
-        }
-    }
-    get telemetrySessionId() {
-        return this._telemetrySessionId;
-    }
-    /**
-     * Pin the session identity to pi's STABLE session id and record why this
-     * session started (#190). Called AFTER {@link resetForSession} (which assigns
-     * a fresh random id), so the stable id — when pi provides one via
-     * `ctx.sessionManager.getSessionId()` — wins and survives a quit→resume.
-     */
-    setSessionLifecycle(args) {
-        if (args.sessionId && args.sessionId.trim()) {
-            this._telemetrySessionId = args.sessionId.trim();
-            this._hasStableSessionId = true;
-        }
-        this._lifecycleReason = args.reason;
-    }
-    /** Why the current session started: new | resume | fork | reload | startup. */
-    get sessionLifecycleReason() {
-        return this._lifecycleReason;
-    }
-    /** True once a stable pi session id has been pinned (vs the random fallback). */
-    get hasStableSessionId() {
-        return this._hasStableSessionId;
-    }
-    get telemetryModel() {
-        return this._telemetryModel;
-    }
-    /** Raw model id (never the combined `provider/model` display string), blank
-     * when the host hasn't reported one this session. Worklog/disposition
-     * attribution (#1448) reads this, not {@link telemetryModel}. */
-    get telemetryModelId() {
-        return this._telemetryModelId;
-    }
-    /** Explicit host-reported provider, or a conservative derivation from the
-     * model id (see clients/model-provider.ts), blank when neither is known. */
-    get telemetryProviderId() {
-        return this._telemetryProvider;
-    }
-    get turnIndex() {
-        return this._turnIndex;
-    }
-    get projectSeq() {
-        return this._projectSeq;
-    }
-    get turnStartProjectSeq() {
-        return this._turnStartProjectSeq;
-    }
-    seedProjectSequence(projectSeq, fileSeqByPath) {
-        this._projectSeq = Math.max(0, Math.floor(projectSeq));
-        this._turnStartProjectSeq = this._projectSeq;
-        this._fileSeq.clear();
-        // Seeded per-file counters carry no projectSeq provenance, so start the
-        // changed-since map empty; the graph fast path simply won't fire until an
-        // in-process bump records a seq-stamped change (safe: falls back to sweep).
-        this._fileLastProjectSeq.clear();
-        for (const [filePath, seq] of fileSeqByPath ?? []) {
-            this._fileSeq.set(normalizeMapKey(path.resolve(filePath)), Math.max(0, seq));
-        }
-    }
-    bumpFileSeq(filePath) {
-        // normalizeMapKey costs a realpath syscall per call — ~200us on Windows,
-        // ~1.8us on POSIX since #3098; every caller that also needs the key must
-        // reuse this one instead of paying it twice.
-        const key = normalizeMapKey(path.resolve(filePath));
-        this._projectSeq += 1;
-        const fileSeq = (this._fileSeq.get(key) ?? 0) + 1;
-        this._fileSeq.set(key, fileSeq);
-        this._fileLastProjectSeq.set(key, this._projectSeq);
-        return { projectSeq: this._projectSeq, fileSeq, key };
-    }
-    /**
-     * Files whose most recent bump happened AFTER `seq` — i.e. every file the
-     * review graph would need to re-ingest to catch up from a build taken at
-     * projectSeq `seq` (#451). Returns NORMALIZED keys (normalizeMapKey +
-     * path.resolve), the same form the builder's fileSignatures map uses, so the
-     * caller can compare without re-normalizing.
-     */
-    getFilesChangedSince(seq) {
-        const changed = [];
-        for (const [key, lastSeq] of this._fileLastProjectSeq) {
-            if (lastSeq > seq)
-                changed.push(key);
-        }
-        return changed;
-    }
-    getFileSeq(filePath) {
-        return this._fileSeq.get(normalizeMapKey(path.resolve(filePath))) ?? 0;
-    }
-    getFileSeqEntries() {
-        return [...this._fileSeq.entries()];
-    }
-    get sessionGeneration() {
-        return this._sessionGeneration;
-    }
-    isCurrentSession(generation) {
-        return this._sessionGeneration === generation;
-    }
-    markStartupScanInFlight(name, generation) {
-        this._startupScansInFlight.set(name, generation);
-    }
-    clearStartupScanInFlight(name, generation) {
-        const owner = this._startupScansInFlight.get(name);
-        if (owner === generation) {
-            this._startupScansInFlight.delete(name);
-        }
-    }
-    isStartupScanInFlight(name) {
-        return this._startupScansInFlight.has(name);
-    }
-    formatPipelineCrashNotice(filePath, err) {
-        const key = path.resolve(filePath);
-        const count = (this._pipelineCrashCounts.get(key) ?? 0) + 1;
-        this._pipelineCrashCounts.set(key, count);
-        const message = err instanceof Error ? err.message : String(err);
-        const shortMessage = message.split("\n")[0].slice(0, 220);
-        const shouldSurface = count <= RUNTIME_CONFIG.crashNotice.alwaysShowFirstN ||
-            count % RUNTIME_CONFIG.crashNotice.showEveryNth === 0;
-        if (!shouldSurface)
-            return "";
-        return [
-            "⚠️ pi-lens pipeline crashed while analyzing this write.",
-            `File: ${path.basename(filePath)} | crash count this session: ${count}`,
-            `Error: ${shortMessage}`,
-            "Recovery: LSP service was reset. If this repeats, rerun with --no-lsp and report the file + stack.",
-        ].join("\n");
-    }
-    getCrashEntries() {
-        return Array.from(this._pipelineCrashCounts.entries());
-    }
-    get projectRoot() {
-        return this._projectRoot;
-    }
-    set projectRoot(value) {
-        this._projectRoot = normalizeMapKey(value);
-    }
-    get errorDebtBaseline() {
-        return this._errorDebtBaseline;
-    }
-    set errorDebtBaseline(value) {
-        this._errorDebtBaseline = value;
-    }
-    get cachedExports() {
-        return this._cachedExports;
-    }
-    appendCascadeRun(run) {
-        this._cascadeRuns.push(run);
-    }
-    appendCascadePromise(p) {
-        if (this._pendingCascadeRuns.length < MAX_PENDING_CASCADE_RUNS) {
-            this._pendingCascadeRuns.push(p);
-            return;
-        }
-        // Preserve delivery for overflow rather than growing the per-edit array.
-        // The settled run enters the same accumulator off-hook and is therefore
-        // visible to the next turn-end drain.
-        recordDegradationOnce({
-            kind: "cascade-pending-cap",
-            subject: "runtime-coordinator",
-            reason: `deferred cascade admission capped at ${MAX_PENDING_CASCADE_RUNS}`,
-        });
-        void p
-            .then((run) => this.appendCascadeRun(run))
-            .catch(() => {
-            // Pipeline promises are normally non-rejecting; preserve the existing
-            // failure sink if a caller violates that contract.
-        });
-    }
-    /**
-     * The active turn_end settle clock, or undefined outside that wait.
-     *
-     * #1462 review F-F: every cascade compute in flight on this coordinator
-     * reads the SAME clock. `_turnEndCascadeSettleStarts` is keyed by settle
-     * token so `settleCascadeRuns` can distinguish its own drain from a nested
-     * one, but this getter always answers with the latest active window —
-     * there is one turn_end per runtime, not one per caller. A cascade begun
-     * moments before turn_end and one begun long before it both measure elapsed
-     * time against the same start, which is correct: they are racing the same
-     * settle wait and share its deadline, not separate ones.
-     */
-    getTurnEndCascadeSettleStart() {
-        let latest;
-        for (const start of this._turnEndCascadeSettleStarts.values())
-            latest = start;
-        return latest;
-    }
-    /**
-     * Drain the deferred cascade computes kicked off this turn (#450), racing them
-     * against a bounded wait. Fulfilled runs feed the same accumulator as inline
-     * runs (appendCascadeRun). A promise still pending at the cap is retained so a
-     * late-resolving compute is picked up on the next turn_end rather than lost.
-     * The stored promises never reject (pipeline guarantees an "error" skip-run).
-     */
-    async settleCascadeRuns(maxWaitMs, settleOptions = {}) {
-        const pending = this._pendingCascadeRuns;
-        if (pending.length === 0)
-            return { settled: 0, timedOut: 0 };
-        this._pendingCascadeRuns = [];
-        const settleToken = settleOptions.trackTurnEndClock
-            ? ++this._nextCascadeSettleToken
-            : undefined;
-        if (settleToken !== undefined) {
-            this._turnEndCascadeSettleStarts.set(settleToken, Date.now());
-        }
-        try {
-            // Track per-promise settlement so promises still in flight at the cap can be
-            // carried over. A settled entry records its run; an unsettled one is re-parked.
-            const tracked = pending.map((p) => {
-                const entry = { done: false, promise: p };
-                entry.promise = p.then((run) => {
-                    entry.done = true;
-                    entry.run = run;
-                    return run;
-                });
-                return entry;
-            });
-            const timeout = new Promise((resolve) => {
-                setTimeout(resolve, maxWaitMs).unref?.();
-            });
-            await Promise.race([
-                Promise.allSettled(tracked.map((t) => t.promise)),
-                timeout,
-            ]);
-            let settled = 0;
-            let timedOut = 0;
-            for (const entry of tracked) {
-                if (entry.done && entry.run) {
-                    this.appendCascadeRun(entry.run);
-                    settled += 1;
-                }
-                else {
-                    this._pendingCascadeRuns.push(entry.promise);
-                    timedOut += 1;
-                }
-            }
-            return { settled, timedOut };
-        }
-        finally {
-            if (settleToken !== undefined) {
-                this._turnEndCascadeSettleStarts.delete(settleToken);
-            }
-        }
-    }
-    consumeCascadeRuns() {
-        const runs = this._cascadeRuns;
-        this._cascadeRuns = [];
-        return runs;
-    }
-    /**
-     * R1 (#1443 follow-up): non-destructive peek used by turn_end's read-only
-     * fast path. A carried cascade run (or one still in flight) represents a
-     * DELIVERY OPPORTUNITY, not turn activity — an agent that answers a question
-     * without editing anything must still get yesterday's late finding. Before
-     * this, the files-empty early return skipped `settleCascadeRuns` /
-     * `consumeCascadeRuns` entirely on a read-only turn, so `beginTurn`'s next
-     * carry pass saw the run as having survived a turn_start with no offsetting
-     * drain and dropped it — burning the one-turn carry allowance on a turn that
-     * never had a chance to deliver.
-     */
-    hasCascadeRuns() {
-        // Carried, ALREADY-BUILT runs only. Pending (still-settling) computes are
-        // deliberately excluded: a read-only turn that fell through for a pending
-        // run would block on the full settle cap — every turn, forever, when the
-        // compute never resolves (re-review finding F1). A pending run loses
-        // nothing by waiting: settleCascadeRuns re-parks it and the next turn
-        // that actually settles it delivers it.
-        return this._cascadeRuns.length > 0;
-    }
-    recordInlineBlockers(filePath, summary, writeIndex, sources, lines, contentBaseline, diagnostics) {
-        const recordedAtMs = Date.now();
-        this._pendingInlineBlockers.set(path.resolve(filePath), {
-            filePath,
-            summary,
-            writeIndex,
-            sources,
-            lines,
-            diagnostics,
-            recordedAtMs,
-            stale: false,
-            ...(contentBaseline
-                ? {
-                    recordedSize: contentBaseline.size,
-                    recordedHash: contentBaseline.sha256,
-                }
-                : {}),
-        });
-        return recordedAtMs;
-    }
-    clearInlineBlockers(filePath) {
-        this._pendingInlineBlockers.delete(path.resolve(filePath));
-    }
-    /**
-     * #1631: demote a cached blocker to stale without dropping it (#1419
-     * demote-not-drop). Called by the turn-boundary freshness sweep when the
-     * file or one of its forward imports drifted on disk after the verdict.
-     * Idempotent: re-marking an already-stale entry (for ANY reason) is a
-     * no-op — a `"past-eof"` demotion already took this record out of the
-     * authoritative channel, and `sweepInlineBlockerFreshness` re-checks next
-     * turn once that heals. Returns true only when this call transitioned the
-     * entry to stale, so a caller can log the demotion exactly once.
-     */
-    markInlineBlockerStale(filePath, reason = "dependency-drift") {
-        const key = path.resolve(filePath);
-        const existing = this._pendingInlineBlockers.get(key);
-        if (!existing || existing.stale)
-            return false;
-        this._pendingInlineBlockers.set(key, {
-            ...existing,
-            stale: true,
-            staleReason: reason,
-        });
-        return true;
-    }
-    /**
-     * #1641: re-derive the past-EOF demotion for one inline-blocker record.
-     * Unlike {@link markInlineBlockerStale} (a one-way latch for the
-     * dependency-drift gate), this RE-ARMS: called every turn end with the
-     * gate's freshly-computed verdict, it can both demote (rising edge) and
-     * heal (falling edge — a transient shrink-then-restore of the file). Never
-     * touches a record a sibling gate demoted (`staleReason !== "past-eof"`
-     * while `stale`) — composing with #1631's dependency-drift gate means each
-     * gate only heals its own demotions. Returns true only on an actual
-     * transition, so the caller logs/resyncs exactly once per edge.
-     */
-    setInlineBlockerPastEofStale(filePath, isPastEof) {
-        const key = path.resolve(filePath);
-        const existing = this._pendingInlineBlockers.get(key);
-        if (!existing)
-            return false;
-        if (existing.stale && existing.staleReason !== "past-eof")
-            return false;
-        const currentlyPastEof = !!existing.stale && existing.staleReason === "past-eof";
-        if (currentlyPastEof === isPastEof)
-            return false;
-        this._pendingInlineBlockers.set(key, {
-            ...existing,
-            stale: isPastEof,
-            staleReason: isPastEof ? "past-eof" : undefined,
-        });
-        return true;
-    }
-    /**
-     * #2982: re-derive the self-drift demotion for one inline-blocker record.
-     *
-     * Modelled on {@link setInlineBlockerPastEofStale}, not on
-     * {@link markInlineBlockerStale}: it RE-ARMS rather than latching, so a
-     * file whose bytes drift and then come back (a checkout, a revert, an
-     * editor writing the original content) un-demotes on the next sweep
-     * instead of staying demoted for the session. That re-arm is what lets
-     * this axis skip the #1950 delivery cap entirely — a record that can heal
-     * needs no bounded-noise retirement, and applying the cap here would walk
-     * an ast-grep or tree-sitter security finding out of turn-end rendering
-     * permanently (#2982 review).
-     *
-     * Composes with the sibling gates the same way they compose with each
-     * other: it never touches a record another gate demoted, and never heals a
-     * demotion it did not make. Returns true only on an actual transition, so
-     * the caller counts exactly one edge.
-     */
-    setInlineBlockerSelfDriftStale(filePath, isSelfDrift) {
-        const key = path.resolve(filePath);
-        const existing = this._pendingInlineBlockers.get(key);
-        if (!existing)
-            return false;
-        if (existing.stale && existing.staleReason !== "self-drift")
-            return false;
-        const currentlySelfDrift = !!existing.stale && existing.staleReason === "self-drift";
-        if (currentlySelfDrift === isSelfDrift)
-            return false;
-        // Omit the key rather than assigning `undefined` to it: under
-        // `exactOptionalPropertyTypes` those are different, and writing the
-        // `undefined` is a strictness spike the ratchet counts. Healing has to
-        // drop `staleReason` off the rebuilt record, so destructure it away
-        // instead of letting `...existing` carry the old value through.
-        const { staleReason: _cleared, ...rest } = existing;
-        this._pendingInlineBlockers.set(key, {
-            ...rest,
-            stale: isSelfDrift,
-            ...(isSelfDrift ? { staleReason: "self-drift" } : {}),
-        });
-        return true;
-    }
-    /**
-     * #1944: retire a past-EOF demotion after its ONE degraded delivery.
-     *
-     * The past-EOF gate demotes and re-arms, but nothing ever retired the
-     * record, so a blocker whose file shrank past the cited lines re-served on
-     * every turn end for the rest of the session — measured live at 80+
-     * minutes on session 01a0234c. The re-serve is unbounded, not the six
-     * turns the first evidence window suggested.
-     *
-     * It is unbounded because the record cannot resolve itself. The two
-     * clearing events (`clearInlineBlockers` on a later dispatch of the same
-     * path, `retireInlineBlockerOnConfirmedClean` on a fresh clean verdict)
-     * both need the file to be looked at again, and the agent has no reason to
-     * look: the coordinates it was handed do not exist. "Re-run to confirm" is
-     * an instruction this record makes impossible to follow.
-     *
-     * So the delivery surface retires it after serving it once, degraded. That
-     * is a DROP, which #1419's demote-not-drop rule normally forbids; the
-     * exception is narrow and stated here. The finding was already delivered
-     * this turn with its dead coordinates annotated, and what remains is a
-     * message pinned to a line the file does not have. `deadLines` is required
-     * and must be non-empty, so a record stale for any OTHER reason, or
-     * past-EOF with no identified dead line, still stands.
-     *
-     * @returns true when an entry was retired — the caller records it, so the
-     * suppression is never silent (#1432 Gap 1).
-     */
-    retireDemotedPastEofBlocker(filePath, deadLines) {
-        if (deadLines.length === 0)
-            return false;
-        const key = path.resolve(filePath);
-        const existing = this._pendingInlineBlockers.get(key);
-        if (!existing)
-            return false;
-        // Only this gate's own demotion. A dependency-drift demotion (#1631)
-        // keeps in-bounds coordinates the agent CAN re-run against, so it stays
-        // in the store until a fresh verdict clears it.
-        if (!existing.stale)
-            return false;
-        if ((existing.staleReason ?? "past-eof") !== "past-eof")
-            return false;
-        this._pendingInlineBlockers.delete(key);
-        return true;
-    }
-    /**
-     * #1950 fix-round F1: read the current delivery count WITHOUT committing
-     * an increment. `runtime-turn.ts` needs the count a delivery would reach
-     * BEFORE it knows whether that delivery will actually reach the agent —
-     * the turn-end signature dedupe (`turn-end-findings-last`) can suppress a
-     * turn whose rendered content is identical to the last one, and a
-     * suppressed turn must not advance the counter (the agent never saw it).
-     * The caller peeks, renders the tentative body, and only calls
-     * {@link incrementInlineBlockerStaleDelivery} once it knows the turn's
-     * content is NOT being suppressed.
-     */
-    peekInlineBlockerStaleDeliveryCount(filePath) {
-        const key = path.resolve(filePath);
-        return this._pendingInlineBlockers.get(key)?.staleDeliveryCount ?? 0;
-    }
-    /**
-     * #1950: commit one more turn end that re-served this record while
-     * `stale`. The caller (`runtime-turn.ts`) only calls this for a
-     * `"dependency-drift"` demotion — a `"past-eof"` demotion retires after
-     * its own single delivery (#1944, `retireDemotedPastEofBlocker`) and
-     * never accumulates a count — and only AFTER confirming the turn's
-     * content will not be suppressed by the signature dedupe (see
-     * {@link peekInlineBlockerStaleDeliveryCount}), so this counts ACTUAL
-     * deliveries the agent saw, not turn-end loop iterations. Returns the new
-     * count, or 0 when there is no entry to count against (already retired,
-     * or never recorded).
-     */
-    incrementInlineBlockerStaleDelivery(filePath) {
-        const key = path.resolve(filePath);
-        const existing = this._pendingInlineBlockers.get(key);
-        if (!existing)
-            return 0;
-        const next = (existing.staleDeliveryCount ?? 0) + 1;
-        this._pendingInlineBlockers.set(key, {
-            ...existing,
-            staleDeliveryCount: next,
-        });
-        return next;
-    }
-    /**
-     * #1950: retire a dependency-drift demotion once it has been delivered
-     * `DEPENDENCY_DRIFT_MAX_DELIVERIES` times with no re-run confirming or
-     * clearing it. Unlike {@link retireDemotedPastEofBlocker}, the record is
-     * NOT provably unrecoverable — its coordinates are still in bounds, and a
-     * fresh dispatch of the file could still confirm or clear it. This is a
-     * bounded-noise cap, not a "this can never resolve" verdict, and the
-     * caller's ledger reason must say so (`demoted-finding-retired`'s "capped,
-     * re-run can still confirm" vs. past-EOF's "retired, unrecoverable").
-     *
-     * Only ever touches this gate's OWN demotion (`staleReason ===
-     * "dependency-drift"`) — a past-EOF demotion on the same file is that
-     * gate's own record to retire, not this one's.
-     *
-     * @returns true when an entry was retired — the caller records it, so the
-     * suppression is never silent (#1432 Gap 1).
-     */
-    retireDemotedDependencyDriftBlocker(filePath) {
-        const key = path.resolve(filePath);
-        const existing = this._pendingInlineBlockers.get(key);
-        if (!existing)
-            return false;
-        if (!existing.stale)
-            return false;
-        if (existing.staleReason !== "dependency-drift")
-            return false;
-        this._pendingInlineBlockers.delete(key);
-        return true;
-    }
-    /**
-     * Retire a file's inline blocker because a FRESH, content-bound diagnostic
-     * verdict proved it gone (#1561).
-     *
-     * The map was invalidated by exactly two events: a later dispatch of the
-     * SAME path returning no blockers, and that path ceasing to exist (#1245).
-     * Neither covers the common case that produced #1561 — a blocker on file F
-     * whose cause lives in file G. Fixing G re-dispatches G, not F, so F's
-     * verdict was never re-taken and "Unresolved from this turn" was re-injected
-     * for the rest of the session. In the live case the agent then ran
-     * `lsp_diagnostics` on F, pi-lens answered "confirmed clean", and the
-     * blocker was STILL re-served on the next three turn ends: #571 wired that
-     * tool's confirmed result into the widget footer and stopped there.
-     *
-     * This is the seam #1198 invariant 4 left undecided, decided: an affirmative
-     * clean from the authoritative current view retires the stale verdict.
-     *
-     * Ordering (#1198 invariants 1-2). Both stores draw from the same
-     * `nextWriteIndex()` counter, so when both sides are stamped the retire
-     * requires the clean verdict to be strictly NEWER. A slow old clean that
-     * settles after a fresh dispatch found real blockers must not erase them.
-     * When either side is unstamped the two cannot be ordered at all; the fresh
-     * confirmed verdict wins, because it is the only one of the two backed by an
-     * actual observation of current content. Only production's single record site
-     * is stamped, so in practice the unstamped branch is legacy callers/tests.
-     *
-     * COVERAGE (#1561 F1). A blocker is retired only by a verdict that can speak
-     * for the tools that raised it. Inline blockers come from the whole dispatch,
-     * not just the language server: `dispatcher.ts` collects every
-     * `semantic === "blocking"` diagnostic across all runners, so eslint,
-     * biome-check, actionlint, elixir/gleam-check and ast-grep security rules all
-     * land in this map. A language-server check knows nothing about any of them,
-     * so `coveredSources` must be a SUPERSET of the recorded sources or the entry
-     * stands. This is a commit gate: a record whose provenance is unknown (no
-     * `sources`) fails CLOSED and is never retired, because "we don't know what
-     * raised this" must not resolve to "an LSP check can clear it".
-     *
-     * @returns true when an entry was retired — the caller logs it, so an
-     * eviction is never silent (#1432 Gap 1).
-     */
-    retireInlineBlockerOnConfirmedClean(filePath, confirmedAtWriteIndex, coveredSources) {
-        const key = path.resolve(filePath);
-        const existing = this._pendingInlineBlockers.get(key);
-        if (!existing)
-            return false;
-        if (existing.writeIndex !== undefined &&
-            confirmedAtWriteIndex !== undefined &&
-            confirmedAtWriteIndex <= existing.writeIndex) {
-            return false;
-        }
-        // Fail closed on unknown provenance, and on any source the fresh verdict
-        // did not consult. An eslint-origin blocker outliving an LSP-only clean is
-        // the correct outcome — the next dispatch of that file is what clears it.
-        if (!existing.sources || existing.sources.length === 0)
-            return false;
-        const covered = new Set(coveredSources ?? []);
-        if (!existing.sources.every((source) => covered.has(source)))
-            return false;
-        this._pendingInlineBlockers.delete(key);
-        return true;
-    }
-    reconcileInlineBlockers() {
-        // Rebuild, never delete-in-place: `PathKeyedMap.delete()` re-normalizes
-        // the key, and `normalizeMapKey` realpaths a live file but lowercases
-        // the tail of a deleted one — so on Windows a mixed-case filename gets
-        // a DIFFERENT delete-time key than its set-time key and the delete
-        // misses (#1245, verified live: `MyCase.ts` survived reconcile).
-        // Existence-checking the display path and rebuilding survivors avoids
-        // the key-mismatch entirely; live survivors re-set to identical keys
-        // (both realpath), so only the stale entries are dropped.
-        const survivors = [];
-        for (const [displayPath, value] of this._pendingInlineBlockers.entries()) {
-            if (fs.existsSync(displayPath))
-                survivors.push([displayPath, value]);
-        }
-        if (survivors.length !== this._pendingInlineBlockers.size) {
-            this._pendingInlineBlockers.clear();
-            for (const [displayPath, value] of survivors) {
-                this._pendingInlineBlockers.set(displayPath, value);
-            }
-        }
-    }
-    /**
-     * Stale-entry reconcile (#1245): a blocker recorded for a file that has
-     * since been deleted can never be cleared — `clearInlineBlockers` fires
-     * only on a LATER dispatch of the same path, which a deleted file never
-     * gets. Every read of the blocker map (turn_end injection, git-guard
-     * size/summary, `syncGitGuardRecord`) therefore drops entries whose file no
-     * longer exists on disk: a blocker for a deleted file is stale by
-     * definition (the agent cannot fix it), so it must not re-surface every
-     * turn or gate a commit. The map is tiny (per-turn blockers) and reads are
-     * bounded (once per turn_end / tool_result), so the probe cost is
-     * negligible.
-     */
-    getInlineBlockersSnapshot() {
-        this.reconcileInlineBlockers();
-        return [...this._pendingInlineBlockers.values()];
-    }
-    consumeInlineBlockers() {
-        const entries = this.getInlineBlockersSnapshot();
-        this._pendingInlineBlockers.clear();
-        return entries;
-    }
-    recordActionableWarnings(warnings) {
-        for (const warning of warnings) {
-            this._actionableWarningsThisTurn.set(warning.id, warning);
-        }
-    }
-    peekActionableWarnings() {
-        return [...this._actionableWarningsThisTurn.values()];
-    }
-    clearActionableWarnings() {
-        this._actionableWarningsThisTurn.clear();
-    }
-    recordCodeQualityWarnings(warnings) {
-        for (const warning of warnings) {
-            this._codeQualityWarningsThisTurn.set(warning.id, warning);
-        }
-    }
-    peekCodeQualityWarnings() {
-        return [...this._codeQualityWarningsThisTurn.values()];
-    }
-    clearCodeQualityWarnings() {
-        this._codeQualityWarningsThisTurn.clear();
-    }
-    /** #484: the per-run diagnostics/autofix/format collector (accumulates
-     * across turns; consumed once at the agent_settled quiet window). Always
-     * present; callers gate recording behind the `lens-turn-summary` opt-in
-     * flag. */
-    get turnSummary() {
-        return this._turnSummary;
-    }
-    get complexityBaselines() {
-        return this._complexityBaselines;
-    }
-    get fixedThisTurn() {
-        // Self-referencing local so chained add() returns the same facade
-        // instead of re-entering this getter and allocating a new one per call
-        // (sonar S7725).
-        const facade = {
-            add: (filePath) => {
-                this._fixedThisTurn.set(filePath, true);
-                return facade;
-            },
-            has: (filePath) => this._fixedThisTurn.has(filePath),
-            delete: (filePath) => this._fixedThisTurn.delete(filePath),
-            clear: () => this._fixedThisTurn.clear(),
-        };
-        return facade;
-    }
-    get projectRulesScan() {
-        return this._projectRulesScan;
-    }
-    set projectRulesScan(value) {
-        this._projectRulesScan = value;
-    }
-    get readGuard() {
-        this._readGuard ??= new ReadGuard(this._telemetrySessionId);
-        return this._readGuard;
-    }
-    /**
-     * Record the canonical target `tool_call` resolved for `toolCallId`
-     * (#1642). The paired `tool_result` claims this exactly once via
-     * {@link takeToolCallAttribution} instead of re-deriving a path from its
-     * own diff metadata.
-     */
-    recordToolCallAttribution(toolCallId, attribution) {
-        this._toolCallAttributions.set(toolCallId, {
-            ...attribution,
-            recordedAt: Date.now(),
-        });
-    }
-    /**
-     * One-shot claim of a previously recorded tool-call attribution. Removed
-     * on read: a given `tool_call`/`tool_result` pair correlates exactly once,
-     * and leaving it behind would let a later, unrelated `tool_result` that
-     * happens to reuse a stale id inherit a stranger's resolved path.
-     *
-     * An expired entry (older than `TOOL_CALL_ATTRIBUTION_TTL_MS`) is treated
-     * as a miss and removed rather than returned — see the constant's doc.
-     */
-    takeToolCallAttribution(toolCallId) {
-        const attribution = this._toolCallAttributions.get(toolCallId);
-        if (attribution === undefined)
-            return undefined;
-        this._toolCallAttributions.delete(toolCallId);
-        if (Date.now() - attribution.recordedAt > TOOL_CALL_ATTRIBUTION_TTL_MS) {
-            return undefined;
-        }
-        return attribution;
-    }
-    /**
-     * Queue one mutation kind for `filePath` at `agent_end`. Returns `true`
-     * when this call created a pending entry or added a new kind, and `false`
-     * for a same-kind re-touch. Callers publish each kind's first transition
-     * without spamming repeated edits before `agent_end`.
-     */
-    deferMutation(filePath, cwd, 
-    /** Host tool name; any mutating tool, not just `write`/`edit` (#2423). */
-    toolName, turnStateCwd, kind, ownerSessionId, originCwd) {
-        const key = path.resolve(filePath);
-        const now = Date.now();
-        const resolvedOriginCwd = originCwd ?? turnStateCwd;
-        const existing = this._pendingDeferredMutations.get(key);
-        if (existing) {
-            const addedKind = !existing.kinds.has(kind);
-            existing.lastTouchedAt = now;
-            existing.cwd = cwd;
-            existing.turnStateCwd = turnStateCwd;
-            existing.toolNames.add(toolName);
-            existing.kinds.add(kind);
-            existing.queuedTurnIndex = this._turnIndex;
-            existing.queuedTurnId = `${this._telemetrySessionId}:${this._turnIndex}`;
-            existing.ownerSessionId = ownerSessionId;
-            existing.originCwd = resolvedOriginCwd;
-            return addedKind;
-        }
-        this._pendingDeferredMutations.set(key, {
-            filePath: key,
-            cwd,
-            turnStateCwd,
-            firstTouchedAt: now,
-            lastTouchedAt: now,
-            toolNames: new Set([toolName]),
-            kinds: new Set([kind]),
-            queuedTurnIndex: this._turnIndex,
-            queuedTurnId: `${this._telemetrySessionId}:${this._turnIndex}`,
-            ownerSessionId,
-            originCwd: resolvedOriginCwd,
-        });
-        return true;
-    }
-    deferFormat(filePath, cwd, 
-    /** Host tool name; any mutating tool, not just `write`/`edit` (#2423). */
-    toolName, turnStateCwd, ownerSessionId, originCwd) {
-        return this.deferMutation(filePath, cwd, toolName, turnStateCwd, "format", ownerSessionId, originCwd);
-    }
-    get pendingDeferredFormatCount() {
-        return this._pendingDeferredMutations.size;
-    }
-    get pendingDeferredMutationCount() {
-        return this._pendingDeferredMutations.size;
-    }
-    /**
-     * Legacy unconditional drain — still exposed for any caller that
-     * genuinely wants "everything, no ownership check" (and for tests). New
-     * flush call sites should prefer {@link claimDeferredFormatFiles}.
-     */
-    consumeDeferredFormatFiles() {
-        const records = [...this._pendingDeferredMutations.values()];
-        this._pendingDeferredMutations.clear();
-        return records;
-    }
-    /**
-     * Ownership-filtered drain (#791). Claims and removes only the records
-     * this flush is entitled to:
-     *  - `ownerSessionId` unset on the record, OR `currentSessionId` unset, OR
-     *    they match → claimed as "same session" (the common case, and the
-     *    fail-safe default when either side lacks a stable session id).
-     *  - otherwise (both known, and they differ) the record belongs to a
-     *    DIFFERENT session (e.g. a concurrent in-process secondary/subagent)
-     *    and is left queued for its owner's own flush — UNLESS it has sat
-     *    unclaimed longer than `staleAfterMs` (the owner presumably died), in
-     *    which case this flush claims it as an orphan-recovery fallback ONLY
-     *    when `currentOriginCwd` (this flush's own workspace/worktree) exactly
-     *    matches the record's `originCwd` (the cwd it was actually queued
-     *    under, #1642 F3 — NOT `turnStateCwd`, which is always the workspace
-     *    root by design and so would match every session unconditionally). A
-     *    mismatch means the record belongs to a DIFFERENT checkout/worktree
-     *    than the one now running `agent_end` — claiming it across that
-     *    boundary is exactly how a worktree's queued edit got formatted onto
-     *    the parent checkout in the reported incident. It is left queued
-     *    (NOT deleted) and logged instead: a legitimate crashed-session
-     *    orphan from, say, a monorepo subdir must still be claimable later by
-     *    a flush whose origin actually matches, or stay visible for
-     *    observability — deleting it here would drop it forever with no
-     *    origin ever able to reclaim it.
-     *
-     * Returns the claimed records, the left-queued mismatched-origin records,
-     * and per-skipped record why it was left behind — callers use this for
-     * `agent_end`'s latency-log provenance and for the "stale fallback
-     * fired"/"orphan mismatch" log lines.
-     */
-    claimDeferredFormatFiles(currentSessionId, now, staleAfterMs, currentOriginCwd) {
-        const claimed = [];
-        const staleClaimed = [];
-        const deferredToOwner = [];
-        const droppedOrphans = [];
-        for (const [key, record] of this._pendingDeferredMutations) {
-            const sameSession = record.ownerSessionId === undefined ||
-                currentSessionId === undefined ||
-                record.ownerSessionId === currentSessionId;
-            if (sameSession) {
-                claimed.push(record);
-                this._pendingDeferredMutations.delete(key);
-                continue;
-            }
-            const age = now - record.lastTouchedAt;
-            if (age > staleAfterMs) {
-                // #1642 F3: origin identity is required before an orphan-recovery
-                // claim, not just staleness. `currentOriginCwd === undefined`
-                // means the caller can't state its own origin — fail-safe as
-                // "can't prove different" (same posture as the sameSession check
-                // above), not as a free pass to claim across a KNOWN mismatch.
-                const originMatches = currentOriginCwd === undefined ||
-                    pathsEqual(record.originCwd, currentOriginCwd);
-                if (originMatches) {
-                    this._pendingDeferredMutations.delete(key);
-                    staleClaimed.push(record);
-                }
-                else {
-                    // Left queued — see the doc above for why this must not be
-                    // deleted. Reported once per claim attempt; a genuinely
-                    // abandoned origin will keep surfacing here, which is the
-                    // intended, safer trade-off over silent, permanent loss.
-                    droppedOrphans.push(record);
-                }
-                continue;
-            }
-            deferredToOwner.push(record);
-        }
-        return { claimed, staleClaimed, deferredToOwner, droppedOrphans };
-    }
-    /** Return claimed records that were never started by an aborted drain. */
-    requeueDeferredFormatFiles(records) {
-        for (const record of records) {
-            const key = path.resolve(record.filePath);
-            const existing = this._pendingDeferredMutations.get(key);
-            if (existing) {
-                for (const kind of record.kinds)
-                    existing.kinds.add(kind);
-                for (const toolName of record.toolNames)
-                    existing.toolNames.add(toolName);
-                continue;
-            }
-            this._pendingDeferredMutations.set(key, {
-                ...record,
-                kinds: new Set(record.kinds),
-                toolNames: new Set(record.toolNames),
-            });
-        }
-    }
-    claimDeferredMutations(currentSessionId, now, staleAfterMs, currentOriginCwd) {
-        return this.claimDeferredFormatFiles(currentSessionId, now, staleAfterMs, currentOriginCwd);
-    }
-    requeueDeferredMutations(records) {
-        this.requeueDeferredFormatFiles(records);
-    }
-    shouldWarmLspOnRead(filePath, maxAgeMs = 120_000) {
-        const state = this._lspReadWarmState.get(path.resolve(filePath));
-        if (!state)
-            return true;
-        if (state.status === "warming")
-            return false;
-        return Date.now() - state.ts > maxAgeMs;
-    }
-    markLspReadWarmStarted(filePath) {
-        this._lspReadWarmState.set(path.resolve(filePath), {
-            status: "warming",
-            ts: Date.now(),
-        });
-    }
-    markLspReadWarmCompleted(filePath) {
-        this._lspReadWarmState.set(path.resolve(filePath), {
-            status: "ready",
-            ts: Date.now(),
-        });
-    }
-    clearLspReadWarmState(filePath) {
-        this._lspReadWarmState.delete(path.resolve(filePath));
-    }
-}
-/**
- * Read the live model identity off a pi extension context (#1655 item 2).
- *
- * `ExtensionContext.model` is `AgentSession.model`, projected through a lazy
- * getter guarded by `assertActive()`
- * (`@earendil-works/pi-coding-agent/dist/core/extensions/runner.js:488-491`;
- * `dist/core/agent-session.js:580-582`). The value is a `Model` with `id` and
- * `provider` (`@earendil-works/pi-ai/dist/types.d.ts:661-667`), or `undefined`
- * when no model is selected.
- *
- * Because the getter is lazy and guarded, reading it on a REPLACED runner
- * throws. Telemetry identity is advisory; a stale ctx must degrade to "no
- * identity", never take down the event handler that happened to carry it.
- */
-export function readHostModelIdentity(ctx) {
-    try {
-        const model = ctx?.model;
-        return {
-            model: typeof model?.id === "string" ? model.id : undefined,
-            provider: typeof model?.provider === "string" ? model.provider : undefined,
-        };
-    }
-    catch {
-        return {};
-    }
-}