@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/dist/clients/debug-handles.js

@@ -0,0 +1,206 @@
+/**
+ * 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 { getGlobalPiLensDir } from "./file-utils.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(getGlobalPiLensDir(), "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 {
+        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/node_modules/pi-lens/dist/clients/debug-heap.js

@@ -0,0 +1,167 @@
+/**
+ * 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 { getGlobalPiLensDir } from "./file-utils.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(getGlobalPiLensDir(), "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 = getGlobalPiLensDir();
+    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 };
+}

package/node_modules/pi-lens/dist/clients/degradation-ledger.js

@@ -0,0 +1,153 @@
+/** Bounded, process-local telemetry for behavior degraded during one session. */
+import { logExtension } from "./extension-log.js";
+const ENTRIES_PER_KIND = 20;
+const MAX_DISTINCT_KINDS = 32;
+const OVERFLOW_KIND = "other";
+const groups = new Map();
+const onceKeys = new Set();
+const tallies = new Map();
+export function recordDegradation(record) {
+    try {
+        const kind = boundedKind(record.kind);
+        const subject = truncateForLedger(record.subject);
+        const reason = truncateForLedger(record.reason);
+        let group = groups.get(kind);
+        if (!group) {
+            group = { count: 0, entries: [] };
+            groups.set(kind, group);
+        }
+        group.count += 1;
+        // Bounded at RECORD time (#1366 review): reasons carry arbitrary error
+        // text; a 10KB message must never become a 10KB health line or a 10KB
+        // retained string.
+        group.entries.push({ subject, reason });
+        if (group.entries.length > ENTRIES_PER_KIND)
+            group.entries.shift();
+    }
+    catch (error) {
+        debugLedgerFailure("record", error);
+        // Telemetry must never break the observed path.
+    }
+}
+/** Record at most once per kind/subject during the current session. */
+export function recordDegradationOnce(record) {
+    try {
+        const kind = boundedKind(record.kind);
+        const subject = truncateForLedger(record.subject);
+        const key = `${kind}\0${subject}`;
+        if (onceKeys.has(key))
+            return;
+        onceKeys.add(key);
+        recordDegradation({ kind, subject, reason: record.reason });
+    }
+    catch (error) {
+        debugLedgerFailure("record-once", error);
+        // Telemetry must never break the observed path.
+    }
+}
+/**
+ * Count a repeated degradation while retaining one latest-reason entry per
+ * kind/subject. The group count remains the exact event total.
+ */
+export function incrementDegradationCount(record) {
+    try {
+        const kind = boundedKind(record.kind);
+        const subject = truncateForLedger(record.subject);
+        const reason = truncateForLedger(record.reason);
+        const key = `${kind}\0${subject}`;
+        const count = (tallies.get(key) ?? 0) + 1;
+        tallies.set(key, count);
+        let group = groups.get(kind);
+        if (!group) {
+            group = { count: 0, entries: [] };
+            groups.set(kind, group);
+        }
+        group.count += 1;
+        const entry = { subject, reason: truncateForLedger(`${reason} (count: ${count})`) };
+        const existing = group.entries.findIndex((candidate) => candidate.subject === subject);
+        if (existing >= 0)
+            group.entries.splice(existing, 1);
+        group.entries.push(entry);
+        if (group.entries.length > ENTRIES_PER_KIND)
+            group.entries.shift();
+    }
+    catch (error) {
+        debugLedgerFailure("increment", error);
+        // Telemetry must never break the observed path.
+    }
+}
+/** Detached snapshot, grouped in first-seen kind order. */
+const LEDGER_FIELD_MAX = 200;
+function normalizeForLedger(value) {
+    return String(value ?? "unknown");
+}
+function boundedKind(value) {
+    const kind = truncateForLedger(value);
+    if (groups.has(kind) || kind === OVERFLOW_KIND)
+        return kind;
+    // Keep one slot available for all kinds beyond the cardinality bound.
+    return groups.size < MAX_DISTINCT_KINDS - 1 ? kind : OVERFLOW_KIND;
+}
+function truncateForLedger(value) {
+    const text = normalizeForLedger(value);
+    return text.length > LEDGER_FIELD_MAX
+        ? `${text.slice(0, LEDGER_FIELD_MAX)}…`
+        : text;
+}
+export function getDegradationSummary() {
+    return [...groups.entries()].map(([kind, group]) => ({
+        kind,
+        count: group.count,
+        droppedCount: group.count - group.entries.length,
+        latestReasons: group.entries.map((entry) => ({ ...entry })),
+    }));
+}
+function isRenderableSummary(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((group) => {
+        if (group === null || typeof group !== "object")
+            return false;
+        const candidate = group;
+        return (typeof candidate.kind === "string" &&
+            typeof candidate.count === "number" &&
+            Array.isArray(candidate.latestReasons) &&
+            candidate.latestReasons.every((entry) => entry !== null &&
+                typeof entry === "object" &&
+                typeof entry.subject === "string" &&
+                typeof entry.reason === "string"));
+    });
+}
+export function renderDegradationLines(summary = getDegradationSummary()) {
+    if (!isRenderableSummary(summary))
+        return [];
+    if (summary.length === 0)
+        return [];
+    return [
+        "Degradations:",
+        ...summary.map((group) => {
+            const latest = group.latestReasons.at(-1);
+            return `  ⚠ ${group.kind}: ${group.count}${latest ? ` — ${latest.subject}: ${latest.reason}` : ""}`;
+        }),
+    ];
+}
+function debugLedgerFailure(operation, error) {
+    try {
+        logExtension({
+            subsystem: "degradation-ledger",
+            level: "debug",
+            message: `${operation} failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    catch {
+        // Debug logging must not compromise the non-fatal telemetry contract.
+    }
+}
+/** Session-boundary/test reset. */
+export function resetDegradationLedger() {
+    groups.clear();
+    onceKeys.clear();
+    tallies.clear();
+}
+export const DEGRADATION_ENTRIES_PER_KIND = ENTRIES_PER_KIND;
+export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;