pi-lens 4.3.0 → 4.4.0

package/dist/clients/security-scan-client.js

@@ -1,352 +0,0 @@
-/**
- * Shared machinery for pi-lens's session-scan security clients
- * (gitleaks #130, govulncheck #132, trivy #131).
- *
- * Each of those surfaces findings from an external CLI scanner with the same
- * lifecycle plumbing: a one-time availability resolution (PATH probe, optionally
- * followed by an auto-install) shared across concurrent first-time callers, plus
- * per-target scan re-entrancy so concurrent scans of the same root share a single
- * process. That plumbing was copy-pasted three times; this base owns it once and
- * lets each subclass supply only the tool-specific probe/install
- * (`doEnsureAvailable`) and the scan invocation.
- *
- * Refs: #130, #131, #132
- */
-import * as path from "node:path";
-import { createSubsystemLogger } from "./extension-log.js";
-import { probeToolAsync } from "./tool-probe.js";
-import { classifyProbeFailure, createAvailabilityLatch, describeInstallAttempt, describeProbeEvidence, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
-import { createAvailabilityProbeFlight } from "./availability-probe-flight.js";
-import { createSingleFlight } from "./single-flight.js";
-const securityProbeFlights = createAvailabilityProbeFlight();
-export class SecurityScanClient {
-    toolName;
-    /**
-     * Availability memo, backed by the shared transient-aware latch (#1467).
-     *
-     * Assigning `false` still means "durable: this machine does not have the
-     * tool" — every existing subclass write keeps its meaning. A transient
-     * failure must expire instead: `probeVersion` latches its own transient
-     * verdicts (#1501), and any other transient failure (a scan or install
-     * timeout) goes through `markTransientlyUnavailable`, so the tool can come
-     * back without a host restart.
-     */
-    availabilityLatch = createAvailabilityLatch();
-    get available() {
-        return this.availabilityLatch.read();
-    }
-    set available(value) {
-        if (value === true) {
-            this.availabilityLatch.noteAvailable();
-            return;
-        }
-        if (value !== false) {
-            this.availabilityLatch.reset();
-            return;
-        }
-        this.availabilityLatch.noteUnavailable("missing", "not-found");
-        this.logDurableAbsence();
-    }
-    /**
-     * Latch a durable absence WITH the facts behind it. Prefer this over
-     * `available = false` wherever the call site knows what actually failed — a
-     * `missing` row carrying `install: "failed"` is a retry candidate, one
-     * carrying `install: "not-attempted"` is a policy decision, and a bare one is
-     * a plain absence. Only the record can tell them apart.
-     */
-    noteDurableAbsence(evidence, options = {}) {
-        this.availabilityLatch.noteUnavailable("missing", "not-found");
-        this.logDurableAbsence(evidence, options.elapsedMs);
-    }
-    /**
-     * One record per durable-absence ASSERTION, whether or not the call site had
-     * evidence. Before this, `available = false` after a failed install was a
-     * silent latch: the tool went quiet for the session with nothing in
-     * latency.log to audit (#1500). Bounded — the verdict latches, so at most one
-     * row per client per session.
-     *
-     * `elapsedMs` is whatever the caller measured (an install attempt's duration);
-     * there is no probe here, so it is 0 unless the caller has something real.
-     */
-    logDurableAbsence(evidence, elapsedMs = 0) {
-        logAvailabilityDecision({
-            tool: this.toolName,
-            producer: "security-scan",
-            verdict: "unavailable",
-            outcome: "missing",
-            cause: "not-found",
-            elapsedMs,
-            latched: true,
-            classifiedBy: "caller",
-            ...(evidence !== undefined && { evidence }),
-        });
-    }
-    /** Outcome of the most recent `probeVersion` call. */
-    lastProbeOutcome = null;
-    /** Availability resolution is instance-owned; only its external probe is shared. */
-    ensureFlight = createSingleFlight();
-    inFlight = new Map();
-    binaryPath = null;
-    log;
-    /**
-     * @param toolName binary / installer id used for probes, logs and auto-install
-     * @param verbose  when true, diagnostics are written to stderr
-     */
-    constructor(toolName, verbose = false) {
-        this.toolName = toolName;
-        this.log = verbose ? createSubsystemLogger(toolName) : () => { };
-    }
-    /**
-     * Resolve (once) whether the scanner is usable, sharing the probe promise
-     * across concurrent first-time callers. The tool-specific probe + optional
-     * install lives in `doEnsureAvailable`.
-     */
-    async ensureAvailable() {
-        if (this.available !== null)
-            return this.available;
-        return this.ensureFlight.run("availability", () => this.doEnsureAvailable());
-    }
-    /**
-     * Spawn `toolName <versionArgs>` and report whether it answered cleanly.
-     * Classifies the failure (`lastProbeOutcome`) and emits one
-     * availability-decision record, so a probe that keeps timing out is visible
-     * in latency.log rather than inferred from silence (#1467).
-     *
-     * Latch ownership is split by outcome: success and durable failures leave
-     * `this.available` to the caller (a missing binary may still be
-     * auto-installed), while a TRANSIENT failure is latched by the seam itself
-     * with its cooldown — the retry schedule only exists once the latch owns
-     * the verdict, and the record is incomplete without it (#1501). Callers
-     * must not re-mark a probe transient (a second noteUnavailable would
-     * double-escalate the cooldown).
-     */
-    async probeVersion(versionArgs) {
-        const sampler = startHostStallSampler();
-        const startedAt = Date.now();
-        let probe;
-        let hostStallMs;
-        let resolvedBinaryPath = null;
-        let probeJoined = false;
-        try {
-            const shared = securityProbeFlights.run(`security:${this.toolName}|${versionArgs.join("|")}`, async () => {
-                const { findManagedToolBinary } = await import("./installer/index.js");
-                const managed = await findManagedToolBinary(this.toolName);
-                return {
-                    probe: await probeToolAsync(managed ?? this.toolName, versionArgs, {
-                        timeout: 5000,
-                    }),
-                    binaryPath: managed ?? null,
-                };
-            });
-            probeJoined = shared.joined;
-            const flightResult = await shared.promise;
-            probe = flightResult.probe;
-            resolvedBinaryPath = flightResult.binaryPath;
-            if (!probe.error && probe.status === 0 && flightResult.binaryPath) {
-                this.binaryPath = flightResult.binaryPath;
-            }
-        }
-        finally {
-            hostStallMs = sampler.stop();
-        }
-        const elapsedMs = Date.now() - startedAt;
-        if (!probe.error && probe.status === 0) {
-            this.lastProbeOutcome = "success";
-            this.log(`${this.toolName} found: ${probe.stdout.trim().split("\n")[0]}`);
-            logAvailabilityDecision({
-                tool: this.toolName,
-                producer: "security-scan",
-                verdict: "available",
-                outcome: "success",
-                cause: "ok",
-                elapsedMs,
-                latched: true,
-                hostStallMs,
-                budgetMs: 5000,
-                classifiedBy: probeJoined ? "joined" : "probe",
-                evidence: {
-                    ...describeProbeEvidence(probe),
-                    ...(resolvedBinaryPath && {
-                        binary: path.basename(resolvedBinaryPath),
-                        source: "managed-dir",
-                    }),
-                },
-            });
-            return true;
-        }
-        const { outcome, cause, evidence } = classifyProbeFailure(probe, {
-            hostStallMs,
-        });
-        this.lastProbeOutcome = outcome;
-        // A transient verdict's record is incomplete without the retry schedule,
-        // and the schedule only exists once the latch owns the verdict — so the
-        // seam writes the expiring verdict itself, at log time (#1501). Durable
-        // outcomes stay caller-owned (a missing binary may still be installed).
-        const retryAfterMs = outcome === "transient"
-            ? this.availabilityLatch.noteUnavailable("transient", cause)
-            : 0;
-        logAvailabilityDecision({
-            tool: this.toolName,
-            producer: "security-scan",
-            verdict: "unavailable",
-            outcome,
-            cause,
-            elapsedMs,
-            latched: outcome !== "transient",
-            hostStallMs,
-            ...(retryAfterMs > 0 && { retryAfterMs }),
-            budgetMs: 5000,
-            classifiedBy: probeJoined ? "joined" : "probe",
-            evidence: {
-                ...evidence,
-                ...(resolvedBinaryPath && {
-                    binary: path.basename(resolvedBinaryPath),
-                    source: "managed-dir",
-                }),
-            },
-        });
-        return false;
-    }
-    /** True when the last probe failed for a reason that is not the tool's fault. */
-    probeWasTransient() {
-        return this.lastProbeOutcome === "transient";
-    }
-    /**
-     * Record a non-durable unavailability: the verdict expires after a cooldown
-     * and the next `ensureAvailable` re-probes.
-     *
-     * Returns that cooldown in ms so the caller can put it in its decision
-     * record. A latch you can read in `latency.log` without the retry schedule
-     * beside it only tells you the tool is off, not when it comes back.
-     *
-     * For NON-probe transient failures only (scan/install timeouts):
-     * `probeVersion` latches and logs its own transient verdicts (#1501), so
-     * re-marking one here would double-escalate the cooldown.
-     *
-     * Pass `opts.operationClass: "install"` when the failed operation was a
-     * network install/compile rather than a cheap probe (#1497): the retry
-     * escalates on the install-class schedule, on its OWN cooldown slot (a
-     * cheap probe failure can never shorten it), and latches for the session at
-     * the attempt ceiling, in which case the return is 0 (latched).
-     */
-    markTransientlyUnavailable(cause = "probe-timeout", opts) {
-        return this.availabilityLatch.noteUnavailable("transient", cause, opts);
-    }
-    /**
-     * The cause the LATCH settled on, which is not always the cause the caller
-     * passed in: at the install-class ceiling the latch rewrites it to
-     * `install-retry-exhausted` (#1497). A decision record built from the
-     * caller's own cause would say `probe-timeout` for a verdict that is no
-     * longer being retried, so the record reads it back from here.
-     */
-    latchedCause() {
-        return this.availabilityLatch.getCause();
-    }
-    /**
-     * #1623: public window onto the availability verdict for callers OUTSIDE
-     * the dispatch graph (mode=full's fresh-fetch) that need to say WHY
-     * `ensureAvailable()` most recently returned false — using the SAME
-     * `AvailabilityOutcome`/`AvailabilityCause` taxonomy every dispatch-side
-     * message is built from, rather than a re-guessed "binary unavailable"
-     * that can't tell a transient retry-cooldown probe from a durable absence.
-     * `latchedCause()`/`lastProbeOutcome` above stay `protected` for
-     * dispatch-internal callers; this is the one public seam for everyone
-     * else.
-     */
-    getAvailabilityVerdict() {
-        return {
-            outcome: this.availabilityLatch.getOutcome(),
-            cause: this.availabilityLatch.getCause(),
-            retryAtMs: this.availabilityLatch.getRetryAtMs(),
-        };
-    }
-    /**
-     * Standard availability path for the GitHub-release tools (gitleaks, trivy):
-     * PATH probe first, then fall back to the pi-lens installer's `ensureTool`.
-     * Records the resolved binary path and sets `this.available`.
-     */
-    async ensureViaInstaller(versionArgs) {
-        if (await this.probeVersion(versionArgs)) {
-            this.available = true;
-            return true;
-        }
-        if (this.probeWasTransient()) {
-            // A timed-out probe is not evidence the tool is absent, so it must not
-            // trigger an install NOR latch a permanent `false`. probeVersion has
-            // already recorded the expiring verdict and its retry schedule
-            // (#1501) — re-marking it here would double-escalate the cooldown.
-            this.log(`${this.toolName} availability probe timed out; not installing, will retry`);
-            return false;
-        }
-        this.log(`${this.toolName} not found, attempting auto-install`);
-        const { ensureTool, getInstallAttempt } = await import("./installer/index.js");
-        const installStartedAt = Date.now();
-        const installed = await ensureTool(this.toolName);
-        if (!installed) {
-            // #1500: this classification is ASSERTED, not derived. It is justified —
-            // the probe already classified a genuine absence, and a failed repair
-            // leaves the tool absent — but the install failure has no taxonomy of
-            // its own, so a network blip and a permanently unavailable release look
-            // identical from here. Record what happened rather than only the verdict.
-            //
-            // `ensureTool` answers the same empty result whether it TRIED and failed
-            // or declined to try (auto-install off, project trust denied), so the
-            // attempt is read from the reason it records rather than assumed — the
-            // review found `install: "failed"` being written for attempts that never
-            // happened.
-            const attempt = getInstallAttempt(this.toolName);
-            this.log(attempt?.outcome === "failed"
-                ? `${this.toolName} auto-install failed: ${attempt.reason ?? "unknown reason"}`
-                : `${this.toolName} auto-install did not run: ${attempt?.reason ?? "no attempt recorded"}`);
-            this.noteDurableAbsence(describeInstallAttempt(attempt), {
-                elapsedMs: Date.now() - installStartedAt,
-            });
-            return false;
-        }
-        this.binaryPath = installed;
-        this.available = true;
-        this.log(`${this.toolName} auto-installed at ${installed}`);
-        // The probe already wrote a latched `unavailable` row (#1500's durable
-        // assertion doesn't fire here — install SUCCEEDED — but probeVersion's
-        // verdict still did, before this call ever ran). Without a compensating
-        // row, the durable record says the lane is off when it just came back
-        // on: the exact defect #1606 was filed over.
-        logAvailabilityDecision({
-            tool: this.toolName,
-            verdict: "available",
-            outcome: "success",
-            cause: "ok",
-            elapsedMs: Date.now() - installStartedAt,
-            latched: true,
-            classifiedBy: "caller",
-            evidence: {
-                install: "succeeded",
-                binary: path.basename(installed),
-                source: "managed-dir",
-            },
-        });
-        return true;
-    }
-    /**
-     * Per-target scan re-entrancy: when a scan for `key` is already running, the
-     * concurrent caller shares the in-flight promise instead of spawning a second
-     * process. The entry is cleared when the run settles.
-     */
-    dedupeScan(key, run) {
-        const existing = this.inFlight.get(key);
-        if (existing) {
-            this.log(`Scan already in flight for ${key}; sharing result`);
-            return existing;
-        }
-        // Identity-guarded release (#1968's pattern): delete only if THIS run is
-        // still the registered one. A bare delete-by-key lets a late-settling run
-        // evict a live successor a second writer registered under the same key
-        // mid-flight, after which the next caller starts a duplicate scan.
-        const promise = run().finally(() => {
-            if (this.inFlight.get(key) === promise)
-                this.inFlight.delete(key);
-        });
-        this.inFlight.set(key, promise);
-        return promise;
-    }
-}

package/dist/clients/session-event-guard.js

@@ -1,297 +0,0 @@
-/**
- * One home for "this event arrived on a ctx the SDK already invalidated"
- * (#1925).
- *
- * pi invalidates a captured extension ctx when the session is replaced —
- * `ctx.newSession()`, `ctx.fork()`, `ctx.switchSession()`, `ctx.reload()`.
- * Every accessor on that ctx then throws from the SDK's `assertActive()`
- * (`core/extensions/loader.js` in the installed
- * `@earendil-works/pi-coding-agent`). An event already queued when the swap
- * happens still reaches pi-lens, carrying the dead ctx, and the first
- * unguarded `ctx.signal` / `ctx.ui` / `ctx.cwd` read throws.
- *
- * That throw does not escape into pi's loop. `ExtensionRunner.emit` wraps every
- * handler call in a try/catch and routes the error to `emitError`
- * (`core/extensions/runner.js:586-606` in the installed SDK), so the throw
- * surfaces as an extension error report against pi-lens. The report names the
- * wrong cause. It reads as a pi-lens handler bug when the real event is a
- * benign race with a session swap, it says nothing about which handler keeps
- * losing, and it counts nothing. This wrapper converts that noisy misattributed
- * error into a counted, bounded, attributable skip.
- *
- * #1924 fixed that for `agent_settled` with an inline try/catch. #1925 found
- * four more handlers with the same shape. Five inline copies of one policy is
- * the parallel-state defect AGENTS.md names, so the policy lives here instead.
- * `agent_settled` is a consumer of this path, not a special case.
- *
- * ## What this module actually covers
- *
- * Not every `pi.on` registration in `index.ts` goes through here, and the doc
- * used to read as if they all did. Seven do today:
- *
- * - {@link wrapSessionEventHandler} — `tool_result`, `turn_start`,
- *   `agent_end`, `turn_end`, `agent_settled` (#1925) and `session_start`
- *   (#1929). All six return nothing, so a skipped event resolving to
- *   `undefined` is exactly their own early-exit value.
- * - {@link wrapSessionEventHandlerWithResult} — `context` (#1929), which must
- *   hand the host back a message list on the live path.
- *
- * Five registrations stay unwrapped on purpose: `resources_discover`,
- * `session_before_fork`, `tool_call`, `session_shutdown`, and `message_end`.
- * `tests/clients/session-event-guard-sweep.test.ts` is the source of truth for
- * that split. It scans every registration in `index.ts` and reds unless the
- * handler is wrapped or carries a written reason, so this paragraph can go
- * stale but the contract cannot.
- *
- * The wrapper does three things and nothing else:
- *
- * 1. **Probes once, before dispatch.** {@link probeCtxActive} answers `false`
- *    only when an `assertActive()`-wrapped accessor threw the SDK's own stale
- *    message. `undefined` (no ctx, unexpected shape, unrecognised throw) is
- *    inconclusive and always dispatches — never guess a session dead.
- * 2. **Still classifies a stale throw that races in mid-handler.** The probe
- *    is a point-in-time read; the swap can land between the probe and the
- *    handler's own first ctx read, and for an async handler it can land at any
- *    await. Both the synchronous throw and the rejected promise are
- *    classified by {@link isStaleExtensionCtxError}.
- * 3. **Makes the skip visible.** One bounded record and one ledger kind for
- *    the whole class, keyed by the event name so aggregation still answers
- *    WHICH handler is being skipped. A silent guard and a guard that never
- *    fires read identically from a log, which is exactly how vacuous guards
- *    survive review.
- *
- * Anything that is NOT the SDK's stale-ctx error propagates unchanged. The
- * wrapper narrows nothing else: a handler bug must stay as loud as it was.
- */
-import { emitBounded } from "./bounded-telemetry.js";
-import { recordDegradationOnce } from "./degradation-ledger.js";
-import { bounded } from "./deadline-utils.js";
-import { HOOK_WALL_BUDGET_MS } from "./hook-budgets.js";
-import { probeCtxActive } from "./session-lifecycle.js";
-import { runWithTurnContext } from "./turn-context.js";
-function stableSessionId(ctx) {
-    try {
-        return ctx?.sessionManager?.getSessionId?.();
-    }
-    catch {
-        recordDegradationOnce({
-            kind: "turn-context-identity-fallback",
-            subject: "session-event-guard",
-            reason: "stable session identity resolution failed; using detached turn context",
-        });
-        return undefined;
-    }
-}
-/**
- * The pi SDK invalidates a captured `pi`/command ctx after a session
- * replacement or reload; every later `pi.*` call then throws with this
- * signature. Matched by MESSAGE — not by `===` against a captured instance —
- * so a fire-and-forget task that races a session swap can recognise the benign
- * stale-ctx throw and degrade to a no-op. Substring-matched on the stable
- * "stale after session replacement or reload" phrase so it survives incidental
- * wording changes around it.
- *
- * Deliberately a NARROWER match than {@link probeCtxActive}'s (which accepts
- * the shorter "stale after session replacement", the message
- * `ExtensionRunner.invalidate()` uses for its own probe path). Widening this
- * one is a behavior change: it decides which throws get swallowed.
- */
-export function isStaleExtensionCtxError(err) {
-    return (err instanceof Error &&
-        err.message.includes("stale after session replacement or reload"));
-}
-/**
- * Record one skipped session event. Bounded per event name: the ledger counts
- * every occurrence exactly, and only the first per event name this session
- * also writes the detailed `latency.log` row, so a replaced session whose
- * queue drains a hundred stale events cannot storm the log.
- */
-function recordStaleSkip(eventName, detectedAt) {
-    emitBounded("session_event_stale_ctx_skip", eventName, {
-        durationMs: 0,
-        metadata: { event: eventName, detectedAt },
-    }, {
-        ledgerKind: "extension-ctx-stale",
-        risingEdgePer: "identity",
-        reason: `${eventName} skipped: extension ctx is stale (${detectedAt})`,
-    });
-}
-/**
- * The one policy for "a pi hook handler threw and production swallows it"
- * (#2884).
- *
- * Nine catch sites in `index.ts` absorb a crashed handler so a pi-lens bug
- * can never take down the host's session. Each of them used to write only
- * `dbg(...)`, and `dbg` writes nothing under vitest — so a crashed handler was
- * indistinguishable from a completed one. #2859 is what that costs: fourteen
- * `session_start` awaits in `tests/index-integration.test.ts` rejected into
- * one of those catches, every assertion after them was vacuous, and the file
- * stayed green. #2866 closed the hole for `session_start` with an inline
- * `if (process.env.VITEST) throw`; this function is that guard folded into one
- * place so the remaining eight cannot drift from it.
- *
- * Two things happen on every crash, in this order:
- *
- * 1. **The production record.** One bounded `hook-handler-crash` row per
- *    handler per session (`recordDegradationOnce`), so a handler that crashes
- *    on every turn leaves one durable row and an exact ledger tally instead of
- *    a silent no-op. It is written BEFORE the rethrow, so a test can assert the
- *    production observability the runner path would otherwise hide.
- * 2. **The runner rethrow.** Under vitest the crash is rethrown, so the test
- *    whose `await` caused it fails with the real error instead of resolving.
- *    In production nothing is rethrown and the caller's swallow stands.
- *
- * Deliberately `process.env.VITEST` and not `isTestMode()` (kept from #2859):
- * the question is whether a TEST is awaiting this handler, and the #2815 R7
- * case runs under vitest with `PI_LENS_TEST_MODE=0`.
- *
- * The stale-ctx class is NOT this function's business. Callers that classify
- * it (`session_start`, `agent_end`, `turn_end`, the `agent_settled` drain)
- * rethrow `isStaleExtensionCtxError` themselves BEFORE calling in, so a benign
- * session swap keeps its own single record and never lands here as a crash.
- * The quiet-window site is intentionally the exception to the test-runner
- * rethrow: it is fire-and-forget, so a rethrow would be an unhandled rejection
- * that can terminate the pi host before its caller can observe the failure.
- */
-export function surfaceHandlerCrash(handler, err, options = {}) {
-    try {
-        options.dbg?.(`${handler} crashed: ${err}`);
-        options.dbg?.(`${handler} crash stack: ${err?.stack}`);
-    }
-    catch {
-        // A debug sink must never decide whether a crash is recorded.
-    }
-    recordDegradationOnce({
-        kind: "hook-handler-crash",
-        subject: handler,
-        reason: `${handler} handler crashed and was swallowed: ${String(err)}`,
-    });
-    if (process.env.VITEST && options.rethrow !== false)
-        throw err;
-}
-function isThenable(value) {
-    return (typeof value?.then === "function");
-}
-/**
- * The one policy. Both public wrappers are this function with a different
- * stale-path value, so the probe point, the classification, and the record can
- * never drift apart between a void handler and a value-returning one.
- */
-function guardSessionEvent(eventName, handler, onStaleResult, options) {
-    const defaultBudgetKey = (eventName) => {
-        if (eventName === "tool_result")
-            return "tool_result_edit";
-        if (eventName === "session_start" ||
-            eventName === "turn_end" ||
-            eventName === "agent_end" ||
-            eventName === "agent_settled")
-            return eventName;
-        return undefined;
-    };
-    const skip = (event, detectedAt) => {
-        recordStaleSkip(eventName, detectedAt);
-        try {
-            options.dbg?.(`${eventName} skipped: extension ctx is stale after session replacement or reload`);
-        }
-        catch {
-            // A debug sink must never decide whether an event is handled.
-        }
-        return onStaleResult(event);
-    };
-    return (event, ctx) => {
-        // `false` is the only confirmed verdict. `undefined` means the probe
-        // could not tell, and an inconclusive probe must dispatch.
-        if (probeCtxActive(ctx) === false)
-            // SAFETY: `R` is the handler's declared return type, which is either a
-            // plain value or a promise of one. `skip` yields `Awaited<R>`, the
-            // settled form. TypeScript cannot see that a host awaiting an `R` is
-            // equally satisfied by the settled value, but every `pi.on` caller
-            // either awaits the result or ignores it, so both forms behave the
-            // same at the call site. The same reasoning covers the two casts
-            // below.
-            return skip(event, "pre-dispatch");
-        try {
-            let signal;
-            try {
-                signal = ctx?.signal;
-            }
-            catch (err) {
-                if (isStaleExtensionCtxError(err))
-                    return Promise.resolve(skip(event, "mid-handler"));
-                // The signal read moved out of each handler's own try/catch and
-                // into the guard (#2523 hook budgets), so a ctx whose `signal`
-                // accessor throws for a NON-stale reason is a crashed handler and
-                // must leave the same record the handler's own catch used to (#2884).
-                // This preserves the old catch behavior for lifecycle handlers. The
-                // `tool_result` and `context` handlers never caught this signal read,
-                // so their non-stale accessor errors are surfaced as a swallowed
-                // handler crash instead (#2939 F5). `rethrow` is intentionally not
-                // forwarded: wrappers do not pass it, and only `surfaceHandlerCrash`
-                // honors that option (#2939 F4).
-                const crashOptions = {};
-                if (options.dbg !== undefined)
-                    crashOptions.dbg = options.dbg;
-                surfaceHandlerCrash(eventName, err, crashOptions);
-                return Promise.resolve(onStaleResult(event));
-            }
-            const result = runWithTurnContext(stableSessionId(ctx), () => handler(event, ctx));
-            if (isThenable(result)) {
-                const recovered = Promise.resolve(result).catch((err) => {
-                    if (isStaleExtensionCtxError(err))
-                        return skip(event, "mid-handler");
-                    throw err;
-                });
-                const budget = typeof options.budgetKey === "function"
-                    ? options.budgetKey(event, ctx)
-                    : (options.budgetKey ?? defaultBudgetKey(eventName));
-                if (budget === undefined)
-                    return recovered;
-                return bounded(recovered, {
-                    ms: HOOK_WALL_BUDGET_MS[budget],
-                    // The settled drain must observe an aborted signal and requeue
-                    // before its promise is released; its own workers read the same
-                    // signal and remain bounded at their seams.
-                    signal: budget === "agent_settled" ? undefined : signal,
-                    hook: budget,
-                    label: "registered-handler",
-                });
-            }
-            return result;
-        }
-        catch (err) {
-            if (isStaleExtensionCtxError(err))
-                // SAFETY: a synchronous handler's `R` is already its settled form,
-                // so `Awaited<R>` and `R` coincide here — see the note above.
-                return skip(event, "mid-handler");
-            throw err;
-        }
-    };
-}
-/**
- * Wrap one `pi.on` handler so a stale ctx becomes an observable no-op instead
- * of a throw into the host.
- *
- * The returned function keeps the handler's own signature and its return
- * value, so a wrapped registration is a drop-in for the bare one. A skipped
- * event resolves to `undefined`, which is what every handler wrapped this way
- * already returns on its early-exit paths.
- *
- * Use {@link wrapSessionEventHandlerWithResult} when `undefined` is NOT the
- * handler's own no-op value.
- */
-export function wrapSessionEventHandler(eventName, handler, options = {}) {
-    return guardSessionEvent(eventName, handler, () => undefined, options);
-}
-/**
- * {@link wrapSessionEventHandler} for a handler whose return value the host
- * consumes (#1929).
- *
- * The live path returns exactly what the handler returned. The stale path
- * returns `onStaleResult(event)` instead of assuming `undefined`, so a handler
- * whose no-op value is something else does not get one silently substituted.
- * Probe, classification, and the bounded record are identical to the void
- * wrapper's — they are the same function underneath.
- */
-export function wrapSessionEventHandlerWithResult(eventName, handler, options) {
-    return guardSessionEvent(eventName, handler, options.onStaleResult, options);
-}