@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

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/smells-rollup.js

@@ -24,14 +24,19 @@
  * alongside.
  *
  * The tail scan is bounded, but the tail can contain prior-session rows. The
- * session-start caller supplies the session boundary, and rows are admitted
- * only when their own UTC timestamp is at or after that boundary. This keeps
- * the same bounded read without reporting historical failures as current, so
- * this module does not additionally instrument the write call sites
- * (`bus-publish.ts`, `clients/lsp/index.ts`'s respawn path) with parallel
- * live counters. That keeps the change contained to one new module + three
- * small call sites (session_start, `/lens-health`, `turn_end`) instead of
- * touching every producer of the two source logs.
+ * `session_start` and `turn_end` callers supply the in-process session
+ * boundary (`runtime.sessionStartedAt`), and rows are admitted only when
+ * their own UTC timestamp is at or after that boundary. `/lens-health` has
+ * no per-session caller to anchor to (it can run at any point, including
+ * outside a turn) so it omits `sessionStartMs` and falls back to
+ * `SMELLS_ROLLING_WINDOW_MS` (24h) — its rendered line is labeled "last 24h
+ * tail-scan" to say so explicitly rather than implying a session-scoped
+ * count it isn't. This keeps the same bounded read without reporting
+ * historical failures as current, so this module does not additionally
+ * instrument the write call sites (`bus-publish.ts`, `clients/lsp/index.ts`'s
+ * respawn path) with parallel live counters. That keeps the change contained
+ * to one new module + three small call sites (session_start, `/lens-health`,
+ * `turn_end`) instead of touching every producer of the two source logs.
  *
  * Smells covered (deliberately a SUBSET — the two the issue named as having
  * gone unnoticed; the full catalogue stays in the manual analyzer):
@@ -53,6 +58,7 @@ import * as path from "node:path";
 import { getGlobalPiLensDir } from "./file-utils.js";
 /** Bounded tail-read budget PER source log file — never a full-file scan. */
 export const SMELLS_TAIL_BYTES_PER_FILE = 64 * 1024;
+export const SMELLS_ROLLING_WINDOW_MS = 24 * 60 * 60_000;
 /** Re-check cadence at `turn_end`, mirroring `memory-sampler.ts`'s pattern —
  *  cheap enough (bounded ~128KB I/O) not to need finer throttling, but a
  *  fixed interval keeps it from running on every single turn. */
@@ -154,11 +160,12 @@ function isOpengrepRespawn(entry) {
  * up to ~10MB) source files are. `root` is injectable for tests.
  */
 export function countRecentSmells(root = getGlobalPiLensDir(), sessionStartMs) {
+    const sinceMs = sessionStartMs ?? Date.now() - SMELLS_ROLLING_WINDOW_MS;
     const busTail = tailReadText(path.join(root, "bus-events.log"), SMELLS_TAIL_BYTES_PER_FILE);
     const latencyTail = tailReadText(path.join(root, "latency.log"), SMELLS_TAIL_BYTES_PER_FILE);
     return {
-        staleCtxEmitFailed: countMatchingLines(busTail, isStaleCtxEmitFailed, sessionStartMs),
-        opengrepRespawn: countMatchingLines(latencyTail, isOpengrepRespawn, sessionStartMs),
+        staleCtxEmitFailed: countMatchingLines(busTail, isStaleCtxEmitFailed, sinceMs),
+        opengrepRespawn: countMatchingLines(latencyTail, isOpengrepRespawn, sinceMs),
     };
 }
 /**
@@ -186,7 +193,7 @@ export function formatSmellsSessionStartLine(counts) {
  * everything is below threshold).
  */
 export function formatSmellsHealthLine(counts) {
-    return (`Smells (recent tail-scan): stale-ctx emit_failed=${counts.staleCtxEmitFailed}` +
+    return (`Smells (last 24h tail-scan): stale-ctx emit_failed=${counts.staleCtxEmitFailed}` +
         ` · opengrep respawn=${counts.opengrepRespawn}`);
 }
 /** `true` on turn 20, 40, 60, ... — never turn 0. Pure so the cadence is

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-timing.js

@@ -1,5 +1,11 @@
 import { performance } from "node:perf_hooks";
-import { PI_LENS_EVAL_STARTED_MS } from "./console-guard-install.js";
+// #1434 S3d: import the constant from the side-effect-free module, not from
+// `console-guard-install.ts` — that module installs the console guard as an
+// import side effect, so importing it here (for a single constant, from a
+// module measuring load time) would have silently installed the guard
+// wherever this file is imported, including test-only measurement code that
+// has no business flipping a global switch.
+import { PI_LENS_EVAL_STARTED_MS } from "./eval-timestamp.js";
 /**
  * Startup timing for pi-lens.
  *
@@ -15,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
@@ -23,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;