@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/dispatch/integration.js

@@ -10,7 +10,8 @@ import { detectFileKind } from "../file-kinds.js";
 import { getLspCapableKinds, getPrimaryDispatchGroup, } from "../language-policy.js";
 import { formatSlopScoreSummary, } from "../session-summary.js";
 import { clearCoverageNoticeState, clearLatencyReports, createDispatchContext, dispatchForFile, formatLatencyReport, getLatencyReports, RunnerRegistry, } from "./dispatcher.js";
-import { FactStore } from "./fact-store.js";
+import { recordDegradationOnce } from "../degradation-ledger.js";
+import { FactStore, setFactStoreEvictionReporter } from "./fact-store.js";
 import { TOOL_PLANS } from "./plan.js";
 // Re-export latency tracking types and functions
 export { clearLatencyReports, formatLatencyReport, getLatencyReports };
@@ -37,7 +38,7 @@ import { clearModuleGraphCache } from "../review-graph/workspace-modules.js";
 import { releaseWorkspaceTopologyIdleTimers } from "../workspace-topology.js";
 import { RUNTIME_CONFIG } from "../runtime-config.js";
 import { findCompiledClassesDir, hasJavaBuildDescriptor, } from "../tool-policy.js";
-import { removeWordIndexDocument, updateWordIndexDocument, WORD_INDEX_MAX_BYTES, } from "../word-index.js";
+import { removeWordIndexDocumentAsync, updateWordIndexDocumentForEdit, WORD_INDEX_MAX_BYTES, } from "../word-index.js";
 import { reconcileCascadeNeighborLspErrors } from "../widget-state.js";
 import { findAuxiliaryProfileForSource } from "./auxiliary-lsp.js";
 // Register fact providers. All register eagerly here (the dispatch entry) — the
@@ -98,7 +99,46 @@ registerRule(commentedCredentialsRule);
 export function applyProjectLensConfig(cwd) {
     return loadPiLensProjectConfig(cwd);
 }
-const sessionFacts = new FactStore();
+// "dispatch" labels this store's eviction telemetry (#2243 review round 3,
+// F1) — five other production FactStore instances exist (mcp/analyze.ts,
+// lens-map.ts, project-diagnostics/scanner.ts, runtime-session.ts's
+// session-start call-graph task, mcp/cli.ts); a shared constant subject let
+// runtime-session's session-start review-graph walk consume the once-per-
+// session ledger slot before any dispatch ran, misattributing the record.
+const sessionFacts = new FactStore("dispatch");
+// #2243 item 4: wire the fact-store's capacity-eviction telemetry to the
+// ledger from HERE, not from fact-store.ts. fact-store stays an import leaf so
+// it cannot re-enter the safe-spawn ↔ degradation-ledger cycle (see
+// `setFactStoreEvictionReporter`). The reporter forwards each store's own
+// subject, so the ledger's per-kind+subject dedupe emits exactly ONE record
+// per session PER STORE, re-arming when the ledger resets at session_start.
+//
+// #2247 review F1: the axis was previously dropped here, so
+// `recordDegradationOnce`'s `${kind}\0${subject}` dedupe collapsed a store's
+// count-axis and byte-axis evictions onto the SAME key — whichever axis
+// tripped first (always count, since 1024 typical files land far under 64
+// MiB) silently consumed the once-per-session slot and a later byte-axis
+// eviction on that same store recorded nothing. Fold the axis into the
+// subject (`<store>:<axis>`), matching this ledger's own `<store>:<file>`
+// convention (see `demoted-finding-retired`'s doc comment) rather than
+// growing the `kind` union per axis. `pinned-over-budget` (#2247 review F2)
+// is a distinct condition, not an eviction, so it gets its own kind instead
+// of sharing the eviction kind's subject convention.
+setFactStoreEvictionReporter((subject, axis, reason) => {
+    if (axis === "pinned-over-budget") {
+        recordDegradationOnce({
+            kind: "fact-store-pinned-over-budget",
+            subject,
+            reason,
+        });
+        return;
+    }
+    recordDegradationOnce({
+        kind: "fact-store-capacity-eviction",
+        subject: `${subject}:${axis}`,
+        reason,
+    });
+});
 const cascadeDiagnosticBaselines = new Map();
 const sessionRunnerRegistry = new RunnerRegistry();
 registerDefaultRunners(sessionRunnerRegistry);
@@ -137,32 +177,62 @@ function scheduleAstGrepWarningScan(filePath, cwd, pi, logContext) {
     const existing = astGrepWarnDebounceTimers.get(filePath);
     if (existing)
         clearTimeout(existing);
-    const timer = setTimeout(async () => {
+    const timer = setTimeout(() => {
         astGrepWarnDebounceTimers.delete(filePath);
-        try {
-            const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, false);
-            if (ctx.kind !== "jsts")
-                return;
-            // Single-runner group: ast-grep only, warning mode (blockingOnly=false)
-            const group = {
-                mode: "all",
-                runnerIds: ["ast-grep"],
-                filterKinds: ["jsts"],
-            };
-            const result = await dispatchForFile(ctx, [group], sessionRunnerRegistry);
-            if (result.diagnostics.length === 0)
-                return;
-            const logger = getDiagnosticLogger();
-            for (const d of result.diagnostics) {
-                logger.logCaught(d, logContext, false);
-            }
-        }
-        catch {
+        void runAstGrepWarningScan(filePath, cwd, pi, logContext).catch(() => {
             // Non-critical background scan — swallow errors silently
-        }
+        });
     }, AST_GREP_WARN_DEBOUNCE_MS);
     astGrepWarnDebounceTimers.set(filePath, timer);
 }
+/**
+ * Run the debounced ast-grep warning scan for one jsts file.
+ *
+ * #2243 item 1: this is a dispatch entry point like dispatchLint*, so it must
+ * follow the same discipline. It fires ~2 s after the last write, and in that
+ * window the review-graph project walk (`buildOrUpdateGraph`) seeds facts for
+ * every file into the SAME `sessionFacts`, which can evict this file's
+ * `file.content`. `dispatcher.ts` reads that fact back with `?? ""` for inline
+ * suppressions, so a stale or evicted read silently stops applying
+ * `pi-lens-ignore`. Two guards, matching the other dispatch callers:
+ *   1. `beginDispatchFor` pins the file for the dispatch (released in the
+ *      finally), so a concurrent walk cannot evict it mid-dispatch. This
+ *      does NOT clear the file's existing facts the way `clearFileFactsFor`
+ *      does for the other dispatch callers (#2243 review round 3, F5): this
+ *      scan fires ~2s after the SAME edit's inline dispatch already
+ *      re-derived every fact for this file, so a second clear+re-derive
+ *      here bought nothing but ~51ms of redundant re-parsing across all
+ *      five providers (measured; a warm-cache read is ~1ms).
+ *   2. `runProviders` still re-derives `file.content` when it's actually
+ *      missing (a genuine miss — evicted, or never computed), so the read
+ *      never depends on staleness.
+ * `facts` is injected only for tests; production always uses `sessionFacts`.
+ */
+export async function runAstGrepWarningScan(filePath, cwd, pi, logContext, facts = sessionFacts) {
+    const ctx = createDispatchContext(filePath, cwd, pi, facts, false);
+    if (ctx.kind !== "jsts")
+        return;
+    facts.beginDispatchFor(ctx.filePath);
+    try {
+        // Single-runner group: ast-grep only, warning mode (blockingOnly=false)
+        const group = {
+            mode: "all",
+            runnerIds: ["ast-grep"],
+            filterKinds: ["jsts"],
+        };
+        await runProviders(ctx);
+        const result = await dispatchForFile(ctx, [group], sessionRunnerRegistry);
+        if (result.diagnostics.length === 0)
+            return;
+        const logger = getDiagnosticLogger();
+        for (const d of result.diagnostics) {
+            logger.logCaught(d, logContext, false);
+        }
+    }
+    finally {
+        facts.endDispatchFor(ctx.filePath);
+    }
+}
 function resetSessionSlopScore() {
     sessionSlopRuleCounts.clear();
     sessionSlopDiagnosticCount = 0;
@@ -496,6 +566,11 @@ function touchReverseDepsEntry(key, entry, armIdleTimer = true) {
     entry.idleTimer.unref?.();
 }
 function setReverseDepsEntry(key, entry, armIdleTimer = true) {
+    const previous = reverseDepsIndexCache.get(key);
+    if (previous?.idleTimer !== undefined) {
+        clearTimeout(previous.idleTimer);
+        previous.idleTimer = undefined;
+    }
     const resident = { ...entry, lastUsedAt: Date.now() };
     reverseDepsIndexCache.set(key, resident);
     touchReverseDepsEntry(key, resident, armIdleTimer);
@@ -604,20 +679,28 @@ function isIgnoredCascadeNeighbor(filePath, cwd) {
  *    debounced persist (never a synchronous write per edit — same #260
  *    discipline as the graph).
  *
- * Race safety against a build-in-progress: this function body is entirely
- * synchronous (no `await` anywhere in it) and is called synchronously at
- * `computeCascadeForFile`'s entry, before its own `await buildOrUpdateGraph`.
- * Node is single-threaded, so two overlapping cascades (#450's unawaited
- * concurrency) can never interleave mid-mutation here — each call runs to
- * completion in one turn. The only cross-build hazard is a full session-start
- * rebuild REPLACING `runtime.wordIndex` with a new object between the caller
- * reading `runtime.wordIndex` (in runtime-tool-result.ts, also synchronous)
- * and this function receiving it — in that case this call simply mutates
- * whichever index object it was handed (old or new), and the other one is
- * abandoned/superseded, never corrupted. No queue, no lock: the simplest rule
- * that is still provably correct.
+ * Race safety against a build-in-progress: the update runs cooperatively, on
+ * an 8 ms budget, through the word index's own per-index operation queue
+ * (#2067 AC4). It used to run synchronously here, on the reasoning that two
+ * overlapping cascades (#450's unawaited concurrency) could not interleave
+ * mid-mutation if nothing ever yielded — the reviewer's 300-document probe had
+ * lost 1,719 postings during an 8 ms yield. That hazard is what the queue
+ * closed: every async operation on one index is chained behind the previous
+ * one in call order, so overlapping cascades are ordered rather than
+ * interleaved, and the cooperative arena compactor is separately proof against
+ * a synchronous edit landing mid-copy (#2117 review F2). What the synchronous
+ * variant could not fix is its own cost: one replacement on a 2,600-document
+ * corpus held the event loop for the whole replacement, which is the block
+ * #2067 measured at 1.1 s before interning and still tens of ms after it.
+ *
+ * The only cross-build hazard is a full session-start rebuild REPLACING
+ * `runtime.wordIndex` with a new object between the caller reading
+ * `runtime.wordIndex` (in runtime-tool-result.ts, synchronous) and this
+ * function receiving it — in that case this call simply mutates whichever
+ * index object it was handed (old or new), and the other one is
+ * abandoned/superseded, never corrupted.
  */
-function updateWordIndexForCascade(args) {
+async function updateWordIndexForCascade(args) {
     const { wordIndex, filePath, content, onUpdated, dbg } = args;
     if (!wordIndex || !wordIndex.forward)
         return;
@@ -625,11 +708,14 @@ function updateWordIndexForCascade(args) {
         return;
     const byteLength = Buffer.byteLength(content, "utf-8");
     if (byteLength > WORD_INDEX_MAX_BYTES) {
-        removeWordIndexDocument(wordIndex, filePath);
+        await removeWordIndexDocumentAsync(wordIndex, filePath);
         dbg?.(`word-index per-edit: dropped ${filePath} (over size cap)`);
     }
     else {
-        updateWordIndexDocument(wordIndex, { path: filePath, content });
+        await updateWordIndexDocumentForEdit(wordIndex, {
+            path: filePath,
+            content,
+        });
         dbg?.(`word-index per-edit: updated ${filePath}`);
     }
     onUpdated?.(wordIndex);
@@ -689,7 +775,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
         // The old hazard — this update silently orphaning a SECOND entry next to the
         // walker's original-cased one — is now structurally impossible at the map
         // layer, so this seam no longer has to hand-match the build path's key shape.
-        updateWordIndexForCascade({
+        await updateWordIndexForCascade({
             wordIndex,
             filePath: nodePath.resolve(filePath),
             content: fileContent,
@@ -1982,16 +2068,23 @@ export async function dispatchLint(filePath, cwd, pi, modifiedRanges, projectRoo
     // pre-existing issues after the first write.
     const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, true, modifiedRanges, projectRoot);
     sessionFacts.clearFileFactsFor(ctx.filePath);
-    const kind = ctx.kind;
-    if (!kind)
-        return "";
-    const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
-    if (groups.length === 0)
-        return "";
-    await runProviders(ctx);
-    const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry);
-    trackSessionSlopStats(ctx, result.diagnostics);
-    return result.output;
+    // #2243 item 2: release the pin when the dispatch settles, so the pin set
+    // tracks in-flight dispatches rather than the last N files touched.
+    try {
+        const kind = ctx.kind;
+        if (!kind)
+            return "";
+        const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
+        if (groups.length === 0)
+            return "";
+        await runProviders(ctx);
+        const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry);
+        trackSessionSlopStats(ctx, result.diagnostics);
+        return result.output;
+    }
+    finally {
+        sessionFacts.endDispatchFor(ctx.filePath);
+    }
 }
 /**
  * Run linting and return full result (including diagnostics)
@@ -2002,44 +2095,50 @@ export async function dispatchLintWithResult(filePath, cwd, pi, modifiedRanges,
     // facade, pass blockingOnly=false to run every runner.
     const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, options?.blockingOnly ?? true, modifiedRanges, options?.projectRoot, options?.writeIndex, options?.telemetryModel, options?.telemetryProvider);
     sessionFacts.clearFileFactsFor(ctx.filePath);
-    const kind = ctx.kind;
-    if (!kind) {
-        return {
-            diagnostics: [],
-            blockers: [],
-            warnings: [],
-            baselineWarningCount: 0,
-            fixed: [],
-            resolvedCount: 0,
-            output: "",
-            blockerOutput: "",
-            hasBlockers: false,
-        };
-    }
-    const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
-    if (groups.length === 0) {
-        return {
-            diagnostics: [],
-            blockers: [],
-            warnings: [],
-            baselineWarningCount: 0,
-            fixed: [],
-            resolvedCount: 0,
-            output: "",
-            blockerOutput: "",
-            hasBlockers: false,
-        };
+    // #2243 item 2: release the pin when the dispatch settles.
+    try {
+        const kind = ctx.kind;
+        if (!kind) {
+            return {
+                diagnostics: [],
+                blockers: [],
+                warnings: [],
+                baselineWarningCount: 0,
+                fixed: [],
+                resolvedCount: 0,
+                output: "",
+                blockerOutput: "",
+                hasBlockers: false,
+            };
+        }
+        const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
+        if (groups.length === 0) {
+            return {
+                diagnostics: [],
+                blockers: [],
+                warnings: [],
+                baselineWarningCount: 0,
+                fixed: [],
+                resolvedCount: 0,
+                output: "",
+                blockerOutput: "",
+                hasBlockers: false,
+            };
+        }
+        await runProviders(ctx);
+        const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry);
+        trackSessionSlopStats(ctx, result.diagnostics);
+        // Schedule debounced ast-grep warning scan for jsts files.
+        // Runs 2s after the last write — collapses rapid sequential edits into one scan.
+        // Results are logged only, never surfaced to the agent.
+        if (kind === "jsts" && logContext) {
+            scheduleAstGrepWarningScan(filePath, cwd, pi, logContext);
+        }
+        return result;
     }
-    await runProviders(ctx);
-    const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry);
-    trackSessionSlopStats(ctx, result.diagnostics);
-    // Schedule debounced ast-grep warning scan for jsts files.
-    // Runs 2s after the last write — collapses rapid sequential edits into one scan.
-    // Results are logged only, never surfaced to the agent.
-    if (kind === "jsts" && logContext) {
-        scheduleAstGrepWarningScan(filePath, cwd, pi, logContext);
+    finally {
+        sessionFacts.endDispatchFor(ctx.filePath);
     }
-    return result;
 }
 /**
  * Same real dispatch path as {@link dispatchLintWithResult} (real context, real
@@ -2064,20 +2163,26 @@ export async function dispatchLintDetailed(filePath, cwd, pi, options) {
     };
     const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, options?.blockingOnly ?? false, options?.modifiedRanges, options?.projectRoot);
     sessionFacts.clearFileFactsFor(ctx.filePath);
-    const kind = ctx.kind;
-    if (!kind)
-        return { result: empty, runners: [] };
-    const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
-    if (groups.length === 0)
-        return { result: empty, runners: [] };
-    const runners = [];
-    const sink = (runnerId, result) => {
-        runners.push({ runnerId, result });
-    };
-    await runProviders(ctx);
-    const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry, sink);
-    trackSessionSlopStats(ctx, result.diagnostics);
-    return { result, runners };
+    // #2243 item 2: release the pin when the dispatch settles.
+    try {
+        const kind = ctx.kind;
+        if (!kind)
+            return { result: empty, runners: [] };
+        const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
+        if (groups.length === 0)
+            return { result: empty, runners: [] };
+        const runners = [];
+        const sink = (runnerId, result) => {
+            runners.push({ runnerId, result });
+        };
+        await runProviders(ctx);
+        const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry, sink);
+        trackSessionSlopStats(ctx, result.diagnostics);
+        return { result, runners };
+    }
+    finally {
+        sessionFacts.endDispatchFor(ctx.filePath);
+    }
 }
 /**
  * Check if a file should be processed by the dispatcher

package/node_modules/pi-lens/dist/clients/dispatch/pending-runner-findings.js

@@ -0,0 +1,87 @@
+/** Turn-end handoff for runners moved off the post-write critical path. */
+import { incrementDegradationCount } from "../degradation-ledger.js";
+const pending = [];
+export const MAX_PENDING_RUNNER_FINDINGS = 50;
+export function deferRunnerFindings(entry) {
+    const tracked = { ...entry, settled: false };
+    // Attach exactly once at ownership time. Re-attaching at every turn end
+    // accumulates handlers on a promise that may never settle (#2122 F8).
+    void tracked.promise.then((result) => {
+        tracked.result = result;
+        tracked.settled = true;
+    }, (error) => {
+        tracked.result = {
+            status: "failed",
+            diagnostics: [],
+            semantic: "warning",
+            failureKind: "exception",
+            failureMessage: String(error).slice(0, 200),
+        };
+        tracked.settled = true;
+    });
+    pending.push(tracked);
+    if (pending.length > MAX_PENDING_RUNNER_FINDINGS) {
+        const evicted = pending.shift();
+        if (evicted) {
+            incrementDegradationCount({
+                kind: "runner-findings-evicted",
+                subject: `${evicted.runnerId}:${evicted.filePath}`,
+                reason: `pending runner cap ${MAX_PENDING_RUNNER_FINDINGS}`,
+            });
+        }
+    }
+}
+/**
+ * Resolve already-finished runner work for this turn. Unfinished work remains
+ * owned by the store and is retried at the next turn boundary.
+ */
+export async function drainPendingRunnerFindings(maxWaitMs = 2_000) {
+    if (pending.length === 0)
+        return [];
+    const current = pending.splice(0, pending.length);
+    const results = [];
+    // Give already-resolved promises one microtask turn without introducing a
+    // wall-clock wait. This observes completed work while preserving the F5
+    // zero-budget contract for in-flight runners.
+    if (maxWaitMs === 0)
+        await Promise.resolve();
+    if (maxWaitMs > 0 && current.some((entry) => !entry.settled)) {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, maxWaitMs);
+            timer.unref?.();
+        });
+    }
+    for (const entry of current) {
+        if (entry.settled && entry.result) {
+            results.push({
+                filePath: entry.filePath,
+                cwd: entry.cwd,
+                projectRoot: entry.projectRoot,
+                runnerId: entry.runnerId,
+                markedAtMs: entry.markedAtMs,
+                writeIndex: entry.writeIndex,
+                result: entry.result,
+            });
+        }
+        else {
+            pending.push(entry);
+        }
+    }
+    return results;
+}
+/** Drop a stale answer and record the lost re-run coverage. */
+export function dropStaleRunnerFindings(entry) {
+    if (!entry.result)
+        return;
+    incrementDegradationCount({
+        kind: "runner-findings-stale",
+        subject: `${entry.runnerId}:${entry.filePath}`,
+        reason: "completed result was older than the latest file edit",
+    });
+}
+export function resetPendingRunnerFindings() {
+    pending.length = 0;
+}
+export function pendingRunnerFindingsSize() {
+    return pending.length;
+}

package/node_modules/pi-lens/dist/clients/dispatch/plan.js

@@ -95,7 +95,10 @@ export const LANGUAGE_CAPABILITY_MATRIX = {
     json: {
         name: "JSON Processing",
         capabilities: ["format", "lint"],
-        writeGroups: [primary("json")],
+        writeGroups: [
+            primary("json"),
+            { mode: "all", runnerIds: ["trivy-config"], filterKinds: ["json"] },
+        ],
     },
     markdown: {
         name: "Markdown Processing",
@@ -108,7 +111,11 @@ export const LANGUAGE_CAPABILITY_MATRIX = {
     css: {
         name: "CSS Processing",
         capabilities: ["format", "lint"],
-        writeGroups: [primary("css")],
+        writeGroups: [
+            primary("css"),
+            { mode: "all", runnerIds: ["tree-sitter"], filterKinds: ["css"] },
+            { mode: "all", runnerIds: ["ast-grep-napi"], filterKinds: ["css"] },
+        ],
     },
     yaml: {
         name: "YAML Processing",
@@ -131,7 +138,10 @@ export const LANGUAGE_CAPABILITY_MATRIX = {
     html: {
         name: "HTML Linting",
         capabilities: ["lint"],
-        writeGroups: [primary("html")],
+        writeGroups: [
+            primary("html"),
+            { mode: "all", runnerIds: ["ast-grep-napi"], filterKinds: ["html"] },
+        ],
     },
     docker: {
         name: "Dockerfile Linting",
@@ -141,7 +151,10 @@ export const LANGUAGE_CAPABILITY_MATRIX = {
     php: {
         name: "PHP Linting",
         capabilities: ["types", "lint"],
-        writeGroups: [primary("php")],
+        writeGroups: [
+            primary("php"),
+            { mode: "all", runnerIds: ["tree-sitter"], filterKinds: ["php"] },
+        ],
     },
     powershell: {
         name: "PowerShell Linting",
@@ -156,7 +169,10 @@ export const LANGUAGE_CAPABILITY_MATRIX = {
     csharp: {
         name: "C# Linting",
         capabilities: ["types", "lint"],
-        writeGroups: [primary("csharp")],
+        writeGroups: [
+            primary("csharp"),
+            { mode: "all", runnerIds: ["tree-sitter"], filterKinds: ["csharp"] },
+        ],
     },
     fsharp: {
         name: "F# Linting",