@herbertgao/pi-extensions 2026.8.14 → 2026.8.15

package/node_modules/pi-lens/dist/clients/degradation-ledger.js

@@ -3,6 +3,12 @@ import { logExtension } from "./extension-log.js";
 import { LEDGER_FIELD_MAX, truncateForLedger } from "./ledger-bounds.js";
 import { logLatency } from "./latency-logger.js";
 import { getSinkWriteFailures, resetSinkWriteFailures, } from "./ndjson-logger.js";
+// #2146: pulled at READ time, never pushed. `process-singletons.ts` is a
+// dependency leaf on purpose — it cannot import this module without closing a
+// no-client-cycles cycle through instance-registry/instance-reaper — so the
+// ledger reaches IN for its reset log, the same inversion `getSinkWriteFailures`
+// above uses.
+import { getProcessSingletonResets, PROCESS_SINGLETON_RESET_KIND, } from "./process-singletons.js";
 // Re-exported so existing importers keep one name for the ledger's bound.
 export { LEDGER_FIELD_MAX, truncateForLedger };
 const ENTRIES_PER_KIND = 20;
@@ -59,7 +65,7 @@ export function recordDegradationOnce(record) {
             return;
         onceKeys.add(key);
         if (recordDegradation({ kind, subject, reason: record.reason })) {
-            logDurableDegradation(kind, subject, 1);
+            logDurableDegradation(kind, subject, 1, record.metadata);
         }
     }
     catch (error) {
@@ -108,7 +114,7 @@ export function incrementDegradationCount(record) {
         // Durable rows use the summary's admission and emit the first event and
         // power-of-two milestones only, keeping the sink bounded.
         if (admitted && isPowerOfTwo(count)) {
-            logDurableDegradation(kind, subject, count);
+            logDurableDegradation(kind, subject, count, record.metadata);
         }
         return count === 1;
     }
@@ -124,15 +130,34 @@ export function incrementDegradationCount(record) {
  * redaction, and write queue. The subject and kind were already bounded by the
  * ledger before reaching this seam.
  */
-function logDurableDegradation(kind, subject, count) {
+function logDurableDegradation(kind, subject, count, metadata) {
+    const boundedMetadata = boundLedgerMetadata(metadata);
     logLatency({
         type: "phase",
         phase: "degradation_ledger",
         filePath: subject,
         durationMs: 0,
-        metadata: { kind, subject, count, ledgerGeneration },
+        metadata: {
+            ...boundedMetadata,
+            kind,
+            subject,
+            count,
+            ledgerGeneration,
+        },
     });
 }
+const MAX_METADATA_KEYS = 8;
+function boundLedgerMetadata(metadata) {
+    if (!metadata)
+        return {};
+    const entries = Object.entries(metadata);
+    const kept = entries.slice(0, MAX_METADATA_KEYS);
+    const bounded = Object.fromEntries(kept.map(([key, value]) => [key, truncateForLedger(value)]));
+    const dropped = entries.length - kept.length;
+    if (dropped > 0)
+        bounded.metadataDropped = dropped;
+    return bounded;
+}
 function isPowerOfTwo(value) {
     return value > 0 && (value & (value - 1)) === 0;
 }
@@ -165,6 +190,21 @@ export function getDegradationSummary() {
             })),
         });
     }
+    // #2146, same read-time fold: process-singleton resets live in the leaf
+    // module's own bounded log. One entry per family, so this group's count is
+    // the number of families this build could not adopt, never an event tally.
+    const singletonResets = getProcessSingletonResets();
+    if (singletonResets.length > 0) {
+        summary.push({
+            kind: PROCESS_SINGLETON_RESET_KIND,
+            count: singletonResets.length,
+            droppedCount: 0,
+            latestReasons: singletonResets.map((reset) => ({
+                subject: truncateForLedger(reset.family),
+                reason: truncateForLedger(reset.reason),
+            })),
+        });
+    }
     return summary;
 }
 function isRenderableSummary(value) {
@@ -218,6 +258,18 @@ export function resetDegradationLedger() {
     // process-lifetime latch too — it re-arms alongside the rest of the
     // ledger rather than surviving past the session that observed it.
     resetSinkWriteFailures();
+    // #2146 review F3: the OTHER pulled source, `getProcessSingletonResets()`,
+    // deliberately does NOT re-arm here, and the difference from its neighbour
+    // above is the point. A sink write failure recurs — new writes fail, so
+    // clearing the tally costs nothing and a later session re-observes the
+    // problem. A process-singleton reset happens once, at module-evaluation
+    // time, and cannot recur: after it, the container holds only compatible
+    // cells. Clearing it would show the fact in the first session's
+    // `pilens_health` and hide it from every session after, which is exactly
+    // when someone reads that line. The row is bounded independently of the
+    // session (one entry per family, capped at 16), so leaving it costs a fixed
+    // handful of lines and keeps a process-scope fact visible for the process's
+    // life. Deliberate exception to catalog shape 17, not an oversight.
 }
 export const DEGRADATION_ENTRIES_PER_KIND = ENTRIES_PER_KIND;
 export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;

package/node_modules/pi-lens/dist/clients/demoted-finding-render.js

@@ -153,3 +153,17 @@ export function formatRetirementNote(deadLines) {
     return (`Retired after this delivery${cited}: the file no longer has these lines, ` +
         "so this finding cannot be re-confirmed and will not be served again.");
 }
+/**
+ * The one-line note a surface appends when it RETIRES a dependency-drift
+ * demotion at its delivery cap (#1950). Deliberately worded differently from
+ * {@link formatRetirementNote}: that one means the finding is provably
+ * unrecoverable (the cited lines are gone), while THIS retirement is a
+ * bounded-noise cap on a record that is still recoverable — a fresh dispatch
+ * of the file could still confirm or clear it. Saying "cannot be re-confirmed"
+ * here would be false.
+ */
+export function formatDeliveryCapNote(deliveryCount) {
+    return (`Not shown again after ${deliveryCount} deliveries with no re-run: ` +
+        "this finding may still be accurate, but re-serving it further adds no " +
+        "new information. A fresh dispatch of this file will re-confirm or clear it.");
+}

package/node_modules/pi-lens/dist/clients/dependency-checker.js

@@ -14,6 +14,7 @@ import * as path from "node:path";
 import { findNodeToolBinary } from "./package-manager.js";
 import { isFullyQualified } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { compareOrdinal } from "./string-utils.js";
 import { createAvailabilityChecker, discoverManagedTool, getManagedToolEnvironment, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
 import { createAvailabilityLatch, } from "./dispatch/runners/utils/availability-policy.js";
 /**
@@ -501,8 +502,14 @@ export class DependencyChecker {
         const existing = this.checkInFlight.get(key);
         if (existing)
             return existing;
+        // Identity-guarded release (#1968's pattern): delete only if THIS run is
+        // still the registered one. A bare delete-by-key lets a late-settling run
+        // evict a live successor a second writer registered under the same key
+        // mid-flight, after which the next caller starts a duplicate check.
         const promise = this.runCheckFile(normalized, projectRoot, gen).finally(() => {
-            this.checkInFlight.delete(key);
+            if (this.checkInFlight.get(key) === promise) {
+                this.checkInFlight.delete(key);
+            }
         });
         this.checkInFlight.set(key, promise);
         return promise;
@@ -781,8 +788,14 @@ export class DependencyChecker {
         // does, and the two overlap (runtime-session, fresh-fetch), so it takes a
         // generation too — claimed before the spawn, as late as a scan can.
         const gen = ++this.opGeneration;
+        // Identity-guarded release (#1968's pattern): delete only if THIS run is
+        // still the registered one. A bare delete-by-key lets a late-settling run
+        // evict a live successor a second writer registered under the same key
+        // mid-flight, after which the next caller starts a duplicate scan.
         const promise = this.runScanProject(projectRoot, gen).finally(() => {
-            this.scanInFlight.delete(projectRoot);
+            if (this.scanInFlight.get(projectRoot) === promise) {
+                this.scanInFlight.delete(projectRoot);
+            }
         });
         this.scanInFlight.set(projectRoot, promise);
         return promise;
@@ -830,7 +843,11 @@ export class DependencyChecker {
         const seen = new Set();
         let output = `[Circular Deps] ${circular.length} cycle(s) found:\n`;
         for (const dep of circular) {
-            const cycleKey = dep.path.sort((a, b) => a.localeCompare(b)).join("→");
+            // Copy before sorting: `dep.path` is rendered verbatim below (and by
+            // other CircularDep consumers, e.g. madge.ts's diagnostic renderer),
+            // so the dedupe key must not reorder — let alone mutate in place —
+            // the path a user reads.
+            const cycleKey = [...dep.path].sort(compareOrdinal).join("→");
             if (seen.has(cycleKey))
                 continue;
             seen.add(cycleKey);

package/node_modules/pi-lens/dist/clients/deps/minimatch.js

@@ -1,4 +1,4 @@
 /**
  * Centralized accessor for `minimatch`. See ./typescript.ts for the rationale.
  */
-export { minimatch } from "minimatch";
+export { minimatch, Minimatch } from "minimatch";

package/node_modules/pi-lens/dist/clients/dispatch/collect-later-tier.js

@@ -0,0 +1,39 @@
+/** Observed-latency classification shared by dispatch and LSP tier seams. */
+import { normalizeMapKey } from "../path-utils.js";
+/** A runner gets this much time before the next run moves off the write path. */
+export const COLLECT_LATER_THRESHOLD_MS = 5_000;
+const slowRunners = new Map();
+function key(projectRoot, runnerId) {
+    return `${normalizeMapKey(projectRoot)}\u0000${runnerId}`;
+}
+/** Read the current observed tier. Missing observations stay inline. */
+export function classifyObservedRunner(projectRoot, runnerId) {
+    return slowRunners.has(key(projectRoot, runnerId))
+        ? "collect-later"
+        : "inline";
+}
+/** Record one completed latency observation and return the resulting tier. */
+export function observeRunnerLatency(options) {
+    const normalizedProjectRoot = normalizeMapKey(options.projectRoot);
+    const runnerKey = key(normalizedProjectRoot, options.runnerId);
+    if (options.timedOut === true ||
+        options.durationMs > COLLECT_LATER_THRESHOLD_MS) {
+        slowRunners.set(runnerKey, {
+            projectRoot: normalizedProjectRoot,
+            runnerId: options.runnerId,
+        });
+        return "collect-later";
+    }
+    // A fast completed run is affirmative recovery, not merely absence of a
+    // failure. This deliberately prevents a process-lifetime latch.
+    slowRunners.delete(runnerKey);
+    return "inline";
+}
+/** Session boundary reset. */
+export function resetObservedRunnerLatency() {
+    slowRunners.clear();
+}
+/** Test-only inspection without exposing mutable state. */
+export function observedRunnerTierForTests(projectRoot, runnerId) {
+    return classifyObservedRunner(projectRoot, runnerId);
+}

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

@@ -17,6 +17,7 @@ import { logExtension } from "../extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { recordRunner } from "../widget-state.js";
+import { incrementDegradationCount } from "../degradation-ledger.js";
 import { detectFileKind } from "../file-kinds.js";
 import { detectFileRole } from "../file-role.js";
 import { isTestFile } from "../file-utils.js";
@@ -24,19 +25,24 @@ import { getPrimaryDispatchGroup } from "../language-policy.js";
 import { resolveLanguageRootForFile } from "../language-profile.js";
 import { logLatency, phaseFinished, phaseStarted } from "../latency-logger.js";
 import { isSpawnableCommand } from "../installer/index.js";
-import { normalizeMapKey } from "../path-utils.js";
+import { normalizeEphemeralMapKey, normalizeMapKey } from "../path-utils.js";
 import { loadPiLensProjectConfig } from "../project-lens-config.js";
 import { RUNTIME_CONFIG, getRunnerTimeoutFloorMs } from "../runtime-config.js";
 import { safeSpawnAsync } from "../safe-spawn.js";
 import { classifyDiagnostic } from "./diagnostic-taxonomy.js";
 import { classifyProbeFailure, logAvailabilityDecision, startHostStallSampler, transientRetryDelayMs, } from "./runners/utils/availability-policy.js";
+import { recordAvailabilityProbeOverrun, getDispatchAvailabilityGeneration, } from "./runners/utils/runner-helpers.js";
+import { createAvailabilityProbeFlight } from "../availability-probe-flight.js";
 import { applyDispositions } from "../diagnostic-dispositions.js";
 import { applyInlineSuppressions } from "./inline-suppressions.js";
 import { getToolPlan } from "./plan.js";
 import { resolveRunnerPath } from "./runner-context.js";
+import { classifyObservedRunner, COLLECT_LATER_THRESHOLD_MS, observeRunnerLatency, } from "./collect-later-tier.js";
+import { deferRunnerFindings } from "./pending-runner-findings.js";
 import { applyRulePolicy, rulePolicyMapFromConfig } from "./rule-policy.js";
 import { getToolProfile } from "./tool-profile.js";
 import { isRunnerSkipReason } from "./types.js";
+const dispatcherProbeFlights = createAvailabilityProbeFlight({ generation: () => getDispatchAvailabilityGeneration() });
 import { formatDiagnostics } from "./utils/format-utils.js";
 // --- Runner Registry ---
 export class RunnerRegistry {
@@ -134,15 +140,19 @@ export async function checkToolAvailability(command, facts) {
         const startedAt = Date.now();
         let result;
         let hostStallMs;
+        let probeJoined = false;
         try {
-            result = await safeSpawnAsync(command, ["--version"], {
+            const shared = dispatcherProbeFlights.run(`dispatcher:${key}`, () => safeSpawnAsync(command, ["--version"], {
                 timeout: TOOL_PROBE_TIMEOUT_MS,
-            });
+            }));
+            probeJoined = shared.joined;
+            result = await shared.promise;
         }
         finally {
             hostStallMs = sampler.stop();
         }
         const elapsedMs = Date.now() - startedAt;
+        recordAvailabilityProbeOverrun(command, key, elapsedMs, TOOL_PROBE_TIMEOUT_MS, result.failure);
         if (result.status === 0) {
             facts.setSessionFact(key, true);
             // The tool answered: retire the cooldown facts rather than leaving a
@@ -156,6 +166,7 @@ export async function checkToolAvailability(command, facts) {
                 cause: "ok",
                 elapsedMs,
                 latched: true,
+                classifiedBy: probeJoined ? "joined" : "probe",
                 hostStallMs,
                 budgetMs: TOOL_PROBE_TIMEOUT_MS,
             });
@@ -188,7 +199,7 @@ export async function checkToolAvailability(command, facts) {
             hostStallMs,
             ...(retryAfterMs !== undefined && { retryAfterMs }),
             budgetMs: TOOL_PROBE_TIMEOUT_MS,
-            classifiedBy: "probe",
+            classifiedBy: probeJoined ? "joined" : "probe",
             evidence,
         });
         return false;
@@ -419,13 +430,19 @@ function buildCoverageNotice(ctx, runnerLatencies) {
         // The marker describes this exact silent-scanner set. A scanner can
         // recover while another goes dark on the same file, so the set belongs
         // in the session dedupe identity rather than only kind and path.
+        // #2016: these are SCANNER IDS, not filesystem paths. `normalizeMapKey`
+        // would realpath each one; on Windows that fails, falls through to
+        // `resolveNonExisting`, and resolves the id against the CURRENT process
+        // cwd, so the dedupe key differed by platform and by cwd (the #2219
+        // non-path-sentinel class). The cheap syntactic fold is what this
+        // session-scoped dedupe key actually needs.
         const silentScannerSet = [...new Set(unconfirmedServerIds)]
-            .map(normalizeMapKey)
+            .map(normalizeEphemeralMapKey)
             // Code-unit comparator: the sorted set is a dedupe KEY, so ordering
             // must be deterministic across locales — localeCompare is not.
             .sort((a, b) => Number(a > b) - Number(a < b))
             .join(",");
-        const onceKey = `${ctx.kind}:${normalizeMapKey(ctx.filePath)}:${silentScannerSet}`;
+        const onceKey = `${ctx.kind}:${ctx.filePath}:${silentScannerSet}`;
         if (coverageNoticeSeen.has(onceKey))
             return undefined;
         coverageNoticeSeen.add(onceKey);
@@ -467,7 +484,7 @@ function buildCoverageNotice(ctx, runnerLatencies) {
         (r.status === "succeeded" || r.status === "failed"));
     if (anyLinterHasCoverage)
         return undefined;
-    const onceKey = `${ctx.kind}:${normalizeMapKey(ctx.filePath)}`;
+    const onceKey = `${ctx.kind}:${ctx.filePath}`;
     if (coverageNoticeSeen.has(onceKey))
         return undefined;
     coverageNoticeSeen.add(onceKey);
@@ -603,10 +620,123 @@ async function runGroup(ctx, group, registry, onRunnerResult) {
             });
             continue;
         }
+        const projectRoot = ctx.projectRoot ?? ctx.cwd;
+        // Only post-write dispatches participate. Project scans and direct API
+        // callers must retain their existing synchronous semantics.
+        const observedTier = ctx.writeIndex === undefined
+            ? "inline"
+            : classifyObservedRunner(projectRoot, runner.id);
+        if (observedTier === "collect-later") {
+            const markedAtMs = Date.now();
+            const deferred = runRunner(ctx, runner, semantic).then((result) => {
+                const durationMs = Date.now() - markedAtMs;
+                const tier = observeRunnerLatency({
+                    projectRoot,
+                    runnerId: runner.id,
+                    durationMs,
+                    timedOut: result.failureKind === "timeout",
+                });
+                if (tier !== observedTier) {
+                    logLatency({
+                        type: "phase",
+                        filePath: ctx.filePath,
+                        phase: "runner_collect_later_tier_flip",
+                        durationMs: 0,
+                        metadata: {
+                            runnerId: runner.id,
+                            from: observedTier,
+                            to: tier,
+                            projectRoot,
+                        },
+                    });
+                }
+                if (tier === "collect-later") {
+                    incrementDegradationCount({
+                        kind: "runner-collect-later",
+                        subject: `${projectRoot}:${runner.id}`,
+                        reason: `observed ${durationMs}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`,
+                    });
+                }
+                logLatency({
+                    type: "runner",
+                    filePath: ctx.filePath,
+                    runnerId: runner.id,
+                    startedAt: new Date(markedAtMs).toISOString(),
+                    durationMs,
+                    status: result.status,
+                    diagnosticCount: result.diagnostics.length,
+                    semantic: result.semantic ?? semantic,
+                    metadata: { tier: "collect-later", delivered: "turn_end" },
+                });
+                return result;
+            });
+            deferRunnerFindings({
+                filePath: ctx.filePath,
+                cwd: ctx.cwd,
+                projectRoot,
+                runnerId: runner.id,
+                markedAtMs,
+                writeIndex: ctx.writeIndex,
+                promise: deferred,
+            });
+            // A deferred runner is still an observed runner. Keep it visible in
+            // both the edit latency report and the widget until its turn-end result
+            // replaces this pending state (#2122 F1).
+            latencies.push({
+                runnerId: runner.id,
+                startTime: runnerStart,
+                endTime: runnerStart,
+                durationMs: 0,
+                status: "pending",
+                diagnosticCount: 0,
+                semantic: semantic,
+            });
+            recordRunner(ctx.filePath, runner.id, "pending", 0, 0, ctx.writeIndex);
+            logLatency({
+                type: "runner",
+                filePath: ctx.filePath,
+                runnerId: runner.id,
+                durationMs: 0,
+                status: "pending",
+                diagnosticCount: 0,
+                semantic,
+                metadata: { tier: "collect-later", delivered: "turn_end" },
+            });
+            continue;
+        }
         const result = await runRunner(ctx, runner, semantic);
         onRunnerResult?.(runnerId, result);
         const runnerEnd = Date.now();
         const duration = runnerEnd - runnerStart;
+        const tier = ctx.writeIndex === undefined
+            ? "inline"
+            : observeRunnerLatency({
+                projectRoot,
+                runnerId: runner.id,
+                durationMs: duration,
+                timedOut: result.failureKind === "timeout",
+            });
+        if (tier !== observedTier) {
+            logLatency({
+                type: "phase",
+                filePath: ctx.filePath,
+                phase: "runner_collect_later_tier_flip",
+                durationMs: 0,
+                metadata: {
+                    runnerId: runner.id,
+                    from: observedTier,
+                    to: tier,
+                    projectRoot,
+                },
+            });
+        }
+        if (tier === "collect-later") {
+            incrementDegradationCount({
+                kind: "runner-collect-later",
+                subject: `${projectRoot}:${runner.id}`,
+                reason: `observed ${duration}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`,
+            });
+        }
         // Runner definitions are a typed API, but embedders/plugins can still
         // return untyped objects at runtime. Admit only the closed taxonomy and
         // only on actual skips so free text cannot enter durable latency metadata.
@@ -707,8 +837,13 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
     const groupResults = await Promise.all(groups.map((group) => runGroup(ctx, group, registry, onRunnerResult)));
     // Count baseline warnings before filtering (for delta count display)
     const relativeKey = path.relative(ctx.cwd, ctx.filePath).replace(/\\/g, "/");
-    const baselineAbsKey = `session.baseline.${normalizeMapKey(ctx.filePath)}`;
-    const baselineRelKey = `session.baseline.${normalizeMapKey(relativeKey)}`;
+    const baselineAbsKey = `session.baseline.${ctx.filePath}`;
+    // #2016: `relativeKey` is relative to `ctx.cwd`. `normalizeMapKey` resolved
+    // it against the process cwd instead, so on Windows this "relative" key
+    // became an absolute path anchored on the wrong root while POSIX left it
+    // relative. Both the read here and the write below use this const, so the
+    // key stays self-consistent within a session.
+    const baselineRelKey = `session.baseline.${normalizeEphemeralMapKey(relativeKey)}`;
     const previousBaseline = ctx.deltaMode
         ? (ctx.facts.getSessionFact(baselineAbsKey) ??
             ctx.facts.getSessionFact(baselineRelKey))
@@ -819,6 +954,12 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
         output += formatDiagnostics([coverageNotice], "warning", 1);
         warnings.push(coverageNotice);
     }
+    const pendingRunners = runnerLatencies
+        .filter((runner) => runner.status === "pending")
+        .map((runner) => runner.runnerId);
+    if (pendingRunners.length > 0) {
+        output += `\n⏳ Pending runners (reported at turn end): ${pendingRunners.join(", ")}\n`;
+    }
     // Generate and store latency report
     const overallEnd = Date.now();
     const latencyReport = {