pi-lens 4.3.0 → 4.4.0

package/dist/clients/deadline-utils.js

@@ -1,280 +0,0 @@
-/**
- * One implementation of the "race a promise against a timer" pattern that had
- * drifted into three near-identical copies (#366): `withTimeout` (clients/lsp),
- * `withBudget` (read-expansion), and `withinRemaining` (module-report-lsp).
- *
- * The differences between them were real — timeout can *reject* or *resolve
- * undefined*, and the raced promise's own rejection can *propagate* or be
- * *swallowed* — so they are kept as named adapters over one core. Consolidating
- * fixes two latent bugs the copies had: `withBudget` did not suppress the loser
- * promise's late rejection (an unhandled rejection if the timer won first), and
- * `withinRemaining` never cleared its timer.
- */
-import { recordDegradationOnce } from "./degradation-ledger.js";
-/**
- * Combine multiple abort signals into one that aborts when ANY of them does.
- * Returns the single signal unchanged when only one is live, and `undefined`
- * when none are — so callers can pass it straight through. Used so a tool honors
- * both its tool-call `signal` positional and the turn-wired `ctx.signal` (Escape),
- * and to fold in a wall-clock ceiling via `AbortSignal.timeout`.
- */
-export function combineAbortSignals(...signals) {
-    const live = signals.filter((s) => s !== undefined);
-    if (live.length <= 1)
-        return live[0];
-    if (typeof AbortSignal.any === "function")
-        return AbortSignal.any(live);
-    const controller = new AbortController();
-    for (const s of live) {
-        if (s.aborted) {
-            controller.abort(s.reason);
-            break;
-        }
-        s.addEventListener("abort", () => controller.abort(s.reason), {
-            once: true,
-        });
-    }
-    return controller.signal;
-}
-export function withDeadline(promise, options) {
-    const onTimeout = options.onTimeout ?? "reject";
-    const onReject = options.onReject ?? "propagate";
-    const ms = options.ms ??
-        (options.deadlineAt !== undefined ? options.deadlineAt - Date.now() : 0);
-    // Past deadline / non-positive budget: settle immediately, no timer. This
-    // branch returns before the race below ever runs, so — same reason as the
-    // loser-leg catch a few lines down — `promise` needs its own no-op catch
-    // here too: without it, a `promise` that eventually rejects (the caller
-    // already invoked it; this function only decides how long to wait on it)
-    // surfaces as an unhandled rejection instead of being silently superseded
-    // by the immediate timeout/undefined settlement.
-    if (ms <= 0) {
-        promise.catch(() => { });
-        return onTimeout === "undefined"
-            ? Promise.resolve(undefined)
-            : Promise.reject(new Error(`Timeout after ${Math.max(0, ms)}ms`));
-    }
-    // Base promise with rejection handled per `onReject`. In propagate mode we
-    // still attach a no-op catch so that if the timer wins the race, the loser
-    // promise's later rejection does not surface as an unhandled rejection.
-    const base = onReject === "undefined" ? promise.catch(() => undefined) : promise;
-    if (onReject === "propagate")
-        promise.catch(() => { });
-    let timer;
-    const timeoutPromise = new Promise((resolve, reject) => {
-        timer = setTimeout(() => {
-            if (onTimeout === "undefined")
-                resolve(undefined);
-            else
-                reject(new Error(`Timeout after ${ms}ms`));
-        }, ms);
-    });
-    return Promise.race([base, timeoutPromise]).finally(() => {
-        if (timer)
-            clearTimeout(timer);
-    });
-}
-/**
- * Resolve `promise`, or reject with `Error("Timeout after <ms>ms")` once
- * `timeoutMs` elapses. The raced promise's own rejection propagates.
- */
-export function withTimeout(promise, timeoutMs) {
-    return withDeadline(promise, { ms: timeoutMs });
-}
-/**
- * Resolve `promise`, or `undefined` once `budgetMs` elapses (a non-positive
- * budget resolves `undefined` immediately). The raced promise's own rejection
- * propagates.
- */
-export function withBudget(promise, budgetMs) {
-    return withDeadline(promise, { ms: budgetMs, onTimeout: "undefined" });
-}
-/**
- * Resolve `promise`, or `undefined` once the shared `deadlineAt` passes (a past
- * deadline resolves `undefined` immediately). The raced promise's own rejection
- * is swallowed to `undefined`.
- */
-export function withinRemaining(promise, deadlineAt) {
-    return withDeadline(promise, {
-        deadlineAt,
-        onTimeout: "undefined",
-        onReject: "undefined",
-    });
-}
-/**
- * The abort half of a bound, as a value the race can settle on. A symbol, not
- * `undefined`, so `bounded` can tell "the signal fired" from "the awaited work
- * genuinely resolved `undefined`" — the distinction AGENTS.md defect shape 10
- * (silencing counted as fixing) exists to protect.
- */
-const BOUND_ABORTED = Symbol("pi-lens/bounded/aborted");
-/**
- * Await `promise` under BOTH bounds a hook needs: a wall-clock budget AND the
- * hook's own abort signal (#2523 AC2).
- *
- * ## Why the type refuses one bound
- *
- * Every bound in this codebase lived at a LEAF — a spawn timeout, an LSP wait
- * — so a dependency that wedged before reaching the leaf was unreachable by
- * all of them, and `wrapSessionEventHandler` adds neither. The two halves fail
- * differently and neither substitutes for the other: a deadline alone means
- * Escape cannot release the hook (measured: still blocked 30s after the abort
- * fired), and a signal alone means a dependency that wedges without anyone
- * pressing Escape never returns at all (measured: 400s, the harness ceiling).
- * `ms` and `signal` are therefore both non-optional properties, so
- * `bounded(p, { ms: 500, hook, label })` is a COMPILE error, not a review
- * catch. `tests/clients/bounded-hook-await.test.ts` pins that with
- * `@ts-expect-error`: weaken either property and those directives become
- * unused, which `tsc` reports as TS2578.
- *
- * ## Semantics
- *
- * - Resolves to the promise's value when it settles inside both bounds.
- * - Resolves to `undefined` when the budget elapses OR a signal aborts,
- *   whichever comes first — and firing a signal settles IMMEDIATELY, it
- *   never waits the remaining deadline out.
- * - Rejections propagate: this helper decides how LONG to wait, never what an
- *   error means. Once a bound has fired, a later rejection from the
- *   superseded promise is suppressed (a no-op catch is attached to the work
- *   up front) so it cannot surface as an unhandled rejection.
- *
- * ## What reaches the ledger, and what deliberately does not
- *
- * Which bound fired decides this, via {@link BoundCause}. Only the DEADLINE
- * records `hook-await-exceeded` — ONE rising-edge row per (hook, label) via
- * `recordDegradationOnce`, naming the hook, the await, the budget, the actual
- * elapsed ms and the cause. Bounded by construction: a hook that blows its
- * budget on every turn of a long session writes one ledger row, not one per
- * turn. Promote it to `incrementDegradationCount` if slice 2 finds the exact
- * tally is needed.
- *
- * A `"caller-abort"` records NOTHING. The caller's signal is the user pressing
- * Escape or a turn being cancelled — a deliberate action, not a degraded
- * environment. `clients/bootstrap.ts` already carries this lesson at its
- * `if (unavailableReason !== "aborted")` guard: writing a cancel to the ledger
- * made it indistinguishable from an unhealthy analyzer graph in
- * `pilens_health`. This helper is meant to become THE bound primitive at
- * ~187 call sites, so recording a cancel here would ship that inversion
- * everywhere at once.
- *
- * A `"shutdown"` records `hook-await-abandoned`, which is in
- * `INFORMATIONAL_DEGRADATION_KINDS` — teardown abandoning in-flight work is
- * the design, so it is a tally rather than a `⚠`.
- *
- * `undefined` therefore means "no answer inside the bound" and must never be
- * read as an empty/clean ANSWER (defect shape 10, and the #240 lesson that a
- * failed diagnostic pull is not a clean file). The caller decides what the
- * absence means; the ledger row is what makes it visible either way.
- *
- * The promise is not cancelled — nothing here can cancel work already
- * started. It is abandoned, with the abandonment recorded. Work that must not
- * outlive its hook needs the signal threaded INTO it as well (#2523 slice 2's
- * `TurnEndDeps`/`AgentEndDeps`/`SessionStartDeps` change); wrapping the await
- * bounds the HOOK, not the work.
- */
-export async function bounded(promise, options) {
-    const { signal, shutdownSignal, hook, label } = options;
-    // A non-finite budget settles immediately rather than throwing. The type
-    // forbids it, but a JS caller (or a `@ts-expect-error` probe) can still
-    // hand one over, and `setTimeout(fn, NaN)` would fire on the next tick
-    // with a warning — a helper whose whole job is keeping a hook from blowing
-    // up must not itself misbehave inside one. Same
-    // `Number.isFinite`-before-`Math.max` gate the runtime-config readers use.
-    const ms = Number.isFinite(options.ms) ? Math.max(0, options.ms) : 0;
-    const startedAt = Date.now();
-    // Late rejection from work a bound has already abandoned must not surface
-    // as an unhandled rejection. Attached to the BOXED promise, which is what
-    // the race below actually subscribes to; the caller still sees a rejection
-    // that arrives inside the bounds, because `Promise.race` attaches its own
-    // handler to the same promise.
-    const boxed = promise.then((value) => ({ value }));
-    void boxed.catch(() => { });
-    // ONE timer and ONE listener per source signal, all released in `finally`
-    // (#2530 review F2/F4).
-    //
-    // The round-1 implementation folded the wall clock in as
-    // `AbortSignal.timeout(ms)` and combined it through `AbortSignal.any`,
-    // then ALSO passed `ms` to `withDeadline` — two timers for one budget, and
-    // a composite signal per call. `AbortSignal.any` does not add a listener
-    // to its sources: it appends the composite to an internal dependant list
-    // on each of them, which lives as long as the SOURCE does. The hook signal
-    // outlives one await by a whole turn, so 20 000 successful `bounded()`
-    // calls on one hook signal left 20 000 entries on it, and the `finally`'s
-    // `removeEventListener` — aimed at the throwaway composite — removed
-    // nothing from the source. Listening on the sources directly is what makes
-    // the cleanup reach the thing that outlives the call.
-    let cause;
-    let timer;
-    let onCallerAbort;
-    let onShutdownAbort;
-    const abandoned = new Promise((resolve) => {
-        // `abandonedError`'s precedence, unchanged: the caller's own signal
-        // first, then teardown, then the clock. A turn cancelled while the
-        // session also happens to be tearing down is still a cancel.
-        const fire = (reason) => {
-            cause ??= reason;
-            resolve(BOUND_ABORTED);
-        };
-        // `signal?.` — a missing signal is treated as one that never aborts.
-        // The KEY is required (so a call that never mentions a signal does not
-        // compile), but its type admits `undefined` because several seams
-        // genuinely hold `AbortSignal | undefined` — see `BoundedOptions.signal`
-        // for which ones and why. This branch is what lets them pass it straight
-        // through instead of each spelling its own never-aborting stand-in
-        // (#2557 review F2), and it is also what keeps a JS caller, or a
-        // `@ts-expect-error` probe, from making a helper whose whole job is
-        // keeping a hook from blowing up throw `Cannot read properties of
-        // undefined` (#2530 round 3 F5).
-        if (signal?.aborted)
-            return fire("caller-abort");
-        if (shutdownSignal?.aborted)
-            return fire("shutdown");
-        // A zero budget ("this hook may not await at all") is a bound that has
-        // already elapsed, not a timer to arm.
-        if (ms <= 0)
-            return fire("deadline");
-        timer = setTimeout(() => fire("deadline"), ms);
-        // Never hold the event loop open past the hook this bounds.
-        timer.unref?.();
-        onCallerAbort = () => fire("caller-abort");
-        signal?.addEventListener("abort", onCallerAbort, { once: true });
-        if (shutdownSignal) {
-            onShutdownAbort = () => fire("shutdown");
-            shutdownSignal.addEventListener("abort", onShutdownAbort, {
-                once: true,
-            });
-        }
-    });
-    try {
-        // The value is boxed so a promise that legitimately resolves
-        // `undefined` stays distinguishable from a bound firing (defect shape
-        // 10: a silenced answer must not read as a clean one).
-        const settled = await Promise.race([boxed, abandoned]);
-        if (settled !== BOUND_ABORTED)
-            return settled.value;
-        const elapsedMs = Date.now() - startedAt;
-        const fired = cause ?? "deadline";
-        // A caller's own abort is Escape or a cancelled turn — deliberate, not
-        // a degradation, and deliberately absent from the ledger.
-        if (fired === "deadline" || fired === "shutdown") {
-            recordDegradationOnce({
-                kind: fired === "deadline" ? "hook-await-exceeded" : "hook-await-abandoned",
-                subject: `${hook}:${label}`,
-                reason: fired === "deadline"
-                    ? `exceeded ${ms}ms budget after ${elapsedMs}ms`
-                    : `abandoned after ${elapsedMs}ms: session is shutting down (budget ${ms}ms)`,
-                metadata: { hook, label, budgetMs: ms, elapsedMs, cause: fired },
-            });
-        }
-        return undefined;
-    }
-    finally {
-        if (timer !== undefined)
-            clearTimeout(timer);
-        if (onCallerAbort)
-            signal?.removeEventListener("abort", onCallerAbort);
-        if (onShutdownAbort) {
-            shutdownSignal?.removeEventListener("abort", onShutdownAbort);
-        }
-    }
-}

package/dist/clients/debug-handles.js

@@ -1,211 +0,0 @@
-/**
- * Handle-origin tracer, institutionalized from the hand-rolled `async_hooks`
- * instrumentation the #1097 investigation used to find a leaked, ref'd
- * `setTimeout` keeping a `--print --no-session` process alive after
- * `agent_settled` (root-caused/fixed in #1110). The #1097 reporter explicitly
- * asked for a built-in active-resource dump (#1123 item 4) so the next
- * "process won't exit" report is a one-line diagnostic instead of a fresh
- * multi-hour expedition.
- *
- * `PI_LENS_DEBUG_HANDLES=1` (read ONCE at module load — i.e. must be set
- * before pi-lens starts, not toggled mid-session):
- *   - OFF (default): every export below is a no-op that returns immediately
- *     on the flag check — no writer constructed, no async_hooks hook
- *     installed, zero allocations on any hot path. `dumpActiveHandles` is
- *     called from live lifecycle hooks (index.ts `agent_settled` /
- *     `session_shutdown`), so this module must cost nothing when unset.
- *   - ON: (a) `dumpActiveHandles(label)` calls `process.getActiveResourcesInfo()`,
- *     tallies counts by resource type, and writes one ndjson line to
- *     `~/.pi-lens/debug-handles.log` via the standard `createNdjsonLogger`
- *     family (size-bounded, log-cleanup registered — the same rotation
- *     bounds every other pi-lens log gets, #1101-era registry via
- *     clients/ndjson-logger.ts's self-registration + clients/log-cleanup.ts).
- *     (b) an `async_hooks` creation-site tracker, installed at module load
- *     ONLY when the flag is on, records a trimmed `Error().stack` per
- *     tracked resource id for timer/socket/handle async-hook types and
- *     removes the entry on `destroy`. This is a real per-resource-creation
- *     cost — `async_hooks` hooks run on every init/destroy in the process —
- *     so it is strictly opt-in and documented here as a debug-only expense,
- *     never installed unless the flag was on before this module first loads.
- *
- * Bounded tracker (the one-axis-rule, AGENTS.md "resource bounded along one
- * axis but unbounded along another"): the creation-site map is capped at
- * `TRACKER_MAX_ENTRIES` before adding a new entry past the cap — never
- * unbounded growth even in a pathological timer-storm session. Eviction
- * protects the first `TRACKER_PROTECTED_COUNT` insertion-order entries and
- * evicts the oldest entry OUTSIDE that protected zone instead: a #1097-style
- * leaked handle is typically among the EARLIEST created in a session (it's
- * the one nothing ever cleaned up), so a naive drop-oldest policy would let a
- * later burst past the cap evict exactly the evidence this tracer exists to
- * capture, silently. `evictedCount` (a running total, always present on the
- * dump entry once the tracker is installed) makes any eviction — protected
- * or not — an explicit, visible fact instead of a silent gap in attribution.
- */
-import * as asyncHooks from "node:async_hooks";
-import * as path from "node:path";
-import { getGlobalPiLensLogDir } from "./probe-home-state.js";
-import { getMaxLogSizeMB } from "./log-cleanup.js";
-import { createNdjsonLogger } from "./ndjson-logger.js";
-/** Read once at module load — see module docstring. Not re-read per call. */
-const DEBUG_HANDLES_ENABLED = process.env.PI_LENS_DEBUG_HANDLES === "1";
-const DEBUG_HANDLES_LOG_FILE = path.join(getGlobalPiLensLogDir(), "debug-handles.log");
-/** Cap on tracked in-flight creation sites (bounded past this). */
-export const TRACKER_MAX_ENTRIES = 500;
-/** The first N insertion-order entries are never evicted — see the module
- *  docstring's "leaked handles skew early" rationale. Must stay well below
- *  `TRACKER_MAX_ENTRIES` so there is always an evictable, unprotected tail. */
-export const TRACKER_PROTECTED_COUNT = 100;
-/** async_hooks `type` strings worth attributing: timers, sockets, process/
- *  signal handles — the shapes #1097's hand-rolled tracer actually needed
- *  (a `Timeout`). Excludes high-frequency non-handle async resources
- *  (`PROMISE`, `FSREQCALLBACK`, ...) that would dominate the map with no
- *  "why is the process still alive" signal. */
-const TRACKED_TYPE_RE = /^(Timeout|Immediate|TCPWRAP|TCPSOCKETWRAP|TCPCONNECTWRAP|PIPEWRAP|PIPECONNECTWRAP|UDPWRAP|UDPSENDWRAP|TTYWRAP|ProcessWrap|Signal)/;
-function trimStack(raw) {
-    if (!raw)
-        return "";
-    // Drop the "Error" header line and this module's own init() frame; keep a
-    // bounded number of caller frames — enough to identify the call site
-    // without unbounded per-entry memory.
-    const lines = raw.split("\n").slice(1);
-    const callerLines = lines.filter((line) => !line.includes("debug-handles.js") && !line.includes("debug-handles.ts"));
-    return callerLines.slice(0, 8).join("\n").slice(0, 2000);
-}
-/** Running total of tracker evictions this process (never reset) — surfaced
- *  on every dump entry once the tracker is installed, per the P2 fix: an
- *  eviction must always be a visible fact, never a silent attribution gap. */
-let trackedEvictedCount = 0;
-/** Test-only accessor for the running eviction total. */
-export function _evictedCountForTest() {
-    return trackedEvictedCount;
-}
-/** Record one tracked resource's creation site. Once the bounded cap is
- *  reached, evicts the oldest entry OUTSIDE the first `TRACKER_PROTECTED_COUNT`
- *  insertion-order entries (Map iteration order == insertion order) — see the
- *  module docstring for why the earliest entries are protected instead of
- *  evicted. Shared by the real async_hooks `init` callback and the test-only
- *  simulator so the eviction policy has exactly one implementation. */
-function recordTrackedInit(map, asyncId, type) {
-    if (!TRACKED_TYPE_RE.test(type))
-        return;
-    if (map.size >= TRACKER_MAX_ENTRIES) {
-        let index = 0;
-        let evictKey;
-        for (const key of map.keys()) {
-            if (index >= TRACKER_PROTECTED_COUNT) {
-                evictKey = key;
-                break;
-            }
-            index++;
-        }
-        if (evictKey !== undefined) {
-            map.delete(evictKey);
-            trackedEvictedCount++;
-        }
-    }
-    map.set(asyncId, { type, stack: trimStack(new Error().stack) });
-}
-function installHandleTracker() {
-    const map = new Map();
-    const hook = asyncHooks.createHook({
-        init(asyncId, type) {
-            recordTrackedInit(map, asyncId, type);
-        },
-        destroy(asyncId) {
-            map.delete(asyncId);
-        },
-    });
-    hook.enable();
-    return map;
-}
-// Only ever constructed/installed when the flag is on — the entire cost of
-// this module when unset is this one boolean check per export below.
-const trackedResources = DEBUG_HANDLES_ENABLED ? installHandleTracker() : null;
-const writer = DEBUG_HANDLES_ENABLED
-    ? createNdjsonLogger({
-        filePath: DEBUG_HANDLES_LOG_FILE,
-        maxBytes: getMaxLogSizeMB() * 1024 * 1024,
-    })
-    : null;
-/** True iff `PI_LENS_DEBUG_HANDLES=1` was set when this module first loaded. */
-export function isDebugHandlesEnabled() {
-    return DEBUG_HANDLES_ENABLED;
-}
-export function getDebugHandlesLogPath() {
-    return DEBUG_HANDLES_LOG_FILE;
-}
-/** Resolve once all enqueued debug-handles writes are on disk (tests). */
-export function flushDebugHandlesLog() {
-    return writer ? writer.flush() : Promise.resolve();
-}
-function safeGetActiveResourcesInfo() {
-    try {
-        // SAFETY: `process.getActiveResourcesInfo` is a real Node API (>=17.3)
-        // that @types/node does not declare on `Process`. The cast only widens
-        // the type to say the method MIGHT be there; the `typeof fn ===
-        // "function"` guard on the next line is what actually decides, so a
-        // runtime without it returns [] rather than throwing.
-        const fn = process.getActiveResourcesInfo;
-        return typeof fn === "function" ? fn.call(process) : [];
-    }
-    catch {
-        return [];
-    }
-}
-/** One representative stack per tracked TYPE (not per resource id) — keeps
- *  each dump line bounded regardless of how many live entries the capped
- *  map currently holds. */
-function summarizeCreationSites(map) {
-    const byType = new Map();
-    for (const { type, stack } of map.values()) {
-        const existing = byType.get(type);
-        if (existing) {
-            existing.count++;
-        }
-        else {
-            byType.set(type, { type, count: 1, sampleStack: stack });
-        }
-    }
-    return [...byType.values()];
-}
-/**
- * Dump `process.getActiveResourcesInfo()` counts-by-type (and, when the
- * tracker was installed at startup, per-type creation-site attribution) to
- * `debug-handles.log`. A pure no-op — no allocation past the flag check —
- * when `PI_LENS_DEBUG_HANDLES` was unset at startup.
- */
-export function dumpActiveHandles(label) {
-    if (!DEBUG_HANDLES_ENABLED || !writer)
-        return;
-    const resources = safeGetActiveResourcesInfo();
-    const counts = {};
-    for (const type of resources) {
-        counts[type] = (counts[type] ?? 0) + 1;
-    }
-    const entry = {
-        ts: new Date().toISOString(),
-        label,
-        total: resources.length,
-        counts,
-    };
-    if (trackedResources) {
-        entry.creationSites = summarizeCreationSites(trackedResources);
-        entry.evictedCount = trackedEvictedCount;
-    }
-    writer.log(entry);
-}
-/** Test-only view of the tracker's current size (bounded-cap assertions). */
-export function _trackedResourceCountForTest() {
-    return trackedResources?.size ?? 0;
-}
-/** Test-only: is `asyncId` still tracked? (protected-vs-evicted assertions). */
-export function _isTrackedForTest(asyncId) {
-    return trackedResources?.has(asyncId) ?? false;
-}
-/** Test-only: synthesize an `init` call against the installed tracker without
- *  depending on real async resource creation timing. No-op when disabled. */
-export function _simulateTrackedInitForTest(asyncId, type) {
-    if (!trackedResources)
-        return;
-    recordTrackedInit(trackedResources, asyncId, type);
-}

package/dist/clients/debug-heap.js

@@ -1,174 +0,0 @@
-/**
- * On-demand V8 heap-snapshot writer — the `PI_LENS_DEBUG_HEAP` sibling that
- * `clients/memory-sampler.ts`'s docstring names as the SEPARATE, explicitly
- * opt-in mechanism for #1126's acceptance criterion ("a heap snapshot of a
- * >1 GB instance identifying the dominant retainers"). The periodic
- * `memory_sample` latency.log line answers "how many bytes are resident right
- * now, broken down by subsystem, over time"; this answers the follow-up
- * question it cannot — "WHICH objects actually retain those bytes" — by writing
- * a `.heapsnapshot` an operator opens in Chrome DevTools › Memory (or clinic /
- * heapdump tooling). It is the retainer-attribution half of #1126's memory
- * observability, deliberately kept out of the always-on sampler because a heap
- * snapshot is expensive (see COST below).
- *
- * `PI_LENS_DEBUG_HEAP=1` (read ONCE at module load, exactly like
- * `debug-handles.ts` — a flag baked in at startup, never toggled mid-session):
- *   - OFF (default): every export below is a no-op that returns immediately on
- *     the flag check. No file is written, no `node:v8` snapshot work happens,
- *     no ndjson writer is constructed — zero cost on any path. The one caller,
- *     the on-demand `/lens-health` diagnostics command, guards on
- *     `isDebugHeapEnabled()` first, so an unset flag costs a single boolean
- *     read. This is NEVER wired to a hot hook, a timer, or a lifecycle event.
- *   - ON: `writeHeapSnapshotNow(label)` calls `v8.writeHeapSnapshot()` to
- *     `~/.pi-lens/heap-<pid>-<iso>.heapsnapshot` and appends ONE ndjson
- *     breadcrumb (path, pid, `rssBytes`, `durationMs`) to `heap-snapshots.log`
- *     via the standard size-bounded `createNdjsonLogger` family (same rotation
- *     bounds every other pi-lens log gets, #1101-era registry). The breadcrumb
- *     lets latency.log's `memory_sample` trajectory and the on-disk snapshot
- *     files cross-reference each other after the fact.
- *
- * COST: `v8.writeHeapSnapshot()` is a SYNCHRONOUS, multi-hundred-MB, multi-
- * second operation that pauses the whole process — which is exactly why it is
- * (a) strictly opt-in behind `PI_LENS_DEBUG_HEAP`, and (b) only ever invoked on
- * explicit operator demand via `/lens-health`, never on an automatic path.
- * Auto-capturing a snapshot when a `memory_sample` crosses an RSS threshold is
- * a DELIBERATELY-DEFERRED follow-up (see #1126) precisely because a threshold
- * trigger would reintroduce that multi-second pause onto an automatic path.
- *
- * Bounded axis (AGENTS.md recurring-defect shape 9 — "a resource bounded on one
- * axis while it grows on another"): the `.heapsnapshot` FILES are the growing
- * axis — each is large, and repeated `/lens-health` invocations accumulate them
- * — and unlike the breadcrumb log they are NOT ndjson-rotated. So every
- * `writeHeapSnapshotNow()` prunes the snapshot directory down to the newest
- * `SNAPSHOT_RETENTION` files after writing. Keeping the NEWEST N (not pinning
- * the earliest, the opposite of `debug-handles.ts`'s creation-site tracker) is
- * the correct policy HERE: an operator triggers each snapshot deliberately to
- * capture the CURRENT grown state of a long-lived instance, so the latest
- * snapshots ARE the evidence — there is no "leak hides among the earliest
- * handles" ordering to protect, as there is for the handle tracer.
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as v8 from "node:v8";
-import { getGlobalPiLensLogDir } from "./probe-home-state.js";
-import { getMaxLogSizeMB } from "./log-cleanup.js";
-import { createNdjsonLogger } from "./ndjson-logger.js";
-/** Read once at module load — see module docstring. Not re-read per call. */
-const DEBUG_HEAP_ENABLED = process.env.PI_LENS_DEBUG_HEAP === "1";
-/** Newest-N `.heapsnapshot` files kept in the pi-lens dir; older ones are
- *  pruned after every write. See the module docstring's shape-9 note for why
- *  newest-kept (not earliest-pinned) is the right retention policy here. */
-export const SNAPSHOT_RETENTION = 3;
-const SNAPSHOT_PREFIX = "heap-";
-const SNAPSHOT_SUFFIX = ".heapsnapshot";
-const HEAP_SNAPSHOT_LOG_FILE = path.join(getGlobalPiLensLogDir(), "heap-snapshots.log");
-// Only ever constructed when the flag is on — the entire cost of this module
-// when unset is the one boolean check at the top of each export below.
-const writer = DEBUG_HEAP_ENABLED
-    ? createNdjsonLogger({
-        filePath: HEAP_SNAPSHOT_LOG_FILE,
-        maxBytes: getMaxLogSizeMB() * 1024 * 1024,
-    })
-    : null;
-/** True iff `PI_LENS_DEBUG_HEAP=1` was set when this module first loaded. */
-export function isDebugHeapEnabled() {
-    return DEBUG_HEAP_ENABLED;
-}
-export function getHeapSnapshotLogPath() {
-    return HEAP_SNAPSHOT_LOG_FILE;
-}
-/** Resolve once all enqueued breadcrumb writes are on disk (tests). */
-export function flushHeapSnapshotLog() {
-    return writer ? writer.flush() : Promise.resolve();
-}
-/**
- * PURE: build a filesystem-safe snapshot filename. The ISO timestamp's `:`/`.`
- * are illegal in Windows paths, so they are folded to `-` (this repo develops
- * on Windows; see AGENTS.md's OS-agnostic rule). Exported for tests.
- */
-export function snapshotFileName(pid, isoTs) {
-    return `${SNAPSHOT_PREFIX}${pid}-${isoTs.replace(/[:.]/g, "-")}${SNAPSHOT_SUFFIX}`;
-}
-/**
- * Prune the snapshot directory to the newest `keep` `.heapsnapshot` files,
- * deleting older ones (bounds the growing on-disk axis — see the module
- * docstring). Best-effort: unreadable dir / unstattable / undeletable files are
- * skipped, never thrown. Returns the paths actually removed (for tests).
- */
-export function pruneOldSnapshots(dir, keep = SNAPSHOT_RETENTION) {
-    let names;
-    try {
-        names = fs.readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
-    const snapshots = names
-        .filter((name) => name.startsWith(SNAPSHOT_PREFIX) && name.endsWith(SNAPSHOT_SUFFIX))
-        .map((name) => {
-        const full = path.join(dir, name);
-        let mtimeMs = 0;
-        try {
-            mtimeMs = fs.statSync(full).mtimeMs;
-        }
-        catch {
-            // unstattable (racing delete): sorts oldest, pruned first
-        }
-        return { full, mtimeMs };
-    })
-        .sort((a, b) => b.mtimeMs - a.mtimeMs); // newest first
-    const removed = [];
-    for (const stale of snapshots.slice(Math.max(0, keep))) {
-        try {
-            fs.rmSync(stale.full, { force: true });
-            removed.push(stale.full);
-        }
-        catch {
-            // best-effort — a failed prune must never break the caller
-        }
-    }
-    return removed;
-}
-/**
- * Write one heap snapshot to `~/.pi-lens/`, append a breadcrumb line, and prune
- * to the newest `SNAPSHOT_RETENTION` files. A pure no-op returning `null` — no
- * file, no allocation past the flag check — when `PI_LENS_DEBUG_HEAP` was unset
- * at startup. `label` records the trigger (currently only `"lens_health"`).
- */
-export function writeHeapSnapshotNow(label) {
-    if (!DEBUG_HEAP_ENABLED)
-        return null;
-    const dir = getGlobalPiLensLogDir();
-    try {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    catch {
-        // dir already exists / unwritable — writeHeapSnapshot will surface it
-    }
-    const ts = new Date().toISOString();
-    const target = path.join(dir, snapshotFileName(process.pid, ts));
-    const rssBytes = process.memoryUsage().rss;
-    const start = Date.now();
-    let written;
-    try {
-        // Returns the filename it actually wrote to.
-        written = v8.writeHeapSnapshot(target);
-    }
-    catch {
-        // A snapshot can fail under memory pressure — the very condition it is
-        // most wanted in. Best-effort: report failure by returning null rather
-        // than throwing into the diagnostics command.
-        return null;
-    }
-    const durationMs = Date.now() - start;
-    pruneOldSnapshots(dir);
-    writer?.log({
-        ts,
-        label,
-        path: written,
-        pid: process.pid,
-        rssBytes,
-        durationMs,
-    });
-    return { path: written, rssBytes, durationMs };
-}