@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/security-scan-client.js

@@ -12,34 +12,73 @@
  *
  * Refs: #130, #131, #132
  */
+import * as path from "node:path";
 import { createSubsystemLogger } from "./extension-log.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
-import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { classifyProbeFailure, createAvailabilityLatch, describeInstallAttempt, describeProbeEvidence, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 export class SecurityScanClient {
     toolName;
     /**
      * Availability memo, backed by the shared transient-aware latch (#1467).
      *
      * Assigning `false` still means "durable: this machine does not have the
-     * tool" — every existing subclass write keeps its meaning. A probe that
-     * merely timed out must go through `markTransientlyUnavailable` instead, so
-     * it expires and the tool can come back without a host restart.
+     * tool" — every existing subclass write keeps its meaning. A transient
+     * failure must expire instead: `probeVersion` latches its own transient
+     * verdicts (#1501), and any other transient failure (a scan or install
+     * timeout) goes through `markTransientlyUnavailable`, so the tool can come
+     * back without a host restart.
      */
     availabilityLatch = createAvailabilityLatch();
     get available() {
         return this.availabilityLatch.read();
     }
     set available(value) {
-        if (value === true)
+        if (value === true) {
             this.availabilityLatch.noteAvailable();
-        else if (value === false)
-            this.availabilityLatch.noteUnavailable("missing", "not-found");
-        else
+            return;
+        }
+        if (value !== false) {
             this.availabilityLatch.reset();
+            return;
+        }
+        this.availabilityLatch.noteUnavailable("missing", "not-found");
+        this.logDurableAbsence();
+    }
+    /**
+     * Latch a durable absence WITH the facts behind it. Prefer this over
+     * `available = false` wherever the call site knows what actually failed — a
+     * `missing` row carrying `install: "failed"` is a retry candidate, one
+     * carrying `install: "not-attempted"` is a policy decision, and a bare one is
+     * a plain absence. Only the record can tell them apart.
+     */
+    noteDurableAbsence(evidence, options = {}) {
+        this.availabilityLatch.noteUnavailable("missing", "not-found");
+        this.logDurableAbsence(evidence, options.elapsedMs);
     }
-    /** Outcome/cause of the most recent `probeVersion` call. */
+    /**
+     * One record per durable-absence ASSERTION, whether or not the call site had
+     * evidence. Before this, `available = false` after a failed install was a
+     * silent latch: the tool went quiet for the session with nothing in
+     * latency.log to audit (#1500). Bounded — the verdict latches, so at most one
+     * row per client per session.
+     *
+     * `elapsedMs` is whatever the caller measured (an install attempt's duration);
+     * there is no probe here, so it is 0 unless the caller has something real.
+     */
+    logDurableAbsence(evidence, elapsedMs = 0) {
+        logAvailabilityDecision({
+            tool: this.toolName,
+            verdict: "unavailable",
+            outcome: "missing",
+            cause: "not-found",
+            elapsedMs,
+            latched: true,
+            classifiedBy: "caller",
+            ...(evidence !== undefined && { evidence }),
+        });
+    }
+    /** Outcome of the most recent `probeVersion` call. */
     lastProbeOutcome = null;
-    lastProbeCause = null;
     ensureInFlight = null;
     inFlight = new Map();
     binaryPath = null;
@@ -74,10 +113,17 @@ export class SecurityScanClient {
     }
     /**
      * Spawn `toolName <versionArgs>` and report whether it answered cleanly.
-     * Does NOT mutate `this.available` — callers decide what a hit/miss means —
-     * but it does classify the failure (`lastProbeOutcome`/`lastProbeCause`) and
-     * emit one availability-decision record, so a probe that keeps timing out is
-     * visible in latency.log rather than inferred from silence (#1467).
+     * Classifies the failure (`lastProbeOutcome`) and emits one
+     * availability-decision record, so a probe that keeps timing out is visible
+     * in latency.log rather than inferred from silence (#1467).
+     *
+     * Latch ownership is split by outcome: success and durable failures leave
+     * `this.available` to the caller (a missing binary may still be
+     * auto-installed), while a TRANSIENT failure is latched by the seam itself
+     * with its cooldown — the retry schedule only exists once the latch owns
+     * the verdict, and the record is incomplete without it (#1501). Callers
+     * must not re-mark a probe transient (a second noteUnavailable would
+     * double-escalate the cooldown).
      */
     async probeVersion(versionArgs) {
         const sampler = startHostStallSampler();
@@ -95,7 +141,6 @@ export class SecurityScanClient {
         const elapsedMs = Date.now() - startedAt;
         if (!probe.error && probe.status === 0) {
             this.lastProbeOutcome = "success";
-            this.lastProbeCause = "ok";
             this.log(`${this.toolName} found: ${probe.stdout.trim().split("\n")[0]}`);
             logAvailabilityDecision({
                 tool: this.toolName,
@@ -106,12 +151,22 @@ export class SecurityScanClient {
                 latched: true,
                 hostStallMs,
                 budgetMs: 5000,
+                classifiedBy: "probe",
+                evidence: describeProbeEvidence(probe),
             });
             return true;
         }
-        const { outcome, cause } = classifyProbeFailure(probe, { hostStallMs });
+        const { outcome, cause, evidence } = classifyProbeFailure(probe, {
+            hostStallMs,
+        });
         this.lastProbeOutcome = outcome;
-        this.lastProbeCause = cause;
+        // A transient verdict's record is incomplete without the retry schedule,
+        // and the schedule only exists once the latch owns the verdict — so the
+        // seam writes the expiring verdict itself, at log time (#1501). Durable
+        // outcomes stay caller-owned (a missing binary may still be installed).
+        const retryAfterMs = outcome === "transient"
+            ? this.availabilityLatch.noteUnavailable("transient", cause)
+            : 0;
         logAvailabilityDecision({
             tool: this.toolName,
             verdict: "unavailable",
@@ -120,7 +175,10 @@ export class SecurityScanClient {
             elapsedMs,
             latched: outcome !== "transient",
             hostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
             budgetMs: 5000,
+            classifiedBy: "probe",
+            evidence,
         });
         return false;
     }
@@ -135,9 +193,47 @@ export class SecurityScanClient {
      * Returns that cooldown in ms so the caller can put it in its decision
      * record. A latch you can read in `latency.log` without the retry schedule
      * beside it only tells you the tool is off, not when it comes back.
+     *
+     * For NON-probe transient failures only (scan/install timeouts):
+     * `probeVersion` latches and logs its own transient verdicts (#1501), so
+     * re-marking one here would double-escalate the cooldown.
+     *
+     * Pass `opts.operationClass: "install"` when the failed operation was a
+     * network install/compile rather than a cheap probe (#1497): the retry
+     * escalates on the install-class schedule, on its OWN cooldown slot (a
+     * cheap probe failure can never shorten it), and latches for the session at
+     * the attempt ceiling, in which case the return is 0 (latched).
+     */
+    markTransientlyUnavailable(cause = "probe-timeout", opts) {
+        return this.availabilityLatch.noteUnavailable("transient", cause, opts);
+    }
+    /**
+     * The cause the LATCH settled on, which is not always the cause the caller
+     * passed in: at the install-class ceiling the latch rewrites it to
+     * `install-retry-exhausted` (#1497). A decision record built from the
+     * caller's own cause would say `probe-timeout` for a verdict that is no
+     * longer being retried, so the record reads it back from here.
      */
-    markTransientlyUnavailable(cause = "probe-timeout") {
-        return this.availabilityLatch.noteUnavailable("transient", cause);
+    latchedCause() {
+        return this.availabilityLatch.getCause();
+    }
+    /**
+     * #1623: public window onto the availability verdict for callers OUTSIDE
+     * the dispatch graph (mode=full's fresh-fetch) that need to say WHY
+     * `ensureAvailable()` most recently returned false — using the SAME
+     * `AvailabilityOutcome`/`AvailabilityCause` taxonomy every dispatch-side
+     * message is built from, rather than a re-guessed "binary unavailable"
+     * that can't tell a transient retry-cooldown probe from a durable absence.
+     * `latchedCause()`/`lastProbeOutcome` above stay `protected` for
+     * dispatch-internal callers; this is the one public seam for everyone
+     * else.
+     */
+    getAvailabilityVerdict() {
+        return {
+            outcome: this.availabilityLatch.getOutcome(),
+            cause: this.availabilityLatch.getCause(),
+            retryAtMs: this.availabilityLatch.getRetryAtMs(),
+        };
     }
     /**
      * Standard availability path for the GitHub-release tools (gitleaks, trivy):
@@ -151,22 +247,59 @@ export class SecurityScanClient {
         }
         if (this.probeWasTransient()) {
             // A timed-out probe is not evidence the tool is absent, so it must not
-            // trigger an install NOR latch a permanent `false`.
+            // trigger an install NOR latch a permanent `false`. probeVersion has
+            // already recorded the expiring verdict and its retry schedule
+            // (#1501) — re-marking it here would double-escalate the cooldown.
             this.log(`${this.toolName} availability probe timed out; not installing, will retry`);
-            this.markTransientlyUnavailable(this.lastProbeCause ?? "probe-timeout");
             return false;
         }
         this.log(`${this.toolName} not found, attempting auto-install`);
-        const { ensureTool } = await import("./installer/index.js");
+        const { ensureTool, getInstallAttempt } = await import("./installer/index.js");
+        const installStartedAt = Date.now();
         const installed = await ensureTool(this.toolName);
         if (!installed) {
-            this.log(`${this.toolName} auto-install failed`);
-            this.available = false;
+            // #1500: this classification is ASSERTED, not derived. It is justified —
+            // the probe already classified a genuine absence, and a failed repair
+            // leaves the tool absent — but the install failure has no taxonomy of
+            // its own, so a network blip and a permanently unavailable release look
+            // identical from here. Record what happened rather than only the verdict.
+            //
+            // `ensureTool` answers the same empty result whether it TRIED and failed
+            // or declined to try (auto-install off, project trust denied), so the
+            // attempt is read from the reason it records rather than assumed — the
+            // review found `install: "failed"` being written for attempts that never
+            // happened.
+            const attempt = getInstallAttempt(this.toolName);
+            this.log(attempt?.outcome === "failed"
+                ? `${this.toolName} auto-install failed: ${attempt.reason ?? "unknown reason"}`
+                : `${this.toolName} auto-install did not run: ${attempt?.reason ?? "no attempt recorded"}`);
+            this.noteDurableAbsence(describeInstallAttempt(attempt), {
+                elapsedMs: Date.now() - installStartedAt,
+            });
             return false;
         }
         this.binaryPath = installed;
         this.available = true;
         this.log(`${this.toolName} auto-installed at ${installed}`);
+        // The probe already wrote a latched `unavailable` row (#1500's durable
+        // assertion doesn't fire here — install SUCCEEDED — but probeVersion's
+        // verdict still did, before this call ever ran). Without a compensating
+        // row, the durable record says the lane is off when it just came back
+        // on: the exact defect #1606 was filed over.
+        logAvailabilityDecision({
+            tool: this.toolName,
+            verdict: "available",
+            outcome: "success",
+            cause: "ok",
+            elapsedMs: Date.now() - installStartedAt,
+            latched: true,
+            classifiedBy: "caller",
+            evidence: {
+                install: "succeeded",
+                binary: path.basename(installed),
+                source: "managed-dir",
+            },
+        });
         return true;
     }
     /**

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(),
+    };
+}