@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/test-runner-client.js

@@ -13,6 +13,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { BoundedFifoMap } from "./bounded-cache.js";
 import { emitBounded } from "./bounded-telemetry.js";
 import { LEDGER_FIELD_MAX } from "./degradation-ledger.js";
 import { minimatch } from "./deps/minimatch.js";
@@ -20,9 +21,46 @@ import { createSubsystemLogger } from "./extension-log.js";
 import { detectFileRole } from "./file-role.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { PathKeyedMap } from "./path-keyed-map.js";
-import { normalizeEphemeralMapKey, normalizeMapKey } from "./path-utils.js";
+import { augmentPythonEnvironment, detectPythonEnvironment, } from "./python-environment.js";
+import { normalizeEphemeralMapKey, normalizeMapKey, toPosix, } from "./path-utils.js";
 import { isMeasuredDuration, toMeasuredDurationMs } from "./run-duration.js";
 import { safeSpawn, safeSpawnAsync } from "./safe-spawn.js";
+import { stripAnsi } from "./sanitize.js";
+/**
+ * #2532: the ONE classification seam for "this `TestResult` carries NO
+ * counted failure the agent needs to fix, even though the runner also
+ * reported an `error`" — i.e. `failed === 0 && !!error`. This is NOT "the
+ * suite never started": a runner can report BOTH counted failures and an
+ * error (pytest exit 2 "Interrupted" after `2 failed, 1 passed` already
+ * printed — `parsePytestOutput` sets `error` from the exit code
+ * independently of the parsed counts, review round 1 S2). The rule is
+ * exactly `failed === 0`, nothing about `error`'s presence or cause: a
+ * result with counted failures stays blocking even when `error` is also
+ * set (`testResultToProjectDiagnostics`/`formatResult` still mention the
+ * error in that case, they just don't let it downgrade the verdict).
+ *
+ * `hasRealFailure`/`runnerErrorOnly` (`runtime-turn.ts`, #2522) key off the
+ * exact same fact for the turn-end delivery framing — a batch made
+ * entirely of `isRunnerErrorResult` results is advisory, one containing
+ * even one counted failure keeps "fix before continuing". Three more
+ * surfaces route through this SAME predicate instead of re-deriving it
+ * (review round 1 S1's class sweep), so the identical `TestResult` cannot
+ * classify differently across them: `testResultToProjectDiagnostics`
+ * (`lens_diagnostics mode=full`), the `--lens-guard` merge call in
+ * `handleTurnEnd`, and `TestRunnerClient.formatResult`/the turn-end dbg
+ * summary (both in this file / `runtime-turn.ts`).
+ *
+ * Two call sites intentionally test the COMPLEMENT (a truly clean result,
+ * no counted failure AND no error) rather than this predicate, and are not
+ * a missed fourth spelling: `runtime-turn.ts`'s `cleanFiles` filter
+ * (`--lens-guard`'s clear-blocker list) and `testResultToProjectDiagnostics`'s
+ * own early "nothing to report" return. Both need "genuinely clean", which
+ * `!isRunnerErrorResult(result)` cannot express (it is also true for a
+ * counted failure).
+ */
+export function isRunnerErrorResult(result) {
+    return result.failed === 0 && !!result.error;
+}
 // Source file → test file patterns (reverse lookup)
 const SOURCE_TO_TEST_PATTERNS = [
     {
@@ -70,6 +108,57 @@ const MAX_NODE_MODULES_WALK_UP = 5;
 // test type rather than mirroring source layout) — capped depth, never an
 // unbounded walk of the whole tests tree.
 const MAX_PYTEST_RECURSE_DEPTH = 3;
+/**
+ * #2522: built-in exclusion list for the turn-end auto-fired test selection.
+ *
+ * `getTestRunTarget`'s three strategies (failed-first / related / self) will
+ * happily resolve to ANY test file on disk, including integration/e2e suites
+ * that spawn external processes. A plegma dogfooding turn resolved
+ * `tests/integration/opencode-delegate.test.ts` this way — it spawns
+ * `opencode` and needs a configured provider, so on a box without one it took
+ * 17s to fail and was reported to the agent as "3/3 failed, fix before
+ * proceeding" on an unrelated model-switch turn (#2522, refs #2504/#2509).
+ *
+ * One hard-coded list, no per-project config knob (maintainer decision
+ * 2026-09-03) — this is a safety bound on what turn_end may auto-fire, not a
+ * project preference. Documented in AGENTS.md and docs/. Matched against the
+ * resolved test file's project-relative, POSIX-folded path so it applies
+ * uniformly to whichever strategy produced the target.
+ */
+export const TURN_END_EXCLUDED_TEST_GLOBS = [
+    "**/integration/**",
+    "**/e2e/**",
+    "**/*.integration.*",
+    "**/*.e2e.*",
+];
+/**
+ * Whether a resolved test target falls under the built-in turn-end
+ * exclusion list (#2522). `testFilePath` may be absolute or relative, and
+ * may use either path-separator form — folded through `toPosix` after being
+ * made cwd-relative so `\`- and `/`-separated inputs match identically
+ * (AGENTS.md cross-form-path screen).
+ */
+export function isExcludedTestTarget(testFilePath, cwd) {
+    const rel = toPosix(path.relative(cwd, path.resolve(cwd, testFilePath)));
+    // #2522 review round 2, F6: a target that resolves OUTSIDE the project root
+    // yields a `..`-leading relative path (or, across Windows drives, a still
+    // absolute one), which matches none of the globs — so the bare `some()`
+    // below reported it as "not excluded" and turn_end would have auto-spawned a
+    // runner against a file outside the project the turn is running in. An
+    // out-of-tree target, and the project root itself, fail CLOSED.
+    if (rel === "" ||
+        rel === ".." ||
+        rel.startsWith("../") ||
+        path.isAbsolute(rel))
+        return true;
+    // #2522 review round 2, F5: case-INSENSITIVE. `tests/Integration/`,
+    // `tests/E2E/` and `foo.E2E.test.ts` are the same hazard as their lowercase
+    // spellings, and on the case-insensitive filesystems Windows and macOS ship
+    // by default they are literally the same files — so a case-sensitive match
+    // made the SAME repo excluded on one box and unbounded on another. A safety
+    // bound a capital letter defeats is not a bound.
+    return TURN_END_EXCLUDED_TEST_GLOBS.some((glob) => minimatch(rel, glob, { dot: true, nocase: true }));
+}
 // --- Runner Detection ---
 export const RUNNERS = {
     vitest: {
@@ -223,7 +312,7 @@ function canonicalProjectRoot(cwd) {
         return { key: normalizeEphemeralMapKey(absolute), resolved: false };
     }
 }
-const MAX_CANONICAL_ROOT_MEMO_ENTRIES = 512;
+export const MAX_CANONICAL_ROOT_MEMO_ENTRIES = 512;
 function filesystemErrorCode(error) {
     if (error !== null &&
         typeof error === "object" &&
@@ -233,6 +322,50 @@ function filesystemErrorCode(error) {
     }
     return undefined;
 }
+const PYTEST_SUMMARY_OUTCOME = "(?:passed|failed|skipped|reruns?|errors?|warnings?|deselected|xfailed|xpassed)";
+const PYTEST_SUMMARY_LINE = new RegExp(`^\\s*(?:=+\\s*)?\\d+\\s+${PYTEST_SUMMARY_OUTCOME}` +
+    `(?:\\s*,\\s*\\d+\\s+${PYTEST_SUMMARY_OUTCOME})*` +
+    `\\s+in\\s+[\\d.]+s(?:\\s*=+)?\\s*$`, "i");
+/** Extract aggregate values from pytest's final outcome line only. */
+function parsePytestSummary(output) {
+    // Pytest may color the whole summary or individual tokens. Strip ANSI before
+    // selecting and extracting so formatting cannot turn the first count into 0.
+    const normalizedOutput = stripAnsi(output);
+    const summaryLine = normalizedOutput
+        .split(/\r?\n/)
+        .reverse()
+        .find((line) => PYTEST_SUMMARY_LINE.test(line));
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    if (!summaryLine)
+        return { passed, failed, skipped };
+    const summaryBody = summaryLine.replace(/^=+\s*|\s*=+\s*$/g, "");
+    for (const field of summaryBody.split(",")) {
+        const [countText, outcome] = field.trim().split(/\s+/, 2);
+        const count = Number.parseInt(countText, 10);
+        if (!Number.isFinite(count))
+            continue;
+        switch (outcome) {
+            case "passed":
+                passed = count;
+                break;
+            case "failed":
+                failed = count;
+                break;
+            case "skipped":
+                skipped = count;
+                break;
+        }
+    }
+    const durationMatch = /in\s+([\d.]+)s/.exec(summaryLine);
+    // Rounded, like `jsonRunDurationMs` and PHPUnit's legacy path:
+    // `in 2.01s` is 2009.9999999999998 in binary floating point.
+    const duration = durationMatch
+        ? Math.round(Number.parseFloat(durationMatch[1]) * 1000)
+        : undefined;
+    return { passed, failed, skipped, duration };
+}
 export class TestRunnerClient {
     log;
     // This is an instance-lifetime memo of RESOLVED spellings only, which leaves
@@ -247,7 +380,7 @@ export class TestRunnerClient {
     // resolve — a state where `detectRunner` already walks node_modules on every
     // call. Keep the memo bounded so pathological spelling churn cannot grow it
     // without limit.
-    canonicalRootMemo = new Map();
+    canonicalRootMemo = new BoundedFifoMap(MAX_CANONICAL_ROOT_MEMO_ENTRIES);
     availableRunners = new PathKeyedMap(normalizeEphemeralMapKey);
     failedTestsByRunner = new Map();
     failedTargetSequence = 0;
@@ -271,14 +404,13 @@ export class TestRunnerClient {
         const { key, resolved } = canonicalProjectRoot(cwd);
         if (!resolved)
             return key;
-        if (this.canonicalRootMemo.size >= MAX_CANONICAL_ROOT_MEMO_ENTRIES) {
-            const oldest = this.canonicalRootMemo.keys().next().value;
-            if (oldest !== undefined)
-                this.canonicalRootMemo.delete(oldest);
-        }
         this.canonicalRootMemo.set(cwd, key);
         return key;
     }
+    /** #2442 test-only: exercise canonicalRootMemo's bounded eviction directly. */
+    _getCanonicalProjectRootForTests(cwd) {
+        return this.getCanonicalProjectRoot(cwd);
+    }
     getRunnerAvailability(byRunner, runner) {
         const cached = byRunner?.get(runner);
         if (!cached)
@@ -904,16 +1036,20 @@ export class TestRunnerClient {
         else {
             request = runnerOrRequest;
         }
-        const { runner, config, turnIndex } = request;
+        const { runner, config, turnIndex, signal } = request;
         if (!fs.existsSync(absoluteTestFile)) {
             return this.emptyResult(absoluteTestFile, "", runner, "Test file not found");
         }
         try {
-            const { command, args } = await this.resolveExec(runner, config, absoluteTestFile, cwd);
+            const { command, args, env } = await this.resolveExec(runner, config, absoluteTestFile, cwd);
             this.log(`Running (async): ${command} ${args.join(" ")}`);
             const result = await safeSpawnAsync(command, args, {
                 cwd,
                 timeout: 60000,
+                env,
+                // #2522 R2 F1. `safeSpawnAsync` resolves `options.signal ?? ambient`,
+                // so an absent batch signal keeps the pre-#2522 ambient behaviour.
+                signal,
             });
             const stdout = result.stdout || "";
             const stderr = result.stderr || "";
@@ -1273,31 +1409,9 @@ export class TestRunnerClient {
     parsePytestOutput(stdout, stderr, exitCode, testFile, _cwd, runner) {
         const failures = [];
         const output = `${stdout}\n${stderr}`;
-        // Parse summary line: "5 passed, 2 failed, 1 skipped in 0.23s"
-        const summaryMatch = output.match(/(\d+)\s+passed?.*?(\d+)\s+failed.*?in\s+([\d.]+)s/i) ||
-            output.match(/(\d+)\s+passed.*?in\s+([\d.]+)s/i);
-        let passed = 0;
-        let failed = 0;
-        let skipped = 0;
-        // #1479: undefined until pytest's own `in N.NNs` is read. `in 0.00s` is
-        // a real pytest summary, so 0 has to stay available as a measurement.
-        let duration;
-        if (summaryMatch) {
-            // Extract numbers from various patterns
-            const passedMatch = output.match(/(\d+)\s+passed/);
-            const failedMatch = output.match(/(\d+)\s+failed/);
-            const skippedMatch = output.match(/(\d+)\s+skipped/);
-            const durationMatch = output.match(/in\s+([\d.]+)s/);
-            passed = passedMatch ? parseInt(passedMatch[1], 10) : 0;
-            failed = failedMatch ? parseInt(failedMatch[1], 10) : 0;
-            skipped = skippedMatch ? parseInt(skippedMatch[1], 10) : 0;
-            // Rounded, like `jsonRunDurationMs` and PHPUnit's legacy path:
-            // `in 2.01s` is 2009.9999999999998 in binary floating point, and
-            // the turn-end log prints the number as it stands.
-            // (Routing this through `toMeasuredDurationMs` is #1484, not this.)
-            if (durationMatch)
-                duration = Math.round(parseFloat(durationMatch[1]) * 1000);
-        }
+        // #1479: `duration` stays undefined unless pytest emits its own `in N.NNs`
+        // summary. A measured `in 0.00s` remains a real zero.
+        const { passed, failed, skipped, duration } = parsePytestSummary(output);
         // Parse individual failures: "FAILED tests/test_foo.py::test_something - AssertionError: ..."
         const failureRegex = /FAILED\s+(\S+::\S+)\s*-\s*(.+?)(?:\n|$)/g;
         let match;
@@ -1325,7 +1439,11 @@ export class TestRunnerClient {
             skipped,
             failures,
             duration,
-            error: exitCode === 2 ? "Pytest configuration error" : undefined,
+            error: exitCode === 4
+                ? "Pytest configuration error"
+                : exitCode === 2
+                    ? "Pytest interrupted"
+                    : undefined,
         };
     }
     // --- PHPUnit Parser (text-based, default CLI output) ---
@@ -1961,9 +2079,15 @@ export class TestRunnerClient {
      * Format test result for LLM consumption
      */
     formatResult(result) {
-        if (result.error && result.passed === 0 && result.failed === 0) {
-            // Runner error, not test failure
-            return `[Tests] ⚠ Could not run tests: ${result.error}`;
+        // #2532 review S1: folded onto `isRunnerErrorResult` instead of the old
+        // local `error && passed === 0 && failed === 0` spelling — that missed a
+        // runner error reported alongside partial passes (pytest `Interrupted`
+        // after some tests already ran clean), which fell through to the normal
+        // "N/N passed" branch below and silently dropped the interruption.
+        if (isRunnerErrorResult(result)) {
+            return result.passed > 0
+                ? `[Tests] ⚠ Could not complete tests: ${result.error} (${result.passed} passed before)`
+                : `[Tests] ⚠ Could not run tests: ${result.error}`;
         }
         const total = result.passed + result.failed + result.skipped;
         if (total === 0) {
@@ -2094,6 +2218,19 @@ export class TestRunnerClient {
      * runners like vitest/jest/pytest).
      */
     async resolveExec(runner, config, testFile, cwd) {
+        // Run pytest through the project interpreter itself, not a generic `python`
+        // resolved from the host PATH. The child-only environment also keeps tools
+        // spawned by tests inside the same project environment.
+        if (runner === "pytest") {
+            const pythonEnvironment = await detectPythonEnvironment(cwd);
+            if (pythonEnvironment) {
+                return {
+                    command: pythonEnvironment.pythonPath,
+                    args: config.args(testFile, cwd),
+                    env: augmentPythonEnvironment(process.env, pythonEnvironment),
+                };
+            }
+        }
         // PHPUnit has no npx-style automatic local-binary resolution — Composer's
         // standard local-install location is vendor/bin/phpunit, so check that
         // explicitly before falling back to a global `phpunit` on PATH.

package/node_modules/pi-lens/dist/clients/test-runner-delivery.js

@@ -0,0 +1,239 @@
+/**
+ * Automatic test-runner delivery for the post-agent idle window (#2366).
+ *
+ * Test results remain in `test-runner-findings` for pull diagnostics and the
+ * commit guard. This module only stages an owner-qualified pointer and
+ * appends a non-context custom entry after the host proves that the agent is
+ * idle. Provenance validation stays in `peekTestFindings`, the one shared
+ * delivery gate for this cache.
+ */
+import { emitBounded } from "./bounded-telemetry.js";
+import { peekTestFindings } from "./runtime-context.js";
+import { fitLines } from "./tui-fit.js";
+export const TEST_RUNNER_ENTRY_TYPE = "pilens:test-runner-findings";
+const MAX_PENDING_DELIVERIES = 32;
+const MAX_ENTRY_CONTENT = 12_000;
+const pending = new Map();
+function key(cwd, sessionId, ownerId) {
+    // `cwd` comes from the same host session field at turn_end and settle. Keep
+    // that canonical value unchanged so cache reads use the identical workspace
+    // identity; dispatch contexts already normalize their own path fields.
+    return `${ownerId ?? "direct"}\u0000${cwd}\u0000${sessionId}`;
+}
+function boundedContent(content) {
+    if (content.length <= MAX_ENTRY_CONTENT)
+        return { content, droppedDetailCount: 0 };
+    return {
+        content: `${content.slice(0, MAX_ENTRY_CONTENT)}\n[…details truncated]`,
+        droppedDetailCount: content.length - MAX_ENTRY_CONTENT,
+    };
+}
+function record(identity, outcome, delivery, metadata = {}) {
+    emitBounded("test_runner_delivery", identity, {
+        filePath: delivery.cwd,
+        durationMs: 0,
+        metadata: {
+            outcome,
+            sessionId: delivery.sessionId,
+            generation: delivery.generation,
+            targetCount: delivery.targetCount,
+            deliveryBoundary: "agent_settled",
+            ownership: "pi",
+            droppedDetailCount: 0,
+            ...metadata,
+        },
+    }, {
+        capPerTurn: { limit: 8, turnIndex: delivery.generation },
+        ledgerKind: outcome === "delivery-failed" || outcome === "capability-unavailable"
+            ? "test-runner-delivery"
+            : undefined,
+        reason: `test runner delivery ${outcome}`,
+    });
+}
+function prunePending() {
+    while (pending.size > MAX_PENDING_DELIVERIES) {
+        const oldest = pending.keys().next();
+        if (oldest.done)
+            return;
+        pending.delete(oldest.value);
+    }
+}
+/** Stage the newest result for this session. Clean results supersede failures. */
+export function stageTestRunnerDelivery(args) {
+    const deliveryKey = key(args.cwd, args.sessionId, args.owner?.ownerId);
+    const prior = pending.get(deliveryKey);
+    if (prior && prior.generation > args.generation) {
+        const superseded = {
+            cwd: args.cwd,
+            sessionId: args.sessionId,
+            ownerId: args.owner?.ownerId,
+            generation: args.generation,
+            targetCount: args.targetCount,
+            createdAt: Date.now(),
+            owner: args.owner,
+        };
+        record(deliveryKey, "superseded", superseded, {
+            currentGeneration: prior.generation,
+        });
+        return;
+    }
+    if (!args.hasFindings) {
+        if (prior) {
+            pending.delete(deliveryKey);
+            record(deliveryKey, "superseded", {
+                ...prior,
+                targetCount: args.targetCount,
+                generation: args.generation,
+            });
+        }
+        return;
+    }
+    const delivery = {
+        cwd: args.cwd,
+        sessionId: args.sessionId,
+        ownerId: args.owner?.ownerId,
+        generation: args.generation,
+        targetCount: args.targetCount,
+        createdAt: Date.now(),
+        owner: args.owner,
+    };
+    pending.set(deliveryKey, delivery);
+    prunePending();
+    record(deliveryKey, "staged", delivery);
+}
+/** Deliver the latest staged result during a host-confirmed idle window. */
+export function deliverTestRunnerFindings(args) {
+    const cwd = args.ctx.cwd ?? process.cwd();
+    const deliveryKey = key(cwd, args.sessionId, args.ownerId);
+    const delivery = pending.get(deliveryKey);
+    if (!delivery)
+        return;
+    const currentGeneration = args.cacheManager.readCache("test-runner-findings", cwd)?.data?.testRunGeneration;
+    if (currentGeneration !== undefined &&
+        currentGeneration > delivery.generation) {
+        pending.delete(deliveryKey);
+        record(deliveryKey, "superseded", delivery, {
+            currentGeneration,
+        });
+        return;
+    }
+    if (typeof args.ctx.isIdle !== "function") {
+        pending.delete(deliveryKey);
+        record(deliveryKey, "capability-unavailable", delivery, {
+            reason: "host does not expose ctx.isIdle",
+        });
+        return;
+    }
+    try {
+        if (!args.ctx.isIdle()) {
+            record(deliveryKey, "carried", delivery);
+            return;
+        }
+    }
+    catch (error) {
+        record(deliveryKey, "delivery-failed", delivery, {
+            error: String(error).slice(0, 500),
+        });
+        return;
+    }
+    const findings = peekTestFindings(args.cacheManager, cwd, args.runtime, true);
+    if (!findings) {
+        pending.delete(deliveryKey);
+        record(deliveryKey, "superseded", delivery);
+        return;
+    }
+    // Recheck immediately before append. The host may accept a prompt between
+    // the first check and this synchronous call.
+    try {
+        if (!args.ctx.isIdle()) {
+            record(deliveryKey, "carried", delivery);
+            return;
+        }
+    }
+    catch (error) {
+        record(deliveryKey, "delivery-failed", delivery, {
+            error: String(error).slice(0, 500),
+        });
+        return;
+    }
+    // SAFETY: appendEntry is an optional host capability absent from older Pi SDKs.
+    const appendEntry = args.pi.appendEntry;
+    if (typeof appendEntry !== "function") {
+        pending.delete(deliveryKey);
+        record(deliveryKey, "capability-unavailable", delivery);
+        return;
+    }
+    const bounded = boundedContent(findings.messages[0]?.content ?? "");
+    try {
+        appendEntry.call(args.pi, TEST_RUNNER_ENTRY_TYPE, {
+            ...bounded,
+            sessionId: delivery.sessionId,
+            generation: delivery.generation,
+            targetCount: delivery.targetCount,
+        });
+        pending.delete(deliveryKey);
+        record(deliveryKey, "delivered", delivery, {
+            droppedDetailCount: bounded.droppedDetailCount,
+            ageMs: Math.max(0, Date.now() - delivery.createdAt),
+        });
+    }
+    catch (error) {
+        record(deliveryKey, "delivery-failed", delivery, {
+            error: String(error).slice(0, 500),
+        });
+    }
+}
+/** Deliver only the result staged by this activation and settled session. */
+export function deliverStagedTestRunnerFindings(args) {
+    if (!args?.cwd || !args.ownerId)
+        return;
+    const delivery = args.sessionId
+        ? pending.get(key(args.cwd, args.sessionId, args.ownerId))
+        : [...pending.values()]
+            .reverse()
+            .find((candidate) => candidate.cwd === args.cwd && candidate.ownerId === args.ownerId);
+    if (!delivery?.owner)
+        return;
+    deliverTestRunnerFindings({
+        pi: delivery.owner.pi,
+        ctx: delivery.owner.getCtx(),
+        cacheManager: delivery.owner.cacheManager,
+        runtime: delivery.owner.runtime,
+        sessionId: delivery.sessionId,
+        ownerId: delivery.ownerId,
+    });
+}
+export function registerTestRunnerEntryRenderer(pi) {
+    // SAFETY: registerEntryRenderer is an optional host capability absent from older Pi SDKs.
+    const register = pi.registerEntryRenderer;
+    if (typeof register !== "function")
+        return false;
+    try {
+        register.call(pi, TEST_RUNNER_ENTRY_TYPE, renderTestRunnerEntry);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function renderTestRunnerEntry(entry, _options, theme) {
+    const content = entry.data?.content;
+    if (typeof content !== "string")
+        return undefined;
+    const lines = [
+        theme.fg("error", "pi-lens test failures"),
+        ...content.split("\n"),
+    ];
+    return {
+        render: (width) => fitLines(lines, width),
+        invalidate: () => { },
+    };
+}
+/** Test-only reset; session ownership prevents cross-session consumption. */
+export function _resetTestRunnerDeliveryForTests() {
+    pending.clear();
+}
+/** Clear staged results when a primary session replaces the owning runtime. */
+export function resetTestRunnerDelivery() {
+    pending.clear();
+}

package/node_modules/pi-lens/dist/clients/tool-definition.js

@@ -1,7 +1,47 @@
+/**
+ * THE final registration boundary for a host-facing tool: everything that
+ * must be true of a tool definition the instant before `pi.registerTool`
+ * sees it. `index.ts` runs every tool it registers — always-active,
+ * situational, and the compact-line-wrapped variants — through this one
+ * function, so a property added here reaches every tool without a second
+ * call site to keep in sync.
+ *
+ * Two jobs today:
+ *  1. metadata the host requires is present (a non-empty description);
+ *  2. an in-flight tool call HOLDS the event loop (#2507). pi-lens unrefs the
+ *     LSP child, its stdio pipes and several waiting timers so an idle
+ *     one-shot process can exit; in a headless child with no other referenced
+ *     handle that let Node exit 0 in the middle of `lsp_diagnostics`. Every
+ *     tool call therefore takes a counted hold for its own duration — see
+ *     `clients/event-loop-hold.ts` for why the hold lives there and not in
+ *     the unref itself.
+ */
+import { acquireEventLoopHold } from "./event-loop-hold.js";
 export function normalizeToolDefinition(tool) {
     const name = typeof tool.name === "string" ? tool.name.trim() : "tool";
     const description = typeof tool.description === "string" && tool.description.trim().length > 0
         ? tool.description
         : `Use the ${name} tool.`;
-    return { ...tool, description };
+    const execute = tool.execute;
+    if (typeof execute !== "function") {
+        return { ...tool, description };
+    }
+    const inner = execute;
+    return {
+        ...tool,
+        description,
+        // A plain function, not an arrow: `this` stays whatever the host called
+        // the tool with, so a definition whose `execute` reads `this` keeps
+        // working. The hold is released in `finally`, so a rejected or aborted
+        // call releases exactly like a resolved one.
+        execute: async function (...args) {
+            const release = acquireEventLoopHold(name);
+            try {
+                return await inner.apply(this, args);
+            }
+            finally {
+                release();
+            }
+        },
+    };
 }