@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/sg-runner.js

@@ -12,7 +12,8 @@ import { getSgCommand, resolveManagedToolClient, } from "./dispatch/runners/util
 import { getProjectIgnoreGlobs } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
-import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { createSingleFlight } from "./single-flight.js";
+import { classifyProbeFailure, describeInstallAttempt, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 /**
  * Build the `bash -c` argv that runs `cmd` with `allArgs` as POSITIONAL
  * parameters. The script is the constant `"$0" "$@"`, so bash re-emits the
@@ -106,7 +107,11 @@ export class SgRunner {
      * restart and paid for an install nobody needed.
      */
     availabilityLatch = createAvailabilityLatch();
-    ensureInFlight = null;
+    /**
+     * At-most-one sweep in flight, via the shared primitive (#1753). One
+     * instance owns one question, so the key is a constant.
+     */
+    ensureFlight = createSingleFlight();
     /**
      * Whether a DIRECT candidate — one that would have been ast-grep itself —
      * failed for a transient reason in the current sweep. Only these block the
@@ -117,11 +122,34 @@ export class SgRunner {
      */
     sweepSawTransient = false;
     sweepTransientCause = "probe-timeout";
+    /**
+     * The DIRECT candidates that were unreachable, in ask order (#1568).
+     *
+     * The sweep returns at the first candidate that answers, so at the moment of
+     * a win this is exactly the set of preferred tiers the winner did not beat on
+     * the merits. Fallbacks are excluded on purpose: `npx` is asked before the
+     * global-bin and platform-package tiers, and a slow `npx` says nothing about
+     * a winner that is a real binary.
+     *
+     * Basenames, because a candidate can be an absolute global-bin or
+     * platform-package path and this list is written to latency.log (#1568
+     * review F3).
+     */
+    sweepUnreachable = [];
     /** A transient on the npx fallback: not evidence, but not nothing either. */
     sweepFallbackTransient = false;
     sweepFallbackCause = "probe-timeout";
     /** Host stall summed over every probe of the current sweep, ms. */
     sweepHostStallMs = 0;
+    /**
+     * Candidates — direct or fallback — that this sweep probed and found
+     * DURABLY missing (real ENOENT/non-installable, not a stall) (#1593). The
+     * retained-arm fallback below only sees whether SOME candidate stalled; this
+     * list lets it also check whether the memoized winner itself is one of the
+     * candidates this very sweep just disproved, rather than re-serving a
+     * command that ENOENTed a moment ago because an unrelated sibling stalled.
+     */
+    sweepDurablyMissing = [];
     constructor(verbose = false) {
         this.log = verbose
             ? createSubsystemLogger("sg-runner")
@@ -130,10 +158,12 @@ export class SgRunner {
     /**
      * Check if ast-grep CLI is available, auto-install if not.
      *
-     * Re-entrancy safe: concurrent first-time callers share a single
-     * `ensureInFlight` promise so probing/auto-install isn't duplicated
-     * across session-start tasks. Mirrors the dedupe pattern in
-     * `KnipClient.ensureAvailable` and `DependencyChecker.ensureAvailable`.
+     * Re-entrancy safe: concurrent first-time callers share one flight, so
+     * probing/auto-install isn't duplicated across session-start tasks. The
+     * share and the clear-in-finally belong to `singleFlight` (#1753); this
+     * method owns only the latch short-circuit above it. The sweep-local
+     * bookkeeping `doEnsureAvailable` resets on entry is untouched — it is
+     * per-sweep state, not concurrency state.
      */
     async ensureAvailable() {
         // Fast path: already decided. `read()` returns null when the last verdict
@@ -141,23 +171,17 @@ export class SgRunner {
         const memo = this.availabilityLatch.read();
         if (memo !== null)
             return memo;
-        if (this.ensureInFlight)
-            return this.ensureInFlight;
-        this.ensureInFlight = this.doEnsureAvailable();
-        try {
-            return await this.ensureInFlight;
-        }
-        finally {
-            this.ensureInFlight = null;
-        }
+        return this.ensureFlight.run("ast-grep", () => this.doEnsureAvailable());
     }
     async doEnsureAvailable() {
         const startedAt = Date.now();
         this.sweepSawTransient = false;
         this.sweepTransientCause = "probe-timeout";
+        this.sweepUnreachable = [];
         this.sweepFallbackTransient = false;
         this.sweepFallbackCause = "probe-timeout";
         this.sweepHostStallMs = 0;
+        this.sweepDurablyMissing = [];
         // Step 1: PATH — canonical binary names + npx fallback.
         // Prefer ast-grep over sg on Linux: /usr/bin/sg is util-linux, not ast-grep.
         const pathCommand = await this.probeCommandCandidates([
@@ -218,6 +242,19 @@ export class SgRunner {
         // install below was never reached and the slow npx was re-spawned on each
         // escalating retry instead — worse than the latch it replaced.
         if (this.sweepSawTransient) {
+            // Nothing answered, transiently, while we are still holding a command a
+            // previous provisional sweep proved working. Discarding it here would
+            // run #1476 backwards — a timeout erasing a positive result — and it
+            // would send the sweep on to Step 4 to install a tool that is already
+            // runnable. Keep the winner and re-arm the cooldown (#1568 review F1).
+            // #1593: a sibling tier stalling this sweep is not license to re-serve
+            // a winner that THIS SAME sweep just proved durably missing.
+            if (this.availabilityLatch.isProvisional() &&
+                this.sgPath &&
+                !this.sweepDurablyMissing.includes(this.sgPath)) {
+                this.noteAvailable(startedAt, `ast-grep re-probe stalled; keeping ${this.sgPath}`, { retained: true });
+                return true;
+            }
             this.log("ast-grep availability probe timed out; will retry (not installing)");
             return this.noteUnavailable(startedAt, "transient", this.sweepTransientCause);
         }
@@ -240,21 +277,61 @@ export class SgRunner {
         if (this.sweepFallbackTransient) {
             return this.noteUnavailable(startedAt, "transient", this.sweepFallbackCause);
         }
-        return this.noteUnavailable(startedAt, "missing", "not-found");
+        // #1500: ASSERTED, not derived — and justified, because every candidate
+        // probe answered "not found", so the absence is real. What the install did
+        // is recorded as evidence rather than folded into the verdict: it is the one
+        // fact separating "never installable here" from "the download failed", and
+        // from "no install was attempted at all" (auto-install off, trust denied,
+        // or an attempt already suppressed this session).
+        const { getInstallAttempt } = await import("./installer/index.js");
+        return this.noteUnavailable(startedAt, "missing", "not-found", describeInstallAttempt(getInstallAttempt("ast-grep"), {
+            installedButRejected: installed.outcome === "non-installable",
+        }), "caller");
     }
-    /** Record a successful sweep: available, latched, one decision record. */
-    noteAvailable(startedAt, message) {
-        this.availabilityLatch.noteAvailable();
+    /**
+     * Record a successful sweep, with one decision record.
+     *
+     * The win is latched for the session UNLESS a direct candidate ahead of it
+     * was unreachable (#1568). `sweepSawTransient` is set only by candidates the
+     * sweep already asked, and the sweep returns at the first one that answers,
+     * so at this point the flag means "a tier the winner is supposed to lose to
+     * never got a fair hearing". Latching that pinned the session to
+     * `npx --no -- ast-grep` — a Node start per invocation — over a healthy
+     * ast-grep on PATH, until the next restart. Provisional instead: served now,
+     * re-swept once the stalled tier's cooldown expires.
+     *
+     * The install arm cannot reach here provisionally: `doEnsureAvailable`
+     * returns before Step 4 whenever `sweepSawTransient` is set.
+     *
+     * `retained` marks the other provisional case (#1568 review F1): no candidate
+     * answered at all, and the winner being reported is the one the previous
+     * sweep found, kept rather than discarded on a timeout.
+     */
+    noteAvailable(startedAt, message, opts = {}) {
+        const provisional = this.sweepSawTransient;
+        let retryAfterMs = 0;
+        if (provisional) {
+            retryAfterMs = this.availabilityLatch.noteProvisionallyAvailable(this.sweepTransientCause);
+        }
+        else {
+            this.availabilityLatch.noteAvailable();
+        }
         this.log(message);
         logAvailabilityDecision({
             tool: "ast-grep",
             verdict: "available",
             outcome: "success",
-            cause: "ok",
+            cause: provisional ? this.sweepTransientCause : "ok",
             elapsedMs: Date.now() - startedAt,
-            latched: true,
+            latched: !provisional,
             hostStallMs: this.sweepHostStallMs,
             budgetMs: PROBE_TIMEOUT_MS,
+            ...(provisional && {
+                provisional: true,
+                unreachablePreferred: [...this.sweepUnreachable],
+                ...(opts.retained === true && { retained: true }),
+                ...(retryAfterMs > 0 && { retryAfterMs }),
+            }),
         });
     }
     /**
@@ -264,7 +341,15 @@ export class SgRunner {
      * about the sweep rather than any single candidate — reporting zero here
      * would erase the evidence that cracked #1467.
      */
-    noteUnavailable(startedAt, outcome, cause) {
+    noteUnavailable(startedAt, outcome, cause, evidence, 
+    /**
+     * How this arm reached its verdict. Per arm on purpose (#1500 review): the
+     * sweep's own transient/missing conclusions ARE derived from candidate
+     * probes, but the post-install assertion is not, and hardcoding `"probe"`
+     * here labelled an assertion as a derivation — the exact confusion the
+     * field was added to remove.
+     */
+    classifiedBy = "probe") {
         const retryAfterMs = this.availabilityLatch.noteUnavailable(outcome, cause);
         logAvailabilityDecision({
             tool: "ast-grep",
@@ -276,6 +361,8 @@ export class SgRunner {
             hostStallMs: this.sweepHostStallMs,
             ...(retryAfterMs > 0 && { retryAfterMs }),
             budgetMs: PROBE_TIMEOUT_MS,
+            classifiedBy,
+            ...(evidence !== undefined && { evidence }),
         });
         return false;
     }
@@ -392,8 +479,15 @@ export class SgRunner {
             else {
                 this.sweepSawTransient = true;
                 this.sweepTransientCause = cause;
+                const name = path.basename(cmd);
+                if (!this.sweepUnreachable.includes(name)) {
+                    this.sweepUnreachable.push(name);
+                }
             }
         }
+        else if (!this.sweepDurablyMissing.includes(cmd)) {
+            this.sweepDurablyMissing.push(cmd);
+        }
         return false;
     }
     async probeCommandCandidates(candidates) {

package/node_modules/pi-lens/dist/clients/single-flight.js

@@ -0,0 +1,158 @@
+/**
+ * `singleFlight` — at most one execution per key, clear owned by the primitive.
+ *
+ * Ten sites hand-roll the same five lines: look up a key in a promise map,
+ * return the existing promise if there is one, otherwise start the work and
+ * delete the key in a `finally`. The class has a measured bug yield, and every
+ * bug is in the part the call site wrote rather than the part it meant:
+ *
+ * - #1690: the `finally`-clear was never exercised, so its regression test
+ *   passed with the clear deleted. A memo short-circuit above the in-flight
+ *   check meant the second call never reached it.
+ * - #1674: the `finally` deleted the key unconditionally, so a probe settling
+ *   after a session reset evicted the REPLACEMENT probe a new session had
+ *   already started for the same key.
+ * - #1687: the trailing-rerun bit shipped unpinned — the test asserted "at most
+ *   two passes" one-sidedly, which a coalescer that dropped the rerun entirely
+ *   also satisfies.
+ * - #1722: an inner latch was vacuous and its own mutation matrix deleted it.
+ *
+ * This module owns those four guards once. The API is the INTERSECTION of the
+ * ten sites, not a superset: share, clear-in-finally, optional trailing-rerun
+ * coalescing, optional generation check. Anything a single site needs stays at
+ * that site.
+ *
+ * LIFECYCLE: the primitive owns no module state. `createSingleFlight` returns
+ * a closure, so each registry's lifetime is its OWNER's — an instance field
+ * lives as long as the instance, a module-level const as long as the process.
+ * That keeps the session-state question where it belongs, at the owner, and
+ * `clear()` is the seam an owner's reset calls. The two converted sites hold
+ * instance fields, exactly as their `ensureInFlight` fields did, so neither
+ * one's session-state answer changes.
+ *
+ * Teardown of a flight that never settles is the owner's question, and neither
+ * converted site answers it today: a wedged probe holds its key until the
+ * process ends, exactly as its `ensureInFlight` field did on master. This
+ * primitive does not make that worse and does not fix it; an owner that needs a
+ * deadline wraps `fn` in one before handing it over.
+ *
+ * The generation hook is deliberately thin — a `() => number` the primitive
+ * reads at start and again at completion. The standalone generation-guard
+ * primitive is #1754's; when it lands, this stays a callback and composes with
+ * it rather than absorbing it.
+ */
+/**
+ * Create a keyed single-flight registry.
+ *
+ * Sites with only one thing to dedupe pass a constant key; the map costs one
+ * entry and buys the same four guards a single slot would have to re-derive.
+ */
+export function createSingleFlight(options = {}) {
+    const { generation: readGeneration, coalesceTrailing = false } = options;
+    const flights = new Map();
+    const currentGeneration = () => readGeneration?.() ?? 0;
+    /**
+     * Release `key`, but ONLY if this exact flight still owns it.
+     *
+     * This is the #1674 eviction direction: a flight that settles late must not
+     * delete the entry a SUCCESSOR already installed under the same key. The
+     * successor may exist because a reset cleared the map and a new caller
+     * arrived, or because the generation moved and `run` superseded the stale
+     * flight. Identity answers both, so identity is the only check here.
+     *
+     * `runner-helpers.ts:1058` writes this as a generation check AND an identity
+     * check. The mutation matrix says the generation half of that pair kills no
+     * test: whenever it would fire, identity has already returned. The pair is
+     * harmless there and not worth churning; it is not worth copying either.
+     */
+    const release = (key, flight) => {
+        if (flights.get(key) !== flight)
+            return;
+        flights.delete(key);
+    };
+    const run = (key, fn) => {
+        const existing = flights.get(key);
+        // Sharing requires BOTH a running flight and a matching generation. A
+        // flight from an earlier generation answers a question a session reset
+        // already invalidated, so this caller falls through and starts a fresh
+        // one; the `flights.set` below replaces the stale entry outright, and the
+        // stale flight's own `release` then finds a foreign entry and leaves it
+        // alone. There is deliberately no explicit delete for the superseded
+        // entry: nothing reads the map between here and that `set`, so a delete
+        // would be a dead statement dressed as a guard.
+        if (existing && existing.generation === currentGeneration()) {
+            // A mid-flight request in the SAME generation. With coalescing it earns
+            // exactly one trailing pass no matter how many such requests arrive;
+            // without it, it shares the running pass. Either way it never starts a
+            // second flight.
+            if (coalesceTrailing)
+                existing.rerunRequested = true;
+            return existing.promise;
+        }
+        // The shared handle is built BEFORE `fn` runs and BEFORE the map entry is
+        // published, so the entry a reentrant caller finds always carries a real
+        // pending promise. The hand-rolled sites all publish the entry after
+        // starting the work, which leaves a synchronous window where a reentrant
+        // call starts a second flight for the same key.
+        let settle;
+        let fail;
+        const promise = new Promise((resolve, reject) => {
+            settle = resolve;
+            fail = reject;
+        });
+        const flight = {
+            promise,
+            generation: currentGeneration(),
+            rerunRequested: false,
+        };
+        const chain = async () => {
+            let result = await fn();
+            // KNOWN INTERACTION, `coalesceTrailing` + `generation`: a flight that
+            // gets superseded mid-pass with its rerun bit already set still runs
+            // that one trailing pass, because the bit lives on the flight and no
+            // caller can reach in to clear it. So a reset can cost ONE extra pass
+            // of pre-reset work, whose result nothing reads — the superseded
+            // promise has no callers left that a live caller depends on.
+            //
+            // Left as-is rather than fixed blind: no site uses both options today,
+            // so any fix would be untested guesswork about which behavior a real
+            // caller wants. A reset arguably SHOULD abandon the pending rerun; it
+            // arguably should also let a pass that is already half-done finish.
+            // The third site to turn this combination on decides, and adds the
+            // test that pins whichever answer it picks.
+            //
+            // Only reruns requested WHILE a pass was running count. Clearing the bit
+            // before each pass — never after — is what pins the coalescing to "at
+            // most one trailing rerun": a request that arrives during pass 2 sets
+            // the bit again and gets pass 3, which is still one trailing pass per
+            // burst-that-overlaps-a-pass, not one per request.
+            while (flight.rerunRequested) {
+                flight.rerunRequested = false;
+                result = await fn();
+            }
+            return result;
+        };
+        flights.set(key, flight);
+        // Release runs on BOTH settlements — a rejected `fn` must not wedge the
+        // key, which is #1690's leak. Release and settle happen in the same
+        // synchronous step, so their order relative to each other is not
+        // observable; what matters is that both run before any awaiting caller's
+        // continuation. A rejection also abandons a pending rerun: re-running
+        // work that just threw is a retry policy, and a retry policy belongs to
+        // the caller that knows what the work was.
+        chain().then((value) => {
+            release(key, flight);
+            settle(value);
+        }, (error) => {
+            release(key, flight);
+            fail(error);
+        });
+        return flight.promise;
+    };
+    return {
+        run,
+        has: (key) => flights.has(key),
+        size: () => flights.size,
+        clear: () => flights.clear(),
+    };
+}

package/node_modules/pi-lens/dist/clients/source-filter.js

@@ -391,11 +391,15 @@ function classifyEntry(entry, fullPath, cfg, probeCache, skipCounters) {
         return { recurseInto: fullPath };
     }
     if (entry.isFile()) {
-        if (ignoreMatcher.isIgnored(fullPath, false))
-            return {};
+        // #1974: extension gate before isIgnored — isIgnored recompiles minimatch
+        // patterns per ancestor dir per call, so a large ignored-but-not-dir-
+        // prunable pile (e.g. wal/*.log) should never pay that cost for files
+        // the extension gate would have dropped anyway.
         const ext = path.extname(entry.name).toLowerCase();
         if (!extensions.has(ext))
             return {};
+        if (ignoreMatcher.isIgnored(fullPath, false))
+            return {};
         // Skip if this is a build artifact or generated/codegen output.
         // #1107: counted separately (both are observability-only — neither
         // changes what gets skipped) so an invisible coverage hole (a real

package/node_modules/pi-lens/dist/clients/stale-marker.js

@@ -0,0 +1,17 @@
+/**
+ * #1622 / #1419 precedent: what a demoted finding shows where its cached line
+ * number used to be. The finding survives, the untrustworthy coordinate does
+ * not. Shared base marker so every freshness gate (dependency-drift blockers,
+ * cached-scanner staleness, #1641's past-EOF gate) renders the same "this
+ * coordinate is no longer trustworthy" vocabulary — a caller with a more
+ * specific reason appends its own suffix rather than inventing a parallel
+ * marker string.
+ *
+ * #1631 review V2: lives in its own leaf module rather than `runtime-turn.ts`
+ * (the turn orchestrator) so a low-level store like `widget-state.ts` can use
+ * the marker without importing a high-level orchestration module — `madge
+ * --circular` went from 0 to 45 cycles when `widget-state.ts` imported this
+ * constant from `runtime-turn.ts`, and this repo ships that circular-import
+ * check as a product feature.
+ */
+export const STALE_LINE_MARKER = "[stale — re-run to confirm]";

package/node_modules/pi-lens/dist/clients/startup-scan.js

@@ -178,9 +178,12 @@ function makeSourceCountVisitor(state, ignoreMatcher, limit, maxEntries) {
             }
             return recurse ? "recurse" : "skip";
         }
+        // #1974: extension-pattern gate before isIgnored — isIgnored recompiles
+        // minimatch patterns per ancestor dir per call, so it should only run for
+        // entries the cheap regex already flags as source.
         if (entry.isFile() &&
-            !ignoreMatcher.isIgnored(fullPath, false) &&
-            SOURCE_FILE_PATTERN.test(entry.name)) {
+            SOURCE_FILE_PATTERN.test(entry.name) &&
+            !ignoreMatcher.isIgnored(fullPath, false)) {
             state.count += 1;
             if (state.count > limit)
                 return "stop";

package/node_modules/pi-lens/dist/clients/startup-timing.js

@@ -21,6 +21,8 @@ export const PI_LENS_LOADED_FROM = import.meta.url.endsWith(".js")
     ? "dist"
     : "source";
 let loadMs;
+let loadedAtMs;
+let hostReadyDelayAnchorConsumed = false;
 /**
  * Record the load-complete time. Call once, as the first statement in the
  * extension entry's module body — by then every import has been evaluated, so
@@ -29,10 +31,26 @@ let loadMs;
  */
 export function markPiLensLoaded() {
     if (loadMs === undefined) {
-        loadMs = Math.round(performance.now());
+        loadedAtMs = performance.now();
+        loadMs = Math.round(loadedAtMs);
     }
     return loadMs;
 }
+/** Monotonic instant when pi-lens finished loading, for cross-hook spans. */
+export function getPiLensLoadedAtMs() {
+    return loadedAtMs;
+}
+/** Consume the process-lifetime first-session host-ready anchor exactly once. */
+export function consumeHostReadyDelayAnchor() {
+    if (hostReadyDelayAnchorConsumed)
+        return false;
+    hostReadyDelayAnchorConsumed = true;
+    return true;
+}
+/** Test seam for the process-lifetime session-state registry probe boundary. */
+export function resetHostReadyDelayAnchorForTests() {
+    hostReadyDelayAnchorConsumed = false;
+}
 /** ms from pi process start to pi-lens load-complete, or undefined if unmarked. */
 export function getPiLensLoadMs() {
     return loadMs;