@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/pi-lens/dist/clients/child-unref.js

@@ -0,0 +1,85 @@
+/**
+ * Shared plumbing for best-effort, fire-and-forget child-process spawns
+ * (shape 4 of the recurring-defect catalog in AGENTS.md: "a timer / promise /
+ * worker / child that outlives its one-shot settle"). Extracted from the
+ * orphan reaper's `unrefReaperChild`/`spawnCollectStdout` (#1153/#1160) into a
+ * shared, dependency-free module so every one-shot
+ * `spawn(..., { stdio: ["ignore","pipe",...] })` call site in the codebase —
+ * the reaper's enumeration/kill spawns AND the resource sampler's Windows
+ * CIM/powershell spawns (#1155) — uses the exact same unref+collect shape
+ * instead of re-deriving it (also closes the #1155 PR's SonarCloud
+ * new-code-duplication finding: two near-identical spawn→collect-stdout
+ * blocks in `clients/resource-sampler.ts` collapsed to one shared helper).
+ *
+ * Deliberately has NO imports beyond `node:child_process` types, so both
+ * `clients/instance-reaper.ts` and `clients/resource-sampler.ts` (which
+ * `clients/safe-spawn.ts` itself depends on) can import this without risking
+ * a circular-import chain.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+/**
+ * Detach a best-effort, fire-and-forget child process from the event loop.
+ *
+ * A piped, `data`-listener-attached stdout/stderr/stdin stream keeps the libuv
+ * loop REFERENCED even after `child.unref()` — the child handle and every
+ * live stdio stream must all be unref'd, or a settled one-shot process (e.g.
+ * `pi --print`) cannot exit until the child `close`s. Unref only means "do
+ * not keep the process alive FOR this best-effort work": in an interactive/
+ * long-lived session the loop stays referenced for other reasons, so the
+ * child's `data`/`close` events still fire normally and callers still collect
+ * output/usage; only a genuinely-settled one-shot is allowed to exit without
+ * waiting for it. Never throws.
+ */
+export function unrefChildAndPipes(child) {
+    try {
+        child.unref();
+        // Child stdio pipes are `net.Socket`s at runtime (which expose `unref`),
+        // but are typed as `Readable`/`Writable` (which do not) — cast to the
+        // optional-`unref` shape and guard, so an un-piped ("ignore") stream is a
+        // no-op rather than a crash.
+        for (const stream of [child.stdout, child.stderr, child.stdin]) {
+            stream?.unref?.();
+        }
+    }
+    catch {
+        // best-effort — unref must never throw out of a fire-and-forget spawn
+    }
+}
+/**
+ * Spawn a best-effort, fire-and-forget child, accumulate its full stdout, and
+ * resolve with the collected text (empty string on a synchronous spawn
+ * failure or an `error` event). Consolidates the spawn → unref →
+ * pipe-stdout → `close` plumbing shared by every one-shot OS-process-table
+ * query in the codebase — each caller supplies only its command/args/options
+ * and does its own output parse. The child + its stdio pipes are `unref`'d
+ * here (via `unrefChildAndPipes`) so a settled one-shot `pi --print` process
+ * can exit without waiting, and both the unref and the collect plumbing live
+ * in exactly ONE place rather than being re-derived at each spawn site.
+ * Never rejects — any failure resolves to `""`, which every caller's parse
+ * turns into an empty/absent result (the best-effort contract every caller
+ * here already has).
+ */
+export function spawnCollectStdout(command, args, options) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        try {
+            const child = nodeSpawn(command, args, options);
+            unrefChildAndPipes(child);
+            let out = "";
+            child.stdout?.on("data", (chunk) => {
+                out += chunk.toString();
+            });
+            child.once("error", () => settle(""));
+            child.once("close", () => settle(out));
+        }
+        catch {
+            settle("");
+        }
+    });
+}

package/node_modules/pi-lens/dist/clients/codebase-model.js

@@ -13,18 +13,25 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
+import { writeFileAtomic } from "./atomic-write.js";
+import { parseSymbolKey } from "./call-graph.js";
+import { detectFileRole } from "./file-role.js";
+import { isExternalOrVendorFile } from "./path-utils.js";
+import { isBuildArtifact } from "./source-filter.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
-const DEFAULT_TOKEN_BUDGET = 1500;
+export const DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET = 1500;
 const MAX_CALLS_PER_SYMBOL = 10;
 const MIN_IN_DEGREE = 0.5; // skip symbols with low centrality (avoids noise)
+/** Persisted model schema version. Bump when the persisted shape changes. */
+export const CODEBASE_MODEL_VERSION = 1;
 // ── Builder ───────────────────────────────────────────────────────────────────
 function inferKind(symbolKey) {
-    const name = symbolKey.split(":").pop() ?? "";
-    if (/^[A-Z]/.test(name))
+    const parsed = parseSymbolKey(symbolKey);
+    if (parsed.kind === "class")
         return "class";
-    if (name.includes("."))
+    if (parsed.kind === "method" || parsed.symbolName?.includes("."))
         return "method";
-    return "function";
+    return /^[A-Z]/.test(parsed.symbolName ?? "") ? "class" : "function";
 }
 function estimateTokens(entry) {
     const text = [
@@ -45,7 +52,15 @@ function estimateTokens(entry) {
  * @param cwd     Project root — used to compute relative file paths.
  * @param budget  Maximum total token budget (default 1500).
  */
-export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
+export function buildCodebaseModel(graph, cwd, budget = DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET, identity) {
+    // Standalone callers may build an unpersisted projection without the
+    // review-graph coordinator. Persisted/session models pass the canonical
+    // review-graph identity explicitly; this fallback is only a local call-graph
+    // identity for builder-only use.
+    const modelIdentity = identity ?? {
+        reviewGraphVersion: graph.builtAt || "call-graph-unknown",
+        reviewGraphSignature: graph.builtAt || "call-graph-unknown",
+    };
     // Sort all callee keys by in-degree descending
     const ranked = [...graph.inDegree.entries()]
         .filter(([, score]) => score >= MIN_IN_DEGREE)
@@ -56,16 +71,16 @@ export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
     for (const [calleeKey, inDegree] of ranked) {
         if (totalTokens >= budget)
             break;
-        const parts = calleeKey.split(":");
-        const name = parts.pop() ?? calleeKey;
-        const filePath = parts.join(":");
-        // Skip if file is in test/node_modules/generated directories
-        if (filePath.includes("node_modules") ||
-            filePath.includes(".test.") ||
-            filePath.includes(".spec.") ||
-            filePath.includes("/__tests__/") ||
-            filePath.includes("/dist/") ||
-            filePath.includes("/generated/")) {
+        const parsedCallee = parseSymbolKey(calleeKey);
+        const name = parsedCallee.symbolName ?? calleeKey;
+        const filePath = parsedCallee.filePath;
+        // Keep this projection aligned with the shared file-role policy. The
+        // call graph is derived from the canonical review graph, so the model
+        // carries that graph's identity rather than inventing a second freshness
+        // policy.
+        const fileRole = detectFileRole(filePath);
+        if (fileRole === "test" || fileRole === "generated" ||
+            isExternalOrVendorFile(filePath, cwd) || isBuildArtifact(filePath)) {
             continue;
         }
         // Deduplicate by name when the same function appears in multiple files
@@ -73,11 +88,11 @@ export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
             continue;
         seenNames.add(name);
         const calls = [...(graph.callees.get(calleeKey) ?? new Set())]
-            .map((k) => k.split(":").pop() ?? k)
+            .map((k) => parseSymbolKey(k).symbolName ?? k)
             .filter(Boolean)
             .slice(0, MAX_CALLS_PER_SYMBOL);
         const calledBy = [...(graph.callers.get(calleeKey) ?? new Set())]
-            .map((k) => k.split(":").pop() ?? k)
+            .map((k) => parseSymbolKey(k).symbolName ?? k)
             .filter((n) => !n.startsWith("file:"))
             .slice(0, MAX_CALLS_PER_SYMBOL);
         const file = filePath
@@ -98,9 +113,12 @@ export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
         totalTokens += tokens;
     }
     const allFiles = new Set([...graph.callers.keys(), ...graph.callees.keys()]
-        .map((k) => k.split(":").slice(0, -1).join(":"))
+        .map((k) => parseSymbolKey(k).filePath)
         .filter(Boolean));
     return {
+        version: CODEBASE_MODEL_VERSION,
+        reviewGraphVersion: modelIdentity.reviewGraphVersion,
+        reviewGraphSignature: modelIdentity.reviewGraphSignature,
         generatedAt: new Date().toISOString(),
         totalSymbols: graph.inDegree.size,
         totalFiles: allFiles.size,
@@ -119,16 +137,27 @@ export function saveCodebaseModel(cwd, model) {
     const cacheFile = cacheFilePath(cwd);
     try {
         fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
-        fs.writeFileSync(cacheFile, JSON.stringify(model), "utf-8");
-        fs.writeFileSync(metaFilePath(cwd), JSON.stringify({ savedAt: new Date().toISOString(), entryCount: model.entries.length, totalTokens: model.totalTokens }), "utf-8");
+        writeFileAtomic(cacheFile, JSON.stringify(model));
+        writeFileAtomic(metaFilePath(cwd), JSON.stringify({ savedAt: new Date().toISOString(), entryCount: model.entries.length, totalTokens: model.totalTokens }));
     }
     catch {
         // Non-fatal — next session rebuilds.
     }
 }
-export function loadCodebaseModel(cwd) {
+/** Load only a model matching the canonical identity it was derived from. */
+export function loadCodebaseModel(cwd, expectedIdentity) {
     try {
-        return JSON.parse(fs.readFileSync(cacheFilePath(cwd), "utf-8"));
+        const raw = JSON.parse(fs.readFileSync(cacheFilePath(cwd), "utf-8"));
+        if (raw.version !== CODEBASE_MODEL_VERSION ||
+            typeof raw.reviewGraphVersion !== "string" || raw.reviewGraphVersion.length === 0 ||
+            typeof raw.reviewGraphSignature !== "string" || raw.reviewGraphSignature.length === 0 ||
+            typeof raw.generatedAt !== "string" ||
+            !Array.isArray(raw.entries))
+            return undefined;
+        if (raw.reviewGraphVersion !== expectedIdentity.reviewGraphVersion ||
+            raw.reviewGraphSignature !== expectedIdentity.reviewGraphSignature)
+            return undefined;
+        return raw;
     }
     catch {
         return undefined;

package/node_modules/pi-lens/dist/clients/collateral-test-role.js

@@ -0,0 +1,40 @@
+/**
+ * Shared test-role predicate for COLLATERAL cascade/impact surfaces (#1080).
+ *
+ * The review graph is already tests-free (`review-graph/builder.ts` applies
+ * `detectFileRole(file) !== "test"` at its walk/incremental chokepoints), but
+ * several collateral surfaces re-derive neighbors from OTHER sources that never
+ * saw that filter — LSP reference expansion, module-level downstream expansion,
+ * the reverse-dependency index, and the passive-diagnostics fallback — so an
+ * unignored `*.test.*` / `tests/` file can still leak into cascade neighbor
+ * output, the formatted impact header/counts, the turn-end call-graph advisory,
+ * and the persisted call-graph-impact diagnostics.
+ *
+ * This composes the SINGLE existing structural classifier (`detectFileRole`) —
+ * no second matcher, no private test-filename list, no duplicated patterns. The
+ * project ignore matcher (`getProjectIgnoreMatcher`) is applied separately and
+ * unchanged at each surface; this predicate only adds the test-ROLE half of the
+ * display policy the review graph already enforces.
+ *
+ * Honesty (#1080 acceptance criteria):
+ *  - A KNOWN `"test"` role is filtered from the collateral surface.
+ *  - If role classification cannot be obtained (an unexpected throw), the
+ *    candidate is RETAINED (`false`) rather than dropped — filtering must never
+ *    invent a heuristic or silently drop a potentially actionable file, and must
+ *    never convert an incomplete/indeterminate computation into a clean result.
+ */
+import { detectFileRole } from "./file-role.js";
+/**
+ * True when `filePath` is a KNOWN test-role file that must not surface as a
+ * collateral cascade/impact neighbor. Path-based only (no content needed for
+ * the test-role branch of `detectFileRole`). Fail-open: any classifier error
+ * returns `false` (retain the candidate).
+ */
+export function isTestRoleCollateral(filePath) {
+    try {
+        return detectFileRole(filePath) === "test";
+    }
+    catch {
+        return false;
+    }
+}

package/node_modules/pi-lens/dist/clients/complexity-client.js

@@ -10,6 +10,7 @@
  * maintainability index (Halstead-free), LOC/comments, code entropy, and AI-slop
  * indicators. These are silent metrics surfaced in the session summary.
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { firstChildOfType, withTreeSitterRoot, resolveTreeSitterLanguage, walk, } from "./tree-sitter-shared.js";
@@ -371,7 +372,7 @@ export class ComplexityClient {
     log;
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[complexity] ${msg}`)
+            ? createSubsystemLogger("complexity")
             : () => { };
     }
     /** True if the file's grammar has a complexity node mapping. */

package/node_modules/pi-lens/dist/clients/console-guard-install.js

@@ -0,0 +1,14 @@
+import { performance } from "node:perf_hooks";
+// Capture this before the guard's other module initialization so host boot is
+// not charged to extension evaluation (#1374).
+export const PI_LENS_EVAL_STARTED_MS = performance.now();
+// #1333: install the console guard as an import side-effect so it runs before
+// any other module's initialization code. Installing inside the extension
+// factory is too late — by the time the factory runs, every static/transitive
+// import has already evaluated, so a dependency writing to console during
+// module init would still hit the TUI raw (#1338 review finding). This module
+// MUST remain the first import of index.ts; the enforcement test pins that.
+// installConsoleGuard() itself is idempotent and no-ops under test mode and
+// PI_LENS_CONSOLE_GUARD=0.
+import { installConsoleGuard } from "./extension-log.js";
+installConsoleGuard();

package/node_modules/pi-lens/dist/clients/cooperative-budget.js

@@ -0,0 +1,42 @@
+/** Monotonic cooperative-work budgeting for event-loop-sensitive bulk work. */
+export function createDeadline(budgetMs) {
+    const boundedBudget = Math.max(0, budgetMs);
+    let startedAt = performance.now();
+    return {
+        expired: () => performance.now() - startedAt >= boundedBudget,
+        reset: () => {
+            startedAt = performance.now();
+        },
+    };
+}
+export async function yieldIfOverBudget(deadline) {
+    if (!deadline.expired())
+        return false;
+    await new Promise((resolve) => setImmediate(resolve));
+    deadline.reset();
+    return true;
+}
+export async function forEachCooperatively(items, fn, options) {
+    const deadline = createDeadline(options.budgetMs);
+    const assertContinuing = () => {
+        if (options.shouldContinue?.() === false) {
+            throw new Error(options.abortMessage ?? "cooperative work superseded");
+        }
+    };
+    let index = 0;
+    for (const item of items) {
+        // Check before each unit: this per-unit check is what bounds abort
+        // latency (one work unit, not an iteration checkpoint). The post-yield
+        // check below only matters after the final unit's yield, so superseded
+        // work is reported aborted rather than completed.
+        assertContinuing();
+        const result = fn(item, index++);
+        if (result !== undefined &&
+            typeof result.then === "function") {
+            await result;
+        }
+        if (deadline.expired() && (await yieldIfOverBudget(deadline))) {
+            assertContinuing();
+        }
+    }
+}

package/node_modules/pi-lens/dist/clients/dead-code-client.js

@@ -11,6 +11,7 @@
  * Phase 1 ships Python via `vulture`. Future phases add Go/Rust/etc. by
  * implementing DeadCodeClient and adding to getDeadCodeClients().
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as path from "node:path";
 import { findNearestMarkerRoot } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
@@ -92,7 +93,7 @@ export class PythonDeadCodeClient {
     log;
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[dead-code:python] ${msg}`)
+            ? createSubsystemLogger("dead-code:python")
             : () => { };
     }
     get minConfidence() {

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);
+}