@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/spawn-outcome.js

@@ -0,0 +1,22 @@
+/**
+ * True when a tool both failed and produced nothing to parse — it never got as
+ * far as linting the file. Callers map this to `skipped`, never `succeeded`.
+ *
+ * Guarding on `result.error` alone covers only half of it: safe-spawn sets
+ * `error` for spawn/timeout/signal failures and resolves a NORMAL exit with no
+ * `error` at any status (see `SpawnResult.failure` — "nonzero exit statuses are
+ * not spawn failures"). An unknown subcommand, a rejected flag, or a config
+ * that fails to load exits non-zero with the message on stderr and an empty
+ * stdout, so an `error`-only guard falls through, parses "" into zero
+ * diagnostics, and reports a clean file that nothing ever checked.
+ *
+ * Tools that exit non-zero *because* they found something are unaffected: their
+ * findings are on stdout, so the output half of the test is false.
+ *
+ * `output` defaults to stdout. Runners that parse stderr too pass the exact
+ * string they are about to hand the parser, so "nothing to parse" means both
+ * streams rather than just one.
+ */
+export function spawnFailedWithNoOutput(result, output = result.stdout) {
+    return (Boolean(result.error) || result.status !== 0) && !output?.trim();
+}

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/toolchain-availability.js

@@ -0,0 +1,97 @@
+/**
+ * Shared toolchain-availability lifecycle (#1476 Sonar follow-up).
+ *
+ * `candidate-probe.ts` factored out the PATH sweep the Go and Rust clients ran,
+ * but the LIFECYCLE around it stayed written twice: the transient-aware latch,
+ * the in-flight dedupe that keeps concurrent first-time callers to one sweep,
+ * the path memo, and the two `availability_decision` records. Two copies of one
+ * rule is how #1467's fix missed seven sites, so the rule lives here once and
+ * each client contributes only its configuration.
+ *
+ * Callers keep their own public method names — `isGoAvailableAsync`,
+ * `findCargoPathAsync` — because other modules call them; only the body moves.
+ */
+import { createAvailabilityLatch, logAvailabilityDecision, } from "./availability-policy.js";
+import { probeAvailabilityCandidates } from "./candidate-probe.js";
+/**
+ * Own one toolchain's availability: sweep the platform candidate list, memoize
+ * the path that answered, and park the verdict behind the shared latch so a
+ * timed-out probe expires instead of latching "the toolchain is not installed"
+ * for the life of the process.
+ */
+export function createToolchainAvailability(config) {
+    const availabilityLatch = createAvailabilityLatch();
+    let toolPath = null;
+    /** Classification of the candidate sweep, for the retry decision. */
+    let sweepSawTransient = false;
+    let sweepTransientCause = "probe-timeout";
+    let sweepHostStallMs = 0;
+    let ensureInFlight = null;
+    async function findPath() {
+        if (toolPath)
+            return toolPath;
+        const paths = process.platform === "win32" ? config.windowsPaths : config.unixPaths;
+        const sweep = await probeAvailabilityCandidates(paths, config.probeArgs, config.budgetMs);
+        sweepSawTransient = sweep.sawTransient;
+        sweepTransientCause = sweep.transientCause;
+        sweepHostStallMs = sweep.hostStallMs;
+        if (sweep.foundPath)
+            toolPath = sweep.foundPath;
+        return sweep.foundPath;
+    }
+    async function resolveAvailability() {
+        const startedAt = Date.now();
+        const found = (await findPath()) !== null;
+        if (found) {
+            availabilityLatch.noteAvailable();
+            config.log(`${config.label} found: ${toolPath}`);
+            logAvailabilityDecision({
+                tool: config.tool,
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs: Date.now() - startedAt,
+                latched: true,
+                hostStallMs: sweepHostStallMs,
+                budgetMs: config.budgetMs,
+            });
+            return true;
+        }
+        // A timed-out version probe is evidence about this moment, not about
+        // whether the toolchain is installed; it expires instead of latching.
+        const outcome = sweepSawTransient ? "transient" : "missing";
+        const cause = sweepSawTransient ? sweepTransientCause : "not-found";
+        const retryAfterMs = availabilityLatch.noteUnavailable(outcome, cause);
+        logAvailabilityDecision({
+            tool: config.tool,
+            verdict: "unavailable",
+            outcome,
+            cause,
+            elapsedMs: Date.now() - startedAt,
+            latched: outcome !== "transient",
+            hostStallMs: sweepHostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+            budgetMs: config.budgetMs,
+        });
+        return false;
+    }
+    async function isAvailable() {
+        // `read()` returns null when the last verdict was transient and its
+        // cooldown expired, which re-enters the candidate sweep (#1476).
+        const memo = availabilityLatch.read();
+        if (memo !== null)
+            return memo;
+        // Now that a verdict can expire, concurrent callers arriving just after a
+        // cooldown must share ONE sweep rather than each spawning their own.
+        if (ensureInFlight)
+            return ensureInFlight;
+        ensureInFlight = resolveAvailability();
+        try {
+            return await ensureInFlight;
+        }
+        finally {
+            ensureInFlight = null;
+        }
+    }
+    return { findPath, isAvailable };
+}

package/node_modules/pi-lens/dist/clients/dispatch/runners/yaml-rule-parser.js

@@ -15,6 +15,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import yaml from "../../deps/js-yaml.js";
+import { BoundedLruCache } from "../../bounded-cache.js";
 // --- Constants ---
 /** Overly broad patterns that match everything (cause false positive explosions) */
 export const OVERLY_BROAD_PATTERNS = [
@@ -28,10 +29,10 @@ export const OVERLY_BROAD_PATTERNS = [
 /** Maximum complexity score for rules in blockingOnly mode */
 export const MAX_BLOCKING_RULE_COMPLEXITY = 8;
 // --- Caches ---
-const rulesCache = new Map();
-const blockingRulesCache = new Map();
-const contentRulesCache = new Map();
-const contentBlockingRulesCache = new Map();
+const rulesCache = new BoundedLruCache(64);
+const blockingRulesCache = new BoundedLruCache(64);
+const contentRulesCache = new BoundedLruCache(64);
+const contentBlockingRulesCache = new BoundedLruCache(64);
 // --- Public API ---
 export function clearRulesCache() {
     rulesCache.clear();

package/node_modules/pi-lens/dist/clients/disposition-publish.js

@@ -24,9 +24,10 @@
 import { logBusEvent } from "./bus-events-logger.js";
 import { isBusPublishEnabled } from "./bus-publish.js";
 import { normalizeFilePath } from "./path-utils.js";
+import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const BUS_DISPOSITION_EVENT = "pilens:diagnostic:disposition";
 export const BUS_DISPOSITION_VERSION = 1;
-let busEmit;
+const liveEmitter = createLiveBusEmitter();
 let hasLoggedFailure = false;
 let hasLoggedUnwired = false;
 let hasLoggedDisabled = false;
@@ -38,11 +39,14 @@ let hasLoggedDisabled = false;
  * the MCP server path run in (no pi host, no `pi.events`).
  */
 export function wireDispositionBusEmitter(emitFn) {
-    busEmit = emitFn;
+    liveEmitter.wire(emitFn);
+}
+export function wireDispositionBusEmitterGetter(getter) {
+    liveEmitter.wireGetter(getter);
 }
 /** Test-only: reset module state between test files. */
 export function _resetDispositionPublishForTests() {
-    busEmit = undefined;
+    liveEmitter.reset();
     hasLoggedFailure = false;
     hasLoggedUnwired = false;
     hasLoggedDisabled = false;
@@ -63,7 +67,13 @@ export function publishDisposition(args) {
         }
         return;
     }
-    if (!busEmit) {
+    const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
+        event: BUS_DISPOSITION_EVENT,
+        cwd: normalizeFilePath(args.cwd),
+    }));
+    if (resolution.outcome === "stale-session")
+        return;
+    if (resolution.outcome === "unwired") {
         if (!hasLoggedUnwired) {
             hasLoggedUnwired = true;
             logBusEvent({
@@ -74,6 +84,7 @@ export function publishDisposition(args) {
         }
         return;
     }
+    const busEmit = resolution.emit;
     try {
         const payload = {
             v: BUS_DISPOSITION_VERSION,
@@ -88,6 +99,7 @@ export function publishDisposition(args) {
             reason: args.reason,
         };
         busEmit(BUS_DISPOSITION_EVENT, payload);
+        hasLoggedFailure = false;
         logBusEvent({
             event: BUS_DISPOSITION_EVENT,
             outcome: "emitted",
@@ -100,9 +112,11 @@ export function publishDisposition(args) {
             outcome: "emit_failed",
             cwd: normalizeFilePath(args.cwd),
             error: String(err),
+            ctxSource: resolution.ctxSource,
         });
         if (!hasLoggedFailure) {
             hasLoggedFailure = true;
+            recordStaleBusFailure(BUS_DISPOSITION_EVENT, err);
             args.dbg?.(`disposition-publish: pilens:diagnostic:disposition emit failed (further failures suppressed): ${err}`);
         }
     }

package/node_modules/pi-lens/dist/clients/durable-store.js

@@ -0,0 +1,97 @@
+/**
+ * Synchronous locked read-modify-write commit seam for behavior-gating JSON
+ * stores shared by multiple pi-lens processes.
+ *
+ * The authoritative read happens only after the bounded PID lock is held; the
+ * caller merges only its delta, publication is a throwing atomic replacement,
+ * and success telemetry runs only after publication succeeds.
+ *
+ * Short synchronous commits use a file lock. Awaited commits use the shared
+ * quarantine directory lock, preserving bounded contention and stale-owner
+ * recovery without allowing a late release to delete a replacement owner.
+ */
+import * as fs from "node:fs";
+import fsp from "node:fs/promises";
+import { writeFileAtomic, writeFileAtomicAsync } from "./atomic-write.js";
+import { acquireBoundedPidFileLock, acquireQuarantinePidFileLock, } from "./bounded-pid-file-lock.js";
+function readLocked(path) {
+    try {
+        return fs.readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function commitDurableStore(options) {
+    const release = options.onContention === "skip-log"
+        ? acquireBoundedPidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "skip-log",
+            logContention: options.logContention,
+        })
+        : acquireBoundedPidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "throw",
+        });
+    if (!release)
+        return undefined;
+    let committed;
+    try {
+        const current = options.deserialize(readLocked(options.path));
+        committed = options.merge(current);
+        writeFileAtomic(options.path, options.serialize(committed), {
+            bestEffort: false,
+        });
+        options.afterWriteLocked?.(committed);
+    }
+    finally {
+        release();
+    }
+    return committed;
+}
+async function readLockedAsync(path) {
+    try {
+        return await fsp.readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function commitDurableStoreAsync(options) {
+    const release = options.onContention === "skip-log"
+        ? await acquireQuarantinePidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            staleMs: options.staleMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "skip-log",
+            logContention: options.logContention,
+        })
+        : await acquireQuarantinePidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            staleMs: options.staleMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "throw",
+        });
+    if (!release)
+        return undefined;
+    try {
+        const current = options.deserialize(await readLockedAsync(options.path));
+        const committed = options.merge(current);
+        await writeFileAtomicAsync(options.path, options.serialize(committed), {
+            bestEffort: false,
+        });
+        await options.afterWriteLocked?.(committed);
+        return committed;
+    }
+    finally {
+        await release();
+    }
+}

package/node_modules/pi-lens/dist/clients/eval-timestamp.js

@@ -0,0 +1,17 @@
+import { performance } from "node:perf_hooks";
+/**
+ * The moment pi-lens's module graph started evaluating, captured as this
+ * module's first statement (#1374 host-boot vs extension-eval split).
+ *
+ * This module is otherwise side-effect-free by design (#1434 S3d review): it
+ * does nothing but capture a timestamp. `clients/console-guard-install.ts`
+ * imports it as its FIRST import so the capture happens before the guard's
+ * own install work, and `clients/startup-timing.ts` imports it too, for the
+ * constant alone. Before this split, `startup-timing.ts` imported the
+ * constant FROM `console-guard-install.ts` — which meant importing
+ * startup-timing anywhere (e.g. a test measuring load time) silently
+ * installed the console guard as a side effect. Splitting the constant out
+ * means importing this module, or `startup-timing.ts`, never installs
+ * anything.
+ */
+export const PI_LENS_EVAL_STARTED_MS = performance.now();

package/node_modules/pi-lens/dist/clients/event-loop-monitor.js

@@ -10,11 +10,50 @@
  * of how late the loop services its own timer, i.e. how long it was blocked —
  * with **no per-event JS overhead**. `max` ≈ the worst synchronous block since
  * the last reset.
+ *
+ * ## System-stall contamination (#1122 / #1123)
+ *
+ * `monitorEventLoopDelay` measures timer lag with the monotonic clock
+ * (`uv_hrtime`, backed by `QueryPerformanceCounter` on Windows). When the whole
+ * process is frozen or descheduled — machine sleep / Modern Standby, or paging
+ * thrash under commit-charge exhaustion — its next timer fires late by the
+ * *entire* wall-clock gap, and the histogram records that gap as a "block".
+ * Two distinct system stalls were confirmed against the Windows System event
+ * log: (1) a 290,179 ms block that lined up exactly with a 14:33:05Z→14:37:55Z
+ * Modern Standby window (Kernel-Power 506/507), reported byte-identical by two
+ * independent pids because the HDR histogram quantizes ~290 s into one bucket;
+ * (2) a later silent host exit with zero sleep events but twelve
+ * Resource-Exhaustion-Detector (id 2004) events at 97% commit charge — the
+ * process was paging, not sleeping. Both are machine artifacts, not pi-lens
+ * work; latency.log also held multi-*hour* "blocks" that can only be overnight
+ * sleep.
+ *
+ * Comparing a wall clock to a monotonic clock does NOT catch these: on Windows
+ * both advance across Modern Standby (the histogram's monotonic delta already
+ * equalled the wall gap). The reliable discriminator is **CPU consumption**: a
+ * genuine synchronous block of D ms burns ≈ D ms of main-thread CPU, so the
+ * window that contains it must have consumed at least ~D ms of CPU. A frozen or
+ * thrashing process consumes ~0 CPU across the gap, so when the worst block
+ * exceeds all the CPU the window could account for, it was a stall, not work.
+ * We window per turn (so the CPU accounting is bounded and each block is
+ * attributable to its turn) and tag system-stall-suspected samples instead of
+ * letting them poison the "worst real block" high-water.
  */
+import { logExtension } from "./extension-log.js";
 import { monitorEventLoopDelay } from "node:perf_hooks";
 const NS_PER_MS = 1e6;
+const US_PER_MS = 1e3;
 let histogram;
 let monitorUnavailable = false;
+// Per-window (per-turn) baselines for CPU-vs-wall accounting. Captured when the
+// monitor starts and re-captured on every reset, so each window's CPU budget is
+// measured against exactly the histogram window it will be compared to.
+let windowStartWallMs = 0;
+let windowStartCpuMs = 0;
+const cpuTotalMs = () => {
+    const c = process.cpuUsage();
+    return (c.user + c.system) / US_PER_MS;
+};
 /**
  * Start the monitor (idempotent). Call once, as early as possible, so startup
  * blocks are captured. Cheap — the sampling is native; nothing runs per event.
@@ -32,26 +71,76 @@ export function startEventLoopMonitor(resolutionMs = 20) {
         const h = monitorEventLoopDelay({ resolution: resolutionMs });
         h.enable();
         histogram = h;
+        windowStartWallMs = Date.now();
+        windowStartCpuMs = cpuTotalMs();
     }
     catch (err) {
         monitorUnavailable = true;
-        console.error(`[pi-lens] event-loop occupancy telemetry disabled (runtime lacks monitorEventLoopDelay): ${err?.message ?? String(err)}`);
+        logExtension({
+            subsystem: "event-loop-monitor",
+            message: `event-loop occupancy telemetry disabled (runtime lacks monitorEventLoopDelay): ${err?.message ?? String(err)}`,
+        });
     }
 }
 const safeMs = (ns) => Number.isFinite(ns) ? Math.round((ns / NS_PER_MS) * 10) / 10 : 0;
+/**
+ * Classify a worst-block sample as genuine CPU work or a suspend/freeze
+ * artifact. Pure so the discrimination is testable without the (vitest-flaky)
+ * native histogram or a real machine sleep.
+ *
+ * A block is system-stall-suspected only when it is both (a) larger than any
+ * plausible synchronous pi-lens stall (`floorMs`, default 20 s — the real tier
+ * observed in latency.log tops out ~15 s) and (b) unaccounted for by the
+ * window's CPU budget (`windowCpuMs + slopMs < maxMs`). The floor keeps a real
+ * multi-second I/O-bound block (low CPU, but genuine) from being mislabeled,
+ * while a frozen or paging process — ~0 CPU across a minutes-to-hours gap —
+ * always trips. Sub-floor blocks are never auto-tagged, but the logged
+ * `windowCpuMs`/`windowWallMs` still expose the CPU-vs-wall ratio so a reviewer
+ * can spot a shorter paging stall by hand.
+ *
+ * KNOWN AMBIGUITY (honest, not fully resolvable from CPU alone): a genuine
+ * pi-lens block that is BLOCKED IN A SYSCALL for >20 s — e.g. a `readdirSync` /
+ * `statSync` stalled on a OneDrive/cloud-backed path fetching a dehydrated file,
+ * or an antivirus-throttled read — also consumes ~0 CPU while wall time
+ * advances, so it is CPU-indistinguishable from a suspend and WILL be tagged
+ * `suspectSystemStall` and excluded from the health high-waters. That is the
+ * conservative choice (a >20 s synchronous FS stall is itself a P0-worthy bug we
+ * do NOT want silently counted as normal), and it is not silenced: such a sample
+ * still re-logs every turn with its `lastPhase` attribution, which is the
+ * forensic breadcrumb for exactly this class. Sharper corroboration (a magnitude
+ * ceiling, a `maxMs`-vs-`windowWallMs` ratio) is tracked as a follow-up note on
+ * #1123, not decided here.
+ */
+export function isSuspendSuspectedBlock(maxMs, windowCpuMs, floorMs = 20000, slopMs = 1000) {
+    if (maxMs < floorMs)
+        return false;
+    return windowCpuMs + slopMs < maxMs;
+}
 /** Current occupancy stats, or undefined if the monitor was never started. */
 export function getEventLoopStats() {
     if (!histogram)
         return undefined;
+    const maxMs = safeMs(histogram.max);
+    const windowWallMs = Math.max(0, Date.now() - windowStartWallMs);
+    const windowCpuMs = Math.max(0, cpuTotalMs() - windowStartCpuMs);
     return {
-        maxMs: safeMs(histogram.max),
+        maxMs,
         p99Ms: safeMs(histogram.percentile(99)),
         meanMs: safeMs(histogram.mean),
+        windowWallMs: Math.round(windowWallMs),
+        windowCpuMs: Math.round(windowCpuMs),
+        suspectSystemStall: isSuspendSuspectedBlock(maxMs, windowCpuMs),
     };
 }
-/** Reset the histogram — e.g. at session/turn boundaries for per-window stats. */
+/**
+ * Reset the histogram and re-baseline the CPU/wall window — called at turn
+ * boundaries so each window's worst block is attributable to that turn and its
+ * CPU budget is measured over the same span (#192 intent, wired in #1122).
+ */
 export function resetEventLoopMonitor() {
     histogram?.reset();
+    windowStartWallMs = Date.now();
+    windowStartCpuMs = cpuTotalMs();
 }
 /**
  * Decide whether a freeze is worth persisting to `latency.log`. Pure so the
@@ -68,4 +157,6 @@ export function _stopEventLoopMonitorForTest() {
     histogram?.disable();
     histogram = undefined;
     monitorUnavailable = false;
+    windowStartWallMs = 0;
+    windowStartCpuMs = 0;
 }