@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

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

@@ -2,12 +2,28 @@ import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { logCascade } from "./cascade-logger.js";
-import { normalizeMapKey } from "./path-utils.js";
+import { normalizeMapKey, pathsEqual } from "./path-utils.js";
 import { PathKeyedMap } from "./path-keyed-map.js";
+import { BoundedLruCache } from "./bounded-cache.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";
+/**
+ * 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;
@@ -17,6 +33,8 @@ export class RuntimeCoordinator {
     _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.
@@ -69,6 +87,8 @@ export class RuntimeCoordinator {
     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();
@@ -89,6 +109,7 @@ export class RuntimeCoordinator {
         this._startupScansInFlight.clear();
         this._cascadeRuns = [];
         this._pendingCascadeRuns = [];
+        this._turnEndCascadeSettleStarts.clear();
         this._cascadeSessionStats = {
             runs: 0,
             diagnosticsSurfaced: 0,
@@ -115,6 +136,10 @@ export class RuntimeCoordinator {
         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();
@@ -421,6 +446,24 @@ export class RuntimeCoordinator {
     appendCascadePromise(p) {
         this._pendingCascadeRuns.push(p);
     }
+    /**
+     * 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
@@ -428,42 +471,55 @@ export class RuntimeCoordinator {
      * 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) {
+    async settleCascadeRuns(maxWaitMs, settleOptions = {}) {
         const pending = this._pendingCascadeRuns;
         if (pending.length === 0)
             return { settled: 0, timedOut: 0 };
         this._pendingCascadeRuns = [];
-        // 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;
+        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;
             });
-            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;
+            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;
+                }
             }
-            else {
-                this._pendingCascadeRuns.push(entry.promise);
-                timedOut += 1;
+            return { settled, timedOut };
+        }
+        finally {
+            if (settleToken !== undefined) {
+                this._turnEndCascadeSettleStarts.delete(settleToken);
             }
         }
-        return { settled, timedOut };
     }
     consumeCascadeRuns() {
         const runs = this._cascadeRuns;
@@ -490,15 +546,175 @@ export class RuntimeCoordinator {
         // that actually settles it delivers it.
         return this._cascadeRuns.length > 0;
     }
-    recordInlineBlockers(filePath, summary) {
+    recordInlineBlockers(filePath, summary, writeIndex, sources, lines) {
         this._pendingInlineBlockers.set(path.resolve(filePath), {
             filePath,
             summary,
+            writeIndex,
+            sources,
+            lines,
+            recordedAtMs: Date.now(),
+            stale: false,
         });
     }
     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;
+    }
+    /**
+     * #1944: retire a past-EOF demotion after its ONE degraded delivery.
+     *
+     * The past-EOF gate demotes and re-arms, but nothing ever retired the
+     * record, so a blocker whose file shrank past the cited lines re-served on
+     * every turn end for the rest of the session — measured live at 80+
+     * minutes on session 01a0234c. The re-serve is unbounded, not the six
+     * turns the first evidence window suggested.
+     *
+     * It is unbounded because the record cannot resolve itself. The two
+     * clearing events (`clearInlineBlockers` on a later dispatch of the same
+     * path, `retireInlineBlockerOnConfirmedClean` on a fresh clean verdict)
+     * both need the file to be looked at again, and the agent has no reason to
+     * look: the coordinates it was handed do not exist. "Re-run to confirm" is
+     * an instruction this record makes impossible to follow.
+     *
+     * So the delivery surface retires it after serving it once, degraded. That
+     * is a DROP, which #1419's demote-not-drop rule normally forbids; the
+     * exception is narrow and stated here. The finding was already delivered
+     * this turn with its dead coordinates annotated, and what remains is a
+     * message pinned to a line the file does not have. `deadLines` is required
+     * and must be non-empty, so a record stale for any OTHER reason, or
+     * past-EOF with no identified dead line, still stands.
+     *
+     * @returns true when an entry was retired — the caller records it, so the
+     * suppression is never silent (#1432 Gap 1).
+     */
+    retireDemotedPastEofBlocker(filePath, deadLines) {
+        if (deadLines.length === 0)
+            return false;
+        const key = path.resolve(filePath);
+        const existing = this._pendingInlineBlockers.get(key);
+        if (!existing)
+            return false;
+        // Only this gate's own demotion. A dependency-drift demotion (#1631)
+        // keeps in-bounds coordinates the agent CAN re-run against, so it stays
+        // in the store until a fresh verdict clears it.
+        if (!existing.stale)
+            return false;
+        if ((existing.staleReason ?? "past-eof") !== "past-eof")
+            return false;
+        this._pendingInlineBlockers.delete(key);
+        return true;
+    }
+    /**
+     * Retire a file's inline blocker because a FRESH, content-bound diagnostic
+     * verdict proved it gone (#1561).
+     *
+     * 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
@@ -598,15 +814,47 @@ export class RuntimeCoordinator {
         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, toolName, turnStateCwd, kind, ownerSessionId) {
+    deferMutation(filePath, cwd, 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);
@@ -617,6 +865,7 @@ export class RuntimeCoordinator {
             existing.kinds.add(kind);
             existing.queuedTurnIndex = this._turnIndex;
             existing.ownerSessionId = ownerSessionId;
+            existing.originCwd = resolvedOriginCwd;
             return addedKind;
         }
         this._pendingDeferredMutations.set(key, {
@@ -629,11 +878,12 @@ export class RuntimeCoordinator {
             kinds: new Set([kind]),
             queuedTurnIndex: this._turnIndex,
             ownerSessionId,
+            originCwd: resolvedOriginCwd,
         });
         return true;
     }
-    deferFormat(filePath, cwd, toolName, turnStateCwd, ownerSessionId) {
-        return this.deferMutation(filePath, cwd, toolName, turnStateCwd, "format", ownerSessionId);
+    deferFormat(filePath, cwd, toolName, turnStateCwd, ownerSessionId, originCwd) {
+        return this.deferMutation(filePath, cwd, toolName, turnStateCwd, "format", ownerSessionId, originCwd);
     }
     get pendingDeferredFormatCount() {
         return this._pendingDeferredMutations.size;
@@ -660,18 +910,32 @@ export class RuntimeCoordinator {
      *  - 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 anyway as an orphan-recovery
-     *    fallback.
+     *    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 both the claimed 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" log line.
+     * 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) {
+    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 ||
@@ -683,13 +947,29 @@ export class RuntimeCoordinator {
             }
             const age = now - record.lastTouchedAt;
             if (age > staleAfterMs) {
-                staleClaimed.push(record);
-                this._pendingDeferredMutations.delete(key);
+                // #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 };
+        return { claimed, staleClaimed, deferredToOwner, droppedOrphans };
     }
     /** Return claimed records that were never started by an aborted drain. */
     requeueDeferredFormatFiles(records) {
@@ -710,8 +990,8 @@ export class RuntimeCoordinator {
             });
         }
     }
-    claimDeferredMutations(currentSessionId, now, staleAfterMs) {
-        return this.claimDeferredFormatFiles(currentSessionId, now, staleAfterMs);
+    claimDeferredMutations(currentSessionId, now, staleAfterMs, currentOriginCwd) {
+        return this.claimDeferredFormatFiles(currentSessionId, now, staleAfterMs, currentOriginCwd);
     }
     requeueDeferredMutations(records) {
         this.requeueDeferredFormatFiles(records);
@@ -740,3 +1020,30 @@ export class RuntimeCoordinator {
         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 {};
+    }
+}