@herbertgao/pi-extensions 2026.10.0 → 2026.10.2

package/node_modules/pi-lens/dist/clients/env-utils.js

@@ -1,83 +0,0 @@
-/**
- * Environment / config input helpers.
- *
- * Small, dependency-free utilities used by logger modules and runtime tuning
- * knobs to keep duplicated env-handling expressions in a single place.
- */
-/**
- * True when pi-lens should suppress side-effecting log writes — e.g. inside
- * the vitest test runner, or when callers explicitly set `PI_LENS_TEST_MODE=1`.
- *
- * Resolution:
- *   - `PI_LENS_TEST_MODE === "1"` → true (explicit opt-in)
- *   - `VITEST` set and `PI_LENS_TEST_MODE !== "0"` → true (vitest default, with explicit opt-out)
- *   - otherwise false
- *
- * Replaces the boolean previously duplicated verbatim in ~10 logger modules.
- */
-export function isTestMode() {
-    if (process.env.PI_LENS_TEST_MODE === "1")
-        return true;
-    if (process.env.VITEST && process.env.PI_LENS_TEST_MODE !== "0")
-        return true;
-    return false;
-}
-/**
- * Coerce an arbitrary input to a non-negative finite number, or 0 otherwise.
- *
- * Use this to gate config / env values before they flow into `Math.max` /
- * `Math.min` / `setTimeout`. `Number(undefined)` is `NaN`, and a single NaN
- * argument makes `Math.max` return NaN, which `setTimeout` silently treats
- * as 0 — see the runner-timeout-floor regression caught in PR #109.
- *
- * @example
- * ```ts
- * const floor = Math.max(
- *   toPositiveFinite(process.env.PI_LENS_KNOB_MS),
- *   toPositiveFinite(loadedConfig?.knobMs),
- *   0,
- * );
- * ```
- */
-export function toPositiveFinite(value) {
-    const num = typeof value === "number" ? value : Number(value);
-    return Number.isFinite(num) && num > 0 ? num : 0;
-}
-/**
- * Factory for the lazy-memoized "positive-finite-number env override, else a
- * default" getter pattern repeated across `startup-scan.ts` (#699, #758) and
- * originally documented as house style in `runtime-config.ts` / `slow-fs.ts` /
- * `subagent-mode.ts` (#763).
- *
- * `get()` reads `process.env[envName]` through {@link toPositiveFinite} the
- * first time it's called, memoizes the result (or `fallback` when the env var
- * is unset/non-finite/non-positive), and returns the memo on every subsequent
- * call. `_resetForTests()` clears the memo so a test can flip the env var and
- * observe a fresh read (matching the existing `_resetForTests` convention).
- *
- * Deliberately does NOT touch `process.env` until `get()` is first called —
- * that's the entire point of the lazy pattern: importing a module must never
- * have a side effect on process env at load time.
- *
- * @example
- * ```ts
- * const _ttl = lazyEnvNumber("PI_LENS_STARTUP_SCAN_VERDICT_TTL_MS", DEFAULT_TTL_MS);
- * export const getStartupScanVerdictTtlMs = _ttl.get;
- * export const _resetStartupScanVerdictTtlForTests = _ttl._resetForTests;
- * ```
- */
-export function lazyEnvNumber(envName, fallback) {
-    let memo;
-    return {
-        get() {
-            if (memo !== undefined)
-                return memo;
-            const envValue = toPositiveFinite(process.env[envName]);
-            memo = envValue > 0 ? envValue : fallback;
-            return memo;
-        },
-        _resetForTests() {
-            memo = undefined;
-        },
-    };
-}

package/node_modules/pi-lens/dist/clients/error-class.js

@@ -1,23 +0,0 @@
-/**
- * The class name of a caught error, and NOTHING else — never the message,
- * which for some callers could quote content they do not want to risk
- * surfacing (a config-core bug thrown while walking the raw, untrusted
- * parsed document; a whole-resolution catch wrapping several stages at
- * once). One leaf so that guarantee does not grow a third, fourth, and
- * fifth hand-rolled `error instanceof Error ? error.name : "unknown error"`
- * (#2451 — `clients/config-warn.ts`'s `normalizeParseErrorReason` (the
- * `classOnly` option), `clients/config-core/normalize.ts`,
- * `clients/config-core/resolve.ts`, and `clients/lens-config.ts` all call
- * this instead of inlining their own copy).
- *
- * Zero imports of its own, deliberately: `config-core/` must never import a
- * sink (`clients/config-warn.ts` -> the degradation ledger) — that exact
- * import closed seven cycles when #2426 removed it, and importing
- * `normalizeParseErrorReason` from inside `config-core/` to get this one
- * value back would reopen them. This leaf is how `config-warn.ts` and
- * `config-core/*.ts` share ONE implementation without either importing the
- * other.
- */
-export function errorClassName(error) {
-    return error instanceof Error ? error.name : "unknown error";
-}

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

@@ -1,17 +0,0 @@
-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-hold.js

@@ -1,274 +0,0 @@
-/**
- * #2507: hold the event loop for the lifetime of in-flight work that would
- * otherwise be kept alive by NOTHING.
- *
- * Every handle pi-lens owns on the way to an LSP answer is deliberately
- * unref'd. `clients/lsp/launch.ts#unrefLspProcessHandles` unrefs the language
- * server child AND its three stdio pipes so a settled one-shot `pi --print`
- * can exit without waiting for a lingering server (the #1097/#1110 class);
- * `clients/child-unref.ts` does the same for every fire-and-forget probe
- * spawn; `bounded()` and several LSP waits unref their timers for the same
- * reason. That is correct for an IDLE process and wrong for a BUSY one: in a
- * headless child (`pi --mode json -p --no-extensions`, stdin ignored, no TUI,
- * no other extension holding a socket or timer) an in-flight `lsp_diagnostics`
- * call reaches a point where the only thing it is waiting on is an unref'd
- * timer or an unref'd pipe, libuv finds no referenced handle, and Node exits 0
- * IN THE MIDDLE of the tool call — no error, no result, no `turn_end`. The
- * reporter measured it against pyright; the drain site the repro lands on is
- * `LSPService.ensureWarmForSweep`'s warm-up retry backoff (an explicitly
- * `.unref()`'d `setTimeout`), but it is one of many: any await whose only
- * pending handle is unref'd has the same shape.
- *
- * The fix is NOT to stop unref'ing — that would leak a lingering server into
- * every settled one-shot process, which is the reason the unref exists. It is
- * to hold ONE referenced handle for exactly as long as something is in
- * flight: a counted keep-alive, armed while at least one hold is taken and
- * disarmed the moment the last one is released. Idle behaviour is therefore
- * byte-identical to before — no hold, no timer, nothing referenced.
- *
- * Shape 15's screen (AGENTS.md), which this follows deliberately:
- *  - a COUNTER of tokens, not a boolean, so overlapping tool calls each
- *    release independently and a throwing/aborted caller still releases
- *    (callers release from `finally`);
- *  - a bounded lifetime PER HOLD, because a leaked hold is the INVERSE defect
- *    (a process that can never exit). Each token gets {@link
- *    getEventLoopHoldMaxMs} measured from its OWN acquire — derived from the
- *    longest legitimate operation's ceiling (`getWorkspaceSweepMaxHoldAgeMs`,
- *    the full-scan wall clock plus its safety margin) rather than a second,
- *    independently-drifting literal. The keep-alive is armed for the SOONEST
- *    outstanding deadline; when it fires, only tokens that are actually stale
- *    are released (with a log record naming them), and it re-arms for
- *    whatever remains. An epoch-anchored version of this — one timer from the
- *    first hold, clearing every token when it fired — was #2649 review F1: a
- *    call issued late in a legitimate 300s `lens_diagnostics mode=full` was
- *    force-released seconds after starting, i.e. #2507's drain reproduced BY
- *    the fix.
- *
- * There is deliberately NO session-boundary clear here, unlike
- * `clients/lsp/workspace-sweep-hold.ts`. A `session_start` can land mid-turn
- * (see `clients/bootstrap.ts`), so clearing holds on a session boundary would
- * un-hold a tool call that is still running and reintroduce this exact defect
- * for it. The hold is scoped to one call's try/finally, not to a session.
- */
-import { claimPhaseOncePerSession, logLatency, releaseOncePerSessionPhase, } from "./latency-logger.js";
-import { getWorkspaceSweepMaxHoldAgeMs } from "./lsp/workspace-sweep-hold.js";
-import { getProcessSingleton } from "./process-singletons.js";
-/** The one row per session proving the keep-alive was taken (#2649 F2). */
-const EVENT_LOOP_HOLD_ARMED_PHASE = "event_loop_hold_armed";
-const EVENT_LOOP_HOLD_FAMILY = "event-loop-hold";
-const EVENT_LOOP_HOLD_VERSION = 1;
-/**
- * Process-scoped on purpose: pi evaluates the pi-lens module graph more than
- * once in one process (see `clients/process-singletons.ts`), and what is being
- * counted here is a property of the PROCESS's event loop, not of one module
- * evaluation. Two copies would arm two timers for one loop.
- */
-function state() {
-    return getProcessSingleton(EVENT_LOOP_HOLD_FAMILY, EVENT_LOOP_HOLD_VERSION, () => ({ holds: new Map(), nextHoldId: 1, timer: undefined }));
-}
-/**
- * Upper bound on how long ONE hold — each hold, measured from its OWN
- * acquire — may keep this process alive. Derived from `lens_diagnostics
- * mode=full`'s own wall-clock ceiling plus the shared
- * `SWEEP_IDLE_SAFETY_MARGIN_MS` — the same derivation the workspace-sweep
- * hold's max-hold-age failsafe uses, so the two cannot drift apart into a
- * relationship where the longest legitimate tool call outlives the bound that
- * is supposed to only catch bugs.
- */
-export function getEventLoopHoldMaxMs() {
-    return getWorkspaceSweepMaxHoldAgeMs();
-}
-/**
- * Arm the keep-alive for the SOONEST deadline any outstanding hold has — the
- * earliest moment a token can become stale — never for a fixed epoch from the
- * first hold (#2649 review F1).
- *
- * Round 1 armed once on 0→1 and cleared every token when it fired, so a call
- * that started while an older one was still running inherited whatever was
- * left of the FIRST call's bound: a `lens_diagnostics mode=full` legitimately
- * running to its 300s ceiling force-released a healthy `lsp_diagnostics`
- * issued at t=305s, which is #2507's own drain produced by the fix. The
- * reviewer reproduced it in a real child with the bound shortened: both calls
- * unsettled, `active=[]`, `EXIT code=0`.
- *
- * Soonest-deadline, not the youngest survivor's: the youngest would let an
- * older survivor overstay its own max age by the whole age gap. Each token is
- * released when IT is stale and never before.
- */
-function armForNextDeadline(current) {
-    if (current.timer !== undefined)
-        return;
-    if (current.holds.size === 0)
-        return;
-    const maxMs = getEventLoopHoldMaxMs();
-    let soonest = Number.POSITIVE_INFINITY;
-    for (const entry of current.holds.values()) {
-        soonest = Math.min(soonest, entry.acquiredAt + maxMs);
-    }
-    // A past-due deadline is left negative on purpose: Node clamps any delay
-    // below 1ms to 1ms, so it fires on a later turn of the loop either way, and
-    // a hand-written floor here would be a guard naming a recurrence that
-    // cannot happen (#2649 verify F4 — probed: 5 re-arms at delay -5000
-    // completed in 5ms, and no test reds without the floor).
-    const delayMs = soonest - Date.now();
-    // NOT `unref()`'d — referencing the loop is this timer's entire job. It is
-    // also the failsafe: when it fires, whatever is stale is over either way.
-    current.timer = setTimeout(() => reapStaleHolds(), delayMs);
-}
-function disarmIfIdle(current) {
-    if (current.holds.size > 0)
-        return;
-    if (current.timer === undefined)
-        return;
-    clearTimeout(current.timer);
-    current.timer = undefined;
-}
-/**
- * Release every hold that has outlived {@link getEventLoopHoldMaxMs} ON ITS
- * OWN CLOCK, log what was released, and re-arm for whatever is still
- * outstanding. Same shape as `clients/lsp/workspace-sweep-hold.ts`'s
- * `reapStaleHolds` — deliberately a second, independent implementation rather
- * than a shared ledger (that consolidation is tracked separately).
- */
-function reapStaleHolds() {
-    const current = state();
-    current.timer = undefined;
-    try {
-        const maxMs = getEventLoopHoldMaxMs();
-        const now = Date.now();
-        const released = [];
-        for (const [holdId, entry] of current.holds) {
-            if (now - entry.acquiredAt <= maxMs)
-                continue;
-            current.holds.delete(holdId);
-            released.push(entry);
-        }
-        if (released.length > 0) {
-            recordForceReleased(released, current.holds.size, maxMs, now);
-        }
-    }
-    finally {
-        // A survivor is held by nothing until this re-arms — the drain — and
-        // forever if it never does — the leak. In a `finally` because this runs
-        // inside a timer callback, where anything that escapes is an uncaught
-        // exception, and because the round-2 code put the log between the reap
-        // and the re-arm: a throwing sink stranded the survivor (#2649 verify
-        // F3). The map is already consistent by here — entries are deleted
-        // before anything is logged.
-        armForNextDeadline(current);
-    }
-}
-/**
- * The force-release record, and its own absorption. Telemetry may not break
- * the guard it observes — the house rule spelled at
- * `clients/runtime-tool-call.ts`'s blocked-attribution cleanup: a guard that
- * fails because its telemetry broke is worse than no guard. Nothing here has
- * a fallback sink to escalate to; the keep-alive's correctness does not
- * depend on the row being written.
- */
-function recordForceReleased(released, stillHeld, maxMs, now) {
-    try {
-        const oldestAcquiredAt = Math.min(...released.map((entry) => entry.acquiredAt));
-        logLatency({
-            type: "phase",
-            phase: "event_loop_hold_force_released",
-            filePath: "",
-            durationMs: now - oldestAcquiredAt,
-            metadata: {
-                maxHoldMs: maxMs,
-                releasedHolds: released.length,
-                stillHeld,
-                labels: [...new Set(released.map((entry) => entry.label))].slice(0, 8),
-            },
-        });
-    }
-    catch {
-        // see the doc comment — a broken sink must not reach the reap path
-    }
-}
-/**
- * ONE row per session saying the keep-alive was actually taken (#2649 review
- * F2). Without it the only record this module ever writes is the failsafe, so
- * a silent log cannot distinguish "working as designed" from "never wired at
- * all" — the #2526 gap shape. Claimed through the logger's own
- * once-per-session mechanism rather than a private latch, so the "one row per
- * session" a reader counts against is the same property `config_resolved`
- * has.
- */
-function recordFirstArm(entry, maxMs) {
-    try {
-        if (!claimPhaseOncePerSession(EVENT_LOOP_HOLD_ARMED_PHASE, "process")) {
-            return;
-        }
-        logLatency({
-            type: "phase",
-            phase: EVENT_LOOP_HOLD_ARMED_PHASE,
-            filePath: "",
-            durationMs: 0,
-            metadata: { label: entry.label, maxHoldMs: maxMs },
-        });
-    }
-    catch {
-        // This runs on the ACQUIRE path, and `normalizeToolDefinition` takes the
-        // hold outside its own try — so a throw here rejected the tool call with
-        // the sink's error instead of returning the tool's result (#2649 verify
-        // F3). Same house rule as `recordForceReleased` above: the hold is
-        // already taken and armed by this point, so absorbing the throw loses a
-        // log row and nothing else.
-    }
-}
-/**
- * Take one hold for the lifetime of a piece of in-flight work, and return its
- * release. Callers MUST release from a `finally` block: a throw, a rejection
- * or an abort has to release exactly like a normal return, or the hold leaks
- * and the process stops being able to exit.
- *
- * The release is identity-guarded and idempotent — calling it twice, or after
- * the max-age failsafe already force-released it, is a no-op and never
- * disarms another caller's hold.
- */
-export function acquireEventLoopHold(label) {
-    const current = state();
-    const holdId = current.nextHoldId++;
-    const entry = { acquiredAt: Date.now(), label };
-    current.holds.set(holdId, entry);
-    const wasArmed = current.timer !== undefined;
-    armForNextDeadline(current);
-    if (!wasArmed)
-        recordFirstArm(entry, getEventLoopHoldMaxMs());
-    return () => {
-        const now = state();
-        if (!now.holds.delete(holdId))
-            return;
-        disarmIfIdle(now);
-    };
-}
-/** Test-only: how many holds are outstanding right now. */
-export function _eventLoopHoldCountForTests() {
-    return state().holds.size;
-}
-/**
- * Test-only: the keep-alive handle's own state. `hasRef` is the property the
- * whole fix rests on — a handle that is armed but unref'd holds nothing — so
- * it is read from the live `Timeout` (`hasRef()`), not asserted from the
- * source text.
- */
-export function _eventLoopKeepAliveForTests() {
-    const timer = state().timer;
-    return {
-        armed: timer !== undefined,
-        hasRef: timer?.hasRef?.() === true,
-    };
-}
-/** Test-only: drop every hold and disarm, between tests. */
-export function _resetEventLoopHoldForTests() {
-    // This module's own phase only — never a blanket clear of a structure other
-    // producers claim in (`releaseOncePerSessionPhase`'s doc comment).
-    releaseOncePerSessionPhase(EVENT_LOOP_HOLD_ARMED_PHASE);
-    const current = state();
-    current.holds.clear();
-    if (current.timer !== undefined)
-        clearTimeout(current.timer);
-    current.timer = undefined;
-    current.nextHoldId = 1;
-}

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

@@ -1,250 +0,0 @@
-/**
- * Production event-loop occupancy monitor (#192 Phase 2).
- *
- * pi-lens runs on pi's TUI event loop; a long synchronous block freezes
- * keystrokes. Our telemetry historically logged phase *durations*, which can't
- * distinguish a TUI-freezing synchronous burst from harmless async/subprocess
- * time — that blind spot let a ~1.5s enumeration freeze through (#188/#191).
- *
- * This wraps Node's native `perf_hooks.monitorEventLoopDelay()` — a histogram
- * 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.
- *
- * Purely observational: if the runtime doesn't implement
- * `perf_hooks.monitorEventLoopDelay` (e.g. Bun < 1.3, which throws
- * `ERR_NOT_IMPLEMENTED` on the call), we degrade to "no stats" rather than let
- * the throw abort extension load. `getEventLoopStats()` already tolerates an
- * absent histogram, so every caller keeps working without telemetry.
- */
-export function startEventLoopMonitor(resolutionMs = 20) {
-    if (histogram || monitorUnavailable)
-        return;
-    try {
-        const h = monitorEventLoopDelay({ resolution: resolutionMs });
-        h.enable();
-        histogram = h;
-        windowStartWallMs = Date.now();
-        windowStartCpuMs = cpuTotalMs();
-    }
-    catch (err) {
-        monitorUnavailable = true;
-        logExtension({
-            subsystem: "event-loop-monitor",
-            message: `event-loop occupancy telemetry disabled (runtime lacks monitorEventLoopDelay): ${err?.message ?? String(err)}`,
-        });
-    }
-}
-/**
- * Below this, a block is not classified at all (`below-floor`). #1980 mined
- * the 5 s+ tier; 1 s is a deliberately conservative floor that still covers
- * every block that tier cares about while keeping sub-second jitter — where
- * measurement slop rivals the signal — out of the verdict.
- */
-const STALL_CLASSIFY_FLOOR_MS = 1000;
-/**
- * Slack allowed to the CPU budget before a block counts as unaccounted.
- * `process.cpuUsage()` and the histogram are sampled at slightly different
- * instants and the histogram quantizes, so a block whose CPU coverage is
- * within this much of exact is called `cpu-accounted`, not a stall.
- */
-const STALL_CLASSIFY_SLOP_MS = 250;
-/**
- * Split a block into compute-vs-stall from the CPU it could possibly have
- * burned (#1980). Pure, so the discrimination is testable without the native
- * histogram or a real machine stall — the same reason
- * {@link isSuspendSuspectedBlock} is pure.
- *
- * ## Why this is sound in exactly one direction
- *
- * `windowCpuMs` is the CPU the WHOLE process consumed across the WHOLE window
- * — every thread, every phase, not just this block. So it is an UPPER BOUND on
- * the CPU this one block could have burned. A synchronous compute block of D ms
- * needs ≈ D ms of main-thread CPU. Therefore:
- *
- * - `windowCpuMs + slop < maxMs` PROVES the block was not compute. Even if the
- *   block had been the only thing running, there was not enough CPU in the
- *   whole window to cover it. This is the `non-cpu-stall` verdict and it is a
- *   real inference, not a heuristic.
- * - The converse proves nothing. A window can burn 30 s of CPU in other phases
- *   and still contain a 5 s I/O park. That is why the label is
- *   `cpu-accounted` ("the budget covers it") rather than "compute": it reports
- *   the absence of proof, not the presence of compute.
- *
- * The existing 20 s suspend verdict is not re-derived here; this delegates to
- * {@link isSuspendSuspectedBlock} so there is one definition of a suspend, and
- * `system-stall` is checked BEFORE `non-cpu-stall` because a suspend is the
- * strictly more specific case of the same evidence.
- *
- * ## Known ambiguity, carried forward not silenced
- *
- * `isSuspendSuspectedBlock`'s own doc records that a >20 s synchronous syscall
- * stall is CPU-indistinguishable from a suspend. Nothing here fixes that. What
- * this adds is the tier BELOW that floor: a 5-20 s non-CPU block, which used
- * to read as ordinary compute and now reads as `non-cpu-stall` with the
- * `inFlightPhase` attribution beside it.
- */
-export function classifyLoopBlock(maxMs, windowCpuMs, options = {}) {
-    const { floorMs = STALL_CLASSIFY_FLOOR_MS, slopMs = STALL_CLASSIFY_SLOP_MS, suspendFloorMs, suspendSlopMs, } = options;
-    const cpuCoverageRatio = maxMs > 0 ? Math.round((windowCpuMs / maxMs) * 100) / 100 : undefined;
-    if (maxMs < floorMs)
-        return { stallClass: "below-floor", cpuCoverageRatio };
-    if (isSuspendSuspectedBlock(maxMs, windowCpuMs, suspendFloorMs, suspendSlopMs))
-        return { stallClass: "system-stall", cpuCoverageRatio };
-    if (windowCpuMs + slopMs < maxMs)
-        return { stallClass: "non-cpu-stall", cpuCoverageRatio };
-    return { stallClass: "cpu-accounted", cpuCoverageRatio };
-}
-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);
-    // One classification pass feeds both fields, so `suspectSystemStall` and
-    // `stallClass` can never disagree about the same sample (#1980).
-    const classification = classifyLoopBlock(maxMs, windowCpuMs);
-    return {
-        maxMs,
-        p99Ms: safeMs(histogram.percentile(99)),
-        meanMs: safeMs(histogram.mean),
-        windowWallMs: Math.round(windowWallMs),
-        windowCpuMs: Math.round(windowCpuMs),
-        suspectSystemStall: classification.stallClass === "system-stall",
-        stallClass: classification.stallClass,
-        cpuCoverageRatio: classification.cpuCoverageRatio,
-    };
-}
-/**
- * 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 THIS block beats the session's running high-water. Pure so
- * the threshold logic is testable without the (vitest-flaky) native
- * histogram. Requires `maxMs > lastLoggedMs + deltaMs` above a floor
- * (`minMs`) so noise near the current max doesn't keep re-triggering the
- * high-water bookkeeping.
- *
- * NOTE (#1723): this is no longer the logging gate — see
- * `shouldLogLoopBlock` for that. This function now answers a narrower
- * question ("is this a new session worst?", used for the `worstSoFar`
- * metadata flag and for deciding whether to advance the high-water), because
- * gating the LOG on it hid every sub-maximum block after a session's first
- * large one, which made loop_block-vs-pull-timeout correlation undecidable.
- */
-export function shouldLogWorstBlock(maxMs, lastLoggedMs, minMs = 60, deltaMs = 25) {
-    return maxMs >= minMs && maxMs > lastLoggedMs + deltaMs;
-}
-/**
- * Decide whether a block is worth persisting to `latency.log` AT ALL (#1723).
- * Every block at or above the floor (`minMs`) qualifies — not only a new
- * session worst — because a session's later blocks can be smaller than an
- * early spike yet still be exactly the ones that starved an LSP pull
- * (#1549/#1713) and are otherwise invisible to the correlation.
- *
- * Volume is bounded by CALL CADENCE, not by this gate: the `turn_end` caller
- * invokes this at most once per turn (the histogram window is reset every
- * turn), so the natural cap is one `loop_block` record per turn — a jittery
- * session cannot flood the log because there is nowhere for a second sample
- * to come from within the same turn.
- */
-export function shouldLogLoopBlock(maxMs, minMs = 60) {
-    return maxMs >= minMs;
-}
-/** Test-only: stop and clear the monitor so cases don't leak into each other. */
-export function _stopEventLoopMonitorForTest() {
-    histogram?.disable();
-    histogram = undefined;
-    monitorUnavailable = false;
-    windowStartWallMs = 0;
-    windowStartCpuMs = 0;
-}