@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/review-graph/builder.js

@@ -27,7 +27,9 @@ import { flushReviewGraphLogSync, logReviewGraph, makeReviewGraphBuildMetadata,
 import { getSharedTreeSitterClient } from "../tree-sitter-shared.js";
 import { TreeSitterSymbolExtractor, } from "../tree-sitter-symbol-extractor.js";
 import { withTreeSitterRoot } from "../tree-sitter-shared.js";
+import { incrementDegradationCount } from "../degradation-ledger.js";
 import { resolveGitIdentity } from "./git-identity.js";
+import { formatReviewGraphRevisionDriftNote, } from "./revision-drift.js";
 import { buildSymbolId } from "./symbol-id.js";
 import { clearReviewGraphFileIr, getFreshReviewGraphFileIr, reviewGraphIrContentHash, } from "./shared-extraction-ir.js";
 // v3 (#260): test files are no longer indexed. Bumping the version makes
@@ -92,10 +94,21 @@ const MAIN_KIND_EXTENSIONS = Array.from(MAIN_KINDS).flatMap((kind) => KIND_EXTEN
 export const REVIEW_GRAPH_SOURCE_EXTENSIONS = MAIN_KIND_EXTENSIONS;
 const CHANGED_SYMBOLS_PREFIX = "session.reviewGraph.changedSymbols:";
 const extractorCache = new Map();
-// Per-invocation Promise cache: deduplicates concurrent buildOrUpdateGraph calls
-// for the same (cwd, changedFiles). Cleared at the start of each pipeline
-// invocation. A separate workspace cache below preserves the expensive parsed
-// graph across invocations when source file mtimes/sizes have not changed.
+// IN-FLIGHT Promise cache: deduplicates CONCURRENT buildOrUpdateGraph calls for
+// the same (cwd, changedFiles). A separate workspace cache below preserves the
+// expensive parsed graph across invocations when source file mtimes/sizes have
+// not changed.
+//
+// #1962: an entry lives only while its build is PENDING — `buildOrUpdateGraph`
+// deletes it on settle, success or failure alike. It used to delete only on
+// rejection, so a settled promise for a SKIPPED or COMPLETED build answered
+// every later call for the same key forever. The pipeline's `clearGraphCache()`
+// (pipeline.ts) was the only thing that ever removed it, and the background
+// build project_report kicks off never goes through the pipeline: four
+// project_report calls over 37s produced ONE build_started, while the tool told
+// the agent a retry had been started each time. That is the process-lifetime
+// latch shape from AGENTS.md — dedupe state whose lifetime must be the
+// operation's, not the process's.
 const _buildCache = new Map();
 const _workspaceGraphCache = new Map();
 const REVIEW_GRAPH_MAX_WARM_WORKSPACES = 8;
@@ -117,13 +130,37 @@ function clearWorkspaceGraphTimer(entry) {
         clearTimeout(entry.idleTimer);
     entry.idleTimer = undefined;
 }
+/**
+ * The canonical workspace identity for a `_buildCache` key (#1962 review F2).
+ *
+ * `path.resolve` collapses `.`/`..` segments and anchors a relative path on
+ * every OS; `normalizeMapKey` folds separator and casing, and it does that by
+ * probing the filesystem (`realpathSync.native`) rather than branching on
+ * `process.platform`. Both steps are idempotent, so feeding this an
+ * already-canonical key — which the two read sites below do — returns it
+ * unchanged.
+ */
+function buildCacheWorkspaceKey(cwd) {
+    return normalizeMapKey(path.resolve(cwd));
+}
+/**
+ * The workspace half of an existing `_buildCache` key. `buildCacheKey`
+ * canonicalizes that half at construction, so this is a plain split.
+ */
+function buildCacheKeyWorkspace(buildKey) {
+    const separator = buildKey.indexOf("|");
+    return separator >= 0 ? buildKey.slice(0, separator) : undefined;
+}
 function evictWorkspaceGraph(key, entry) {
     if (_workspaceGraphCache.get(key) !== entry)
         return;
     clearWorkspaceGraphTimer(entry);
+    // `key` is a workspace-cache key; run it through the build-key derivation so
+    // both sides of this comparison are canonical the same way. Idempotent, so
+    // an already-canonical key passes through untouched (#1962 review F2).
+    const buildWorkspace = buildCacheWorkspaceKey(key);
     for (const buildKey of _buildCache.keys()) {
-        const separator = buildKey.indexOf("|");
-        if (separator >= 0 && normalizeMapKey(buildKey.slice(0, separator)) === key) {
+        if (buildCacheKeyWorkspace(buildKey) === buildWorkspace) {
             _buildCache.delete(buildKey);
         }
     }
@@ -254,8 +291,12 @@ export function clearReviewGraphWorkspaceCache(cwd) {
     }
     else {
         const normalized = normalizeMapKey(cwd);
+        // Compare the key's WORKSPACE half only, both sides canonicalized the same
+        // way. The old form normalized the whole key, changed-file list included,
+        // which is neither meaningful nor cheap (#1962 review F2).
+        const buildWorkspace = buildCacheWorkspaceKey(cwd);
         for (const key of _buildCache.keys()) {
-            if (normalizeMapKey(key).startsWith(`${normalized}|`)) {
+            if (buildCacheKeyWorkspace(key) === buildWorkspace) {
                 _buildCache.delete(key);
             }
         }
@@ -440,8 +481,11 @@ export function getCachedReviewGraph(cwd) {
     // skip the disk read. loadPersistedGraph already rebuilt the indexes.
     // #300: this read is BLIND — nothing downstream content-verifies it, so a
     // stamped snapshot from a different HEAD/worktree must be dropped here.
+    // #1961: a snapshot stamped for a DIFFERENT WORKTREE is dropped here; one
+    // stamped at a different HEAD is served and marked drifted. See
+    // loadPersistedGraph for the one-policy rationale.
     const disk = loadPersistedGraph(cwd, {
-        verifyGitStamp: true,
+        verifyWorktreeIdentity: true,
         allowPartial: true,
     });
     if (!disk)
@@ -451,9 +495,39 @@ export function getCachedReviewGraph(cwd) {
         fileSignatures: disk.fileSignatures,
         fileHashes: disk.fileHashes,
         graph: disk.graph,
+        // Durable half of the drift fact. The current-HEAD half is never cached
+        // beside it — see getReviewGraphRevisionDrift (#1961 review F3).
+        ...(disk.stampedHead ? { snapshotStampedHead: disk.stampedHead } : {}),
     });
     return disk.graph;
 }
+/**
+ * Revision drift for `cwd`'s currently cached graph, computed NOW (#1961).
+ *
+ * Returns the stamped/current commit pair when the warm entry came from a disk
+ * snapshot whose stamp names a commit other than the worktree's HEAD at this
+ * instant, and `undefined` otherwise — including the case where HEAD has moved
+ * BACK to the stamped commit, which resolves the drift and must clear the note.
+ *
+ * Derived, never stored: caching the pair is what made the first version of
+ * this feature report a commit that had since stopped being HEAD, and keep
+ * reporting drift after it was resolved. Callers ask on every render.
+ */
+export function getReviewGraphRevisionDrift(cwd) {
+    const entry = _workspaceGraphCache.get(normalizeMapKey(cwd));
+    const stampedHead = entry?.snapshotStampedHead;
+    if (!stampedHead)
+        return undefined;
+    const current = resolveGitIdentity(cwd);
+    // Unresolvable identity is "can't tell", never "drifted" — the same
+    // fail-open rule loadPersistedGraph applies to the worktree check.
+    if (!current || current.headCommit === stampedHead)
+        return undefined;
+    return { stampedHead, currentHead: current.headCommit };
+}
+// Re-exported so a consumer that already imports the builder dynamically
+// (module_report) gets the accessor and its renderer from one place (#1961).
+export { formatReviewGraphRevisionDriftNote };
 function makeCtx(filePath, cwd, facts) {
     return {
         filePath,
@@ -888,6 +962,29 @@ const LEGACY_GRAPH_CACHE_FILENAME = "review-graph.json";
 // laundered to a consumer as a complete graph. It is read back exclusively by
 // the full-build resume path (`loadReviewGraphCheckpoint`).
 const GRAPH_CHECKPOINT_FILENAME = "review-graph.checkpoint.json.gz";
+/**
+ * Record what the blind read decided about a stamped snapshot (#1961).
+ *
+ * Bounded the way AGENTS.md requires and `bounded-telemetry.ts` documents: the
+ * ledger counts EVERY occurrence exactly, and only the rising edge per
+ * (verdict, cwd) also writes the detailed `review-graph.log` record. The
+ * accessor runs on every module_report / lens-engine / project_report call, so
+ * an unbounded record here would flood the log during a single navigation
+ * session. No second latch: the rising edge comes from the ledger's own tally.
+ */
+function logSnapshotReadVerdict(cwd, phase, reason) {
+    const verdict = phase === "snapshot_read_dropped" ? "dropped" : "drifted";
+    const isRisingEdge = incrementDegradationCount({
+        kind: "review-graph-snapshot-read",
+        // Subject keeps BOTH discriminators, so aggregation still answers which
+        // workspace and which verdict after the detailed records stop.
+        subject: `${verdict}:${normalizeMapKey(cwd)}`,
+        reason,
+    });
+    if (!isRisingEdge)
+        return;
+    logReviewGraph({ cwd, phase, reason });
+}
 function loadPersistedGraph(cwd, opts) {
     const cacheDir = path.join(getProjectDataDir(cwd), "cache");
     const cachePath = path.join(cacheDir, GRAPH_CACHE_FILENAME);
@@ -907,24 +1004,33 @@ function loadPersistedGraph(cwd, opts) {
             return null;
         if (data.coverage?.partial && !opts?.allowPartial)
             return null;
-        if (opts?.verifyGitStamp && data.gitStamp) {
-            // #300: a stamped snapshot must match the CURRENT repo identity. This
-            // closes the "worktree removed + re-added at the same path for a
-            // different branch" edge — the data-dir slug is reused, but the stamp
-            // mismatch forces a cold rebuild instead of serving the old branch's
-            // graph. Opt-in per call site: only the BLIND read path
-            // (getCachedReviewGraph) verifies — the build path's tier-2 load is
-            // already content-verified downstream (signature + #202 hash confirm),
-            // and dropping there on every HEAD move would nuke the cold cache
-            // after each commit. Any resolution failure (non-git, unreadable HEAD)
-            // yields undefined from resolveGitIdentity — treated as "can't
-            // verify," not a mismatch, so it does NOT drop the snapshot.
+        // #1961: ONE verification policy across both load paths — verify tree
+        // IDENTITY, never revision. A HEAD move says nothing about file contents,
+        // and the build path's tier-2 load has said so since #300 (see the comment
+        // above its `loadPersistedGraph(cwd)` call): dropping on every HEAD move
+        // forces a full whole-repo rebuild after each plain `git commit`. The BLIND
+        // read path used to do exactly that, which is why a snapshot survived a
+        // median of ~12 minutes before every reader saw "graph: cold".
+        //
+        // What stays: `worktreeRoot`. A snapshot stamped for a DIFFERENT worktree
+        // reached this data dir through slug reuse, so it describes another tree
+        // and nothing downstream would catch it — this read is blind. What goes:
+        // the `headCommit` equality drop. A revision difference is now REPORTED
+        // (`stampedHead` below → `getReviewGraphRevisionDrift` → computeTrust and
+        // module_report) instead of hiding the graph. Any resolution failure
+        // (non-git, unreadable HEAD) yields undefined from resolveGitIdentity —
+        // "can't verify," not a mismatch, so it does not drop the snapshot.
+        let stampedHead;
+        if (opts?.verifyWorktreeIdentity && data.gitStamp) {
             const current = resolveGitIdentity(cwd);
-            if (current &&
-                (current.headCommit !== data.gitStamp.headCommit ||
-                    current.worktreeRoot !== data.gitStamp.worktreeRoot)) {
+            if (current && current.worktreeRoot !== data.gitStamp.worktreeRoot) {
+                logSnapshotReadVerdict(cwd, "snapshot_read_dropped", "worktree_mismatch");
                 return null;
             }
+            if (current && current.headCommit !== data.gitStamp.headCommit) {
+                stampedHead = data.gitStamp.headCommit;
+                logSnapshotReadVerdict(cwd, "snapshot_read_drifted", "head_moved");
+            }
         }
         const graph = {
             version: data.version,
@@ -944,6 +1050,7 @@ function loadPersistedGraph(cwd, opts) {
             fileSignatures: new Map(data.fileSignatures ?? []),
             fileHashes: new Map(data.fileHashes ?? []),
             graph,
+            ...(stampedHead ? { stampedHead } : {}),
         };
     }
     catch {
@@ -1951,8 +2058,13 @@ function deleteReviewGraphCheckpoint(cwd) {
 /**
  * Read back a checkpoint for `cwd`, gated on the graph version (single source of
  * truth: {@link REVIEW_GRAPH_VERSION}) and, when both stamps resolve, the git
- * identity — the same drop-on-mismatch guard `loadPersistedGraph` uses. Returns
- * null (and best-effort deletes an unusable file) when absent/stale/corrupt.
+ * WORKTREE identity — the same one-policy guard `loadPersistedGraph` uses, and
+ * for the same reason (#1961): the resume path content-verifies every processed
+ * file by hash below (`contentHashEntry` vs `processedHashes`) and evicts the
+ * stale ones, so revision equality proves nothing the hashes do not already
+ * prove. Dropping on a HEAD move threw away a whole resumable partial build
+ * after each plain `git commit`. Returns null (and best-effort deletes an
+ * unusable file) when absent/stale/corrupt.
  * The returned graph carries `persistCoverage.inProgress` so it can never be
  * mistaken for a complete graph if it escapes the resume path.
  */
@@ -1984,13 +2096,11 @@ function loadReviewGraphCheckpoint(cwd) {
     }
     if (data.gitStamp) {
         const current = resolveGitIdentity(cwd);
-        if (current &&
-            (current.headCommit !== data.gitStamp.headCommit ||
-                current.worktreeRoot !== data.gitStamp.worktreeRoot)) {
+        if (current && current.worktreeRoot !== data.gitStamp.worktreeRoot) {
             logReviewGraph({
                 cwd,
                 phase: "checkpoint_discarded",
-                reason: "git_stamp_mismatch",
+                reason: "worktree_mismatch",
             });
             deleteReviewGraphCheckpoint(cwd);
             return null;
@@ -3904,6 +4014,15 @@ async function _doBuildGraph(cwd, changedFiles, facts, seqHint, buildId) {
     const graph = resumed?.graph ?? createEmptyGraph();
     const filesToExtract = resumed?.remaining ?? filesToBuild;
     const treeSitterClient = getSharedTreeSitterClient();
+    // #1941: grow the tree cache to span THIS pass's actual per-parse working
+    // set before parsing starts — filesToExtract, not filesToBuild. On a cold
+    // build they're the same array; on a resumed build filesToExtract is only
+    // the checkpoint's remaining (unprocessed) files, since resumed files are
+    // reused from the checkpoint graph and never re-parsed here. Sizing to
+    // filesToBuild on a resume would over-grow the cache for files this pass
+    // never touches. Same #1715 pattern as scanner.ts:147 — monotonic and
+    // ceiling-bounded inside ensureTreeCacheCapacity itself.
+    treeSitterClient?.ensureTreeCacheCapacity(filesToExtract.length);
     const extractionStartedAt = Date.now();
     // Seeded with the reused files' hashes on resume so the completed snapshot
     // still records a hash for every file (needed by #202 incremental next time).
@@ -4045,8 +4164,42 @@ async function _doBuildGraph(cwd, changedFiles, facts, seqHint, buildId) {
     facts.setSessionFact("session.reviewGraph", graph);
     return graph;
 }
+/**
+ * The one place the in-flight dedupe key is derived — and the one place its
+ * workspace half is normalized (#1962 review F2).
+ *
+ * The key used to interpolate the caller's RAW `cwd`. Callers hand in whatever
+ * path they hold: `runtime-session.ts:1562`, `lens-map.ts:1243`, and
+ * `mcp/cli.ts:59` pass an unnormalized root, while project_report's trigger
+ * passes `normalizeMapKey(path.resolve(cwd))`. On Windows those differ by
+ * separator and casing alone, so ONE workspace produced two live `_buildCache`
+ * entries: two concurrent full builds of the same repo (the #256 two-build OOM
+ * shape), and an `isGraphBuildInFlight` probe that answered about a key nobody
+ * else used. Folding here makes every caller land on one key without any of
+ * them having to know that.
+ *
+ * The derivation lives in {@link buildCacheWorkspaceKey}, which the two sites
+ * that read build keys BACK also use, so write and read agree by construction
+ * rather than by coincidence.
+ */
+function buildCacheKey(cwd, changedFiles) {
+    return `${buildCacheWorkspaceKey(cwd)}|${[...changedFiles].sort((a, b) => a.localeCompare(b)).join(",")}`;
+}
+/**
+ * Whether a build for this exact (cwd, changedFiles) key is PENDING right now
+ * (#1962). Callers that report to a user — project_report's cold-path trigger —
+ * read this BEFORE calling `buildOrUpdateGraph`, so "a retry was started" is
+ * only said when a build actually started rather than when an in-flight one
+ * absorbed the call. Check and call must happen in the same synchronous block;
+ * anything awaited between them reopens the race this exists to close.
+ */
+export function isGraphBuildInFlight(cwd, changedFiles = []) {
+    return _buildCache.has(buildCacheKey(cwd, changedFiles));
+}
 export function buildOrUpdateGraph(cwd, changedFiles, facts, seqHint) {
-    const cacheKey = `${cwd}|${[...changedFiles].sort((a, b) => a.localeCompare(b)).join(",")}`;
+    const cacheKey = buildCacheKey(cwd, changedFiles);
+    // Only a PENDING build is here (see `_buildCache`), so this dedupes genuine
+    // concurrency and nothing else.
     const cached = _buildCache.get(cacheKey);
     if (cached)
         return cached;
@@ -4117,7 +4270,6 @@ export function buildOrUpdateGraph(cwd, changedFiles, facts, seqHint) {
         return graph;
     })
         .catch((err) => {
-        _buildCache.delete(cacheKey);
         const reason = err instanceof Error ? err.message : String(err);
         recordBuildAttempt(cwd, "failed", reason, buildId);
         logReviewGraph({
@@ -4138,6 +4290,17 @@ export function buildOrUpdateGraph(cwd, changedFiles, facts, seqHint) {
         throw err;
     });
     _buildCache.set(cacheKey, promise);
+    // #1962: the entry's lifetime is the BUILD's, not the process's. Settling —
+    // fulfilled, skipped, or rejected — releases the key so the next caller
+    // really builds. The identity guard means a newer build that already claimed
+    // the key survives this older build's cleanup. `then(fn, fn)` rather than
+    // `finally` so the derived promise handles the rejection instead of raising
+    // an unhandled one; the returned `promise` is unchanged either way.
+    const release = () => {
+        if (_buildCache.get(cacheKey) === promise)
+            _buildCache.delete(cacheKey);
+    };
+    promise.then(release, release);
     return promise;
 }
 /**

package/node_modules/pi-lens/dist/clients/review-graph/query.js

@@ -53,6 +53,14 @@ export function computeTransitiveImpact(graph, seedFile, options) {
                     continue;
                 if (visited.has(edge.from))
                     continue;
+                if (hits.length >= maxHits) {
+                    return {
+                        seedFile: normalized,
+                        hits,
+                        truncated: true,
+                        maxDepthReached,
+                    };
+                }
                 visited.add(edge.from);
                 const dependent = graph.nodes.get(edge.from);
                 const hitDepth = node.depth + 1;
@@ -63,9 +71,6 @@ export function computeTransitiveImpact(graph, seedFile, options) {
                     depth: hitDepth,
                     relation: edge.kind,
                 });
-                if (hits.length >= maxHits) {
-                    return { seedFile: normalized, hits, truncated: true, maxDepthReached };
-                }
                 next.push({ id: edge.from, depth: hitDepth });
             }
         }
@@ -73,6 +78,44 @@ export function computeTransitiveImpact(graph, seedFile, options) {
     }
     return { seedFile: normalized, hits, truncated: false, maxDepthReached };
 }
+/**
+ * #1550: evidence for a `missing_node` verdict — the node id sought and the
+ * nearest thing the graph actually held. Runs ONLY on the miss path (one pass
+ * over `fileNodes`, which the same call already consulted), so the hot path is
+ * untouched. Keys are compared as the graph keys them (`normalizeMapKey`), so a
+ * key-shape divergence shows up as "nearest is the same path" rather than
+ * hiding behind a bare "missing".
+ */
+function describeMissingNode(graph, normalizedFile) {
+    const lastSlash = normalizedFile.lastIndexOf("/");
+    const dir = lastSlash === -1 ? "" : normalizedFile.slice(0, lastSlash);
+    const base = normalizedFile.slice(lastSlash + 1);
+    const stem = base.replace(/\.[^./]*$/, "");
+    let sameDirFileCount = 0;
+    let sameDirSibling;
+    let sameStemTwin;
+    for (const known of graph.fileNodes.keys()) {
+        const knownLastSlash = known.lastIndexOf("/");
+        const knownDir = knownLastSlash === -1 ? "" : known.slice(0, knownLastSlash);
+        const knownBase = known.slice(knownLastSlash + 1);
+        if (knownDir === dir) {
+            sameDirFileCount += 1;
+            sameDirSibling ??= known;
+            // A same-stem twin in the same directory is the strongest hint —
+            // an extension/compiled-twin resolution miss rather than an absent file.
+            if (sameStemTwin === undefined && knownBase.replace(/\.[^./]*$/, "") === stem) {
+                sameStemTwin = known;
+            }
+        }
+    }
+    return {
+        soughtNodeId: `file:${normalizedFile}`,
+        graphFileCount: graph.fileNodes.size,
+        symbolNodeCount: graph.symbolNodesByFile.get(normalizedFile)?.length ?? 0,
+        sameDirFileCount,
+        nearestFile: sameStemTwin ?? sameDirSibling,
+    };
+}
 export function computeImpactCascade(graph, changedFile, moduleGraph) {
     const normalizedFile = normalizeMapKey(changedFile);
     const fileNodeId = graph.fileNodes.get(normalizedFile);
@@ -111,7 +154,12 @@ export function computeImpactCascade(graph, changedFile, moduleGraph) {
             directCallers: [],
             neighborFiles: [],
             riskFlags: [],
-            indeterminate: { reason: "missing_node" },
+            indeterminate: {
+                reason: "missing_node",
+                // #1550: the reason alone forced a manual re-derivation on every
+                // occurrence. Attach the evidence (log-only — see the type doc).
+                diagnostic: describeMissingNode(graph, normalizedFile),
+            },
         };
     }
     const changedSymbols = graph.changedSymbolsByFile.get(normalizedFile) ?? [];

package/node_modules/pi-lens/dist/clients/review-graph/revision-drift.js

@@ -0,0 +1,21 @@
+/**
+ * Revision-drift evidence for a served review-graph snapshot, and the one
+ * wording every consumer renders it with (#1961).
+ *
+ * A separate module on purpose. `project-report.ts` and `module-report.ts`
+ * import the builder DYNAMICALLY, to keep that large module (and its
+ * tree-sitter dependencies) off their eager load path. Both still need this
+ * caveat's wording synchronously, and two hand-written copies of a warning
+ * sentence drift apart. This file imports nothing, so depending on it costs
+ * nothing.
+ */
+/**
+ * The one wording for the drift caveat, so `project_report`'s trust note and
+ * `module_report`'s warning cannot say different things about the same fact.
+ * Short commit ids only.
+ */
+export function formatReviewGraphRevisionDriftNote(drift) {
+    return (`Graph was built at commit ${drift.stampedHead.slice(0, 8)}; HEAD is now ` +
+        `${drift.currentHead.slice(0, 8)}. Results below reflect the earlier ` +
+        "revision — run pilens_rebuild or re-analyze to refresh.");
+}

package/node_modules/pi-lens/dist/clients/review-graph/workspace-modules.js

@@ -490,11 +490,14 @@ export function getModuleSourceFiles(moduleRoot, maxFiles = 20) {
             }
             if (!entry.isFile())
                 continue;
+            // #1974: extension gate before isIgnored — isIgnored recompiles
+            // minimatch patterns per ancestor dir per call, so it should only run
+            // for files the cheap extension check already flags as source.
+            if (!SOURCE_EXTS.has(path.extname(entry.name).toLowerCase()))
+                continue;
             if (ignoreMatcher.isIgnored(fullPath, false))
                 continue;
-            if (SOURCE_EXTS.has(path.extname(entry.name).toLowerCase())) {
-                files.push(normalizeMapKey(fullPath));
-            }
+            files.push(normalizeMapKey(fullPath));
         }
     };
     visit(root, 0);

package/node_modules/pi-lens/dist/clients/runtime-agent-end.js

@@ -5,6 +5,7 @@ import { publishFilesTouched } from "./bus-publish.js";
 import { publishAutofixStart, publishFormatStart, } from "./format-events-publish.js";
 import { logLatency } from "./latency-logger.js";
 import { isPathIgnoredByProject } from "./file-utils.js";
+import { admitBounded, emitBounded } from "./bounded-telemetry.js";
 import { newLspMutationCorrelationId } from "./lsp-mutation.js";
 import { getGlobalActionableWarningMaxFixes, } from "./lens-config.js";
 import { resyncLspFile, runAutofix, runFormatPhase } from "./pipeline.js";
@@ -46,7 +47,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
     // session (e.g. a concurrent in-process secondary/subagent) stay queued
     // for their owner's own agent_end, unless they've been stale long enough
     // to fall back to "claim as orphaned" (see claimDeferredFormatFiles).
-    const { claimed, staleClaimed, deferredToOwner } = runtime.claimDeferredMutations(currentSessionId, Date.now(), staleAfterMs);
+    const { claimed, staleClaimed, deferredToOwner, droppedOrphans } = runtime.claimDeferredMutations(currentSessionId, Date.now(), staleAfterMs, ctxCwd ?? runtime.projectRoot);
     const records = [...claimed, ...staleClaimed];
     const requeuedKinds = new Set();
     // S2d (gap 4, #1432 review): the aggregate `agent_end_deferred_mutation_drain`
@@ -85,13 +86,84 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         runtime.requeueDeferredMutations(pending);
     };
     const rootActionableAutofixEnabled = !!getFlag("lens-actionable-warning-autofix");
+    // The actionable-warnings cache is only ever written when the
+    // "lens-actionable-warnings" writer flag is on (clients/runtime-turn.ts).
+    // A reader that ignores this gate always misses in a host where the
+    // writer is off and logs "cache missing or expired" at every agent_end,
+    // misdirecting the debug log toward a bogus cache problem instead of the
+    // real cause: the feature that populates the cache is disabled (#1607).
+    const actionableWarningsWriterEnabled = !!getFlag("lens-actionable-warnings");
     // A path-aware source resolver signals that nested configs may re-enable
     // actionable autofix even when the root default is off. Legacy/test hosts
     // without that resolver keep the old fast exit and avoid a cache read.
-    const inspectActionableReport = rootActionableAutofixEnabled && typeof cacheManager.readCache === "function"
-        ? true
-        : getFlagSource !== undefined &&
-            typeof cacheManager.readCache === "function";
+    const inspectActionableReport = actionableWarningsWriterEnabled &&
+        typeof cacheManager.readCache === "function" &&
+        (rootActionableAutofixEnabled || getFlagSource !== undefined);
+    if (droppedOrphans.length > 0) {
+        // #1642 F3: a stale/foreign record whose origin (the cwd/worktree it
+        // was actually queued under) does NOT match this flush's own
+        // workspace/worktree is left queued and NEVER formatted by this
+        // flush — claiming it would be the same worktree→parent
+        // re-attribution the reported incident hit, just via the orphan
+        // fallback instead of tool_result's path resolution. It stays in
+        // `_pendingDeferredMutations` (not deleted) so a flush whose origin
+        // actually matches can still claim it later; a genuinely abandoned
+        // origin will keep surfacing this record on every subsequent
+        // agent_end, which is the deliberately safer trade-off over silently
+        // losing it forever.
+        dbg(`agent_end deferred_format: left ${droppedOrphans.length} orphaned file(s) queued due to a mismatched origin (unclaimed >${staleAfterMs}ms, not formatted by this flush): ${droppedOrphans
+            .map((r) => `${r.filePath} origin=${r.originCwd}`)
+            .join(", ")}`);
+        // #1678 item 1: a genuinely abandoned origin re-surfaces the SAME
+        // record on every subsequent agent_end for as long as the queued
+        // entry lives — by design (see the comment above), but the repo
+        // invariant is that a repeated degradation goes through the ledger's
+        // counting path instead of accumulating as unbounded raw log lines.
+        // The ledger is the single source of truth for whether THIS is a
+        // record's first appearance (its return value): the detailed forensic
+        // record below names only the orphans on that rising edge, with file
+        // identity/origin/age. Every later repeat of
+        // the same record is counted ONLY by the ledger's running count —
+        // no second raw event, no parallel "already logged" latch to
+        // maintain here.
+        // #1743: `admitBounded` IS that ledger call, plus the registry
+        // membership the bounded-telemetry sweep checks. This site admits PER
+        // ORPHAN and then writes ONE batched record naming the admitted ones,
+        // which is why it uses `admitBounded` directly instead of a per-record
+        // `emitBounded` — the per-call form would turn one log line into N.
+        const firstSeenOrphans = [];
+        for (const record of droppedOrphans) {
+            const isFirstOccurrence = admitBounded("agent_end_deferred_format_orphan_origin_mismatch", record.filePath, {
+                ledgerKind: "path-attribution-orphan-unresolved",
+                risingEdgePer: "identity",
+                reason: `origin=${record.originCwd} unclaimed >${staleAfterMs}ms`,
+            });
+            if (isFirstOccurrence)
+                firstSeenOrphans.push(record);
+        }
+        if (firstSeenOrphans.length > 0) {
+            // Already admitted above, one orphan at a time — hence no bounding
+            // options here. The batch's own identity is the origin this flush ran
+            // under; per-file identity rides in `metadata.files`.
+            emitBounded("agent_end_deferred_format_orphan_origin_mismatch", ctxCwd ?? runtime.projectRoot, {
+                type: "phase",
+                toolName: "agent_end",
+                durationMs: 0,
+                metadata: {
+                    fileCount: firstSeenOrphans.length,
+                    staleAfterMs,
+                    currentOriginCwd: ctxCwd ?? runtime.projectRoot,
+                    files: firstSeenOrphans.map((r) => ({
+                        filePath: r.filePath,
+                        originCwd: r.originCwd,
+                        ownerSessionId: r.ownerSessionId,
+                        queuedTurnIndex: r.queuedTurnIndex,
+                        ageMs: Date.now() - r.lastTouchedAt,
+                    })),
+                },
+            });
+        }
+    }
     if (records.length === 0 && !inspectActionableReport)
         return undefined;
     if (deferredToOwner.length > 0) {
@@ -402,9 +474,26 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         await resyncLspFile(changedPath, content, true, false, getFlag, dbg);
     }
     if (inspectActionableReport) {
-        const actionReport = cacheManager.readCache("actionable-warnings", ctxCwd ?? runtime.projectRoot, 10 * 60_000);
+        const actionCwd = ctxCwd ?? runtime.projectRoot;
+        const actionableWarningsMaxAgeMs = 10 * 60_000;
+        const actionReport = cacheManager.readCache("actionable-warnings", actionCwd, actionableWarningsMaxAgeMs);
         if (!actionReport?.data) {
-            dbg("agent_end actionable_warnings_autofix: cache missing or expired, skipping fixes");
+            // Distinguish "no cache file was ever written" from "a cache file
+            // exists but its TTL elapsed" (#1607) — both used to collapse into
+            // one "cache missing or expired" line, which doesn't tell a reader
+            // whether the writer ran and produced a stale file, or never ran.
+            const inspection = typeof cacheManager.inspectCache === "function"
+                ? cacheManager.inspectCache("actionable-warnings", actionCwd, actionableWarningsMaxAgeMs)
+                : undefined;
+            if (inspection === "missing") {
+                dbg("agent_end actionable_warnings_autofix: cache absent, skipping fixes");
+            }
+            else if (inspection === "stale") {
+                dbg("agent_end actionable_warnings_autofix: cache expired, skipping fixes");
+            }
+            else {
+                dbg(`agent_end actionable_warnings_autofix: cache missing or expired${inspection ? ` (${inspection})` : ""}, skipping fixes`);
+            }
         }
         else {
             const enabledFiles = actionReport.data.files.filter((file) => {

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

@@ -147,7 +147,14 @@ export function consumeSessionStartGuidance(cacheManager, cwd) {
     const guidance = cacheManager.readCache("session-start-guidance", cwd);
     if (!guidance?.data?.content)
         return;
-    cacheManager.writeCache("session-start-guidance", null, cwd);
+    // Consume by writing empty guidance, not by casting `null` into the entry's
+    // own type. `writeCache` infers its type parameter from `data`, so the cast
+    // bought nothing and claimed the file held a `{ content: string }` when it
+    // held JSON `null`. The producer (`runtime-session.ts`) always writes
+    // `{ content }`, and this reader gates on `data?.content` being non-empty,
+    // so an empty string is the same "already consumed" signal with the type
+    // the entry actually has. Same idiom as `acknowledgeTestFindings` above.
+    cacheManager.writeCache("session-start-guidance", { content: "" }, cwd);
     return {
         messages: [
             {