@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/security-scan-client.js

@@ -12,34 +12,73 @@
  *
  * Refs: #130, #131, #132
  */
+import * as path from "node:path";
 import { createSubsystemLogger } from "./extension-log.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
-import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { classifyProbeFailure, createAvailabilityLatch, describeInstallAttempt, describeProbeEvidence, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 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 probe that
-     * merely timed out must go through `markTransientlyUnavailable` instead, so
-     * it expires and the tool can come back without a host restart.
+     * 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)
+        if (value === true) {
             this.availabilityLatch.noteAvailable();
-        else if (value === false)
-            this.availabilityLatch.noteUnavailable("missing", "not-found");
-        else
+            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);
     }
-    /** Outcome/cause of the most recent `probeVersion` call. */
+    /**
+     * 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,
+            verdict: "unavailable",
+            outcome: "missing",
+            cause: "not-found",
+            elapsedMs,
+            latched: true,
+            classifiedBy: "caller",
+            ...(evidence !== undefined && { evidence }),
+        });
+    }
+    /** Outcome of the most recent `probeVersion` call. */
     lastProbeOutcome = null;
-    lastProbeCause = null;
     ensureInFlight = null;
     inFlight = new Map();
     binaryPath = null;
@@ -74,10 +113,17 @@ export class SecurityScanClient {
     }
     /**
      * Spawn `toolName <versionArgs>` and report whether it answered cleanly.
-     * Does NOT mutate `this.available` — callers decide what a hit/miss means —
-     * but it does classify the failure (`lastProbeOutcome`/`lastProbeCause`) and
-     * emit one availability-decision record, so a probe that keeps timing out is
-     * visible in latency.log rather than inferred from silence (#1467).
+     * 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();
@@ -95,7 +141,6 @@ export class SecurityScanClient {
         const elapsedMs = Date.now() - startedAt;
         if (!probe.error && probe.status === 0) {
             this.lastProbeOutcome = "success";
-            this.lastProbeCause = "ok";
             this.log(`${this.toolName} found: ${probe.stdout.trim().split("\n")[0]}`);
             logAvailabilityDecision({
                 tool: this.toolName,
@@ -106,12 +151,22 @@ export class SecurityScanClient {
                 latched: true,
                 hostStallMs,
                 budgetMs: 5000,
+                classifiedBy: "probe",
+                evidence: describeProbeEvidence(probe),
             });
             return true;
         }
-        const { outcome, cause } = classifyProbeFailure(probe, { hostStallMs });
+        const { outcome, cause, evidence } = classifyProbeFailure(probe, {
+            hostStallMs,
+        });
         this.lastProbeOutcome = outcome;
-        this.lastProbeCause = cause;
+        // 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,
             verdict: "unavailable",
@@ -120,7 +175,10 @@ export class SecurityScanClient {
             elapsedMs,
             latched: outcome !== "transient",
             hostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
             budgetMs: 5000,
+            classifiedBy: "probe",
+            evidence,
         });
         return false;
     }
@@ -135,9 +193,47 @@ export class SecurityScanClient {
      * 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.
      */
-    markTransientlyUnavailable(cause = "probe-timeout") {
-        return this.availabilityLatch.noteUnavailable("transient", cause);
+    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):
@@ -151,22 +247,59 @@ export class SecurityScanClient {
         }
         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`.
+            // 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`);
-            this.markTransientlyUnavailable(this.lastProbeCause ?? "probe-timeout");
             return false;
         }
         this.log(`${this.toolName} not found, attempting auto-install`);
-        const { ensureTool } = await import("./installer/index.js");
+        const { ensureTool, getInstallAttempt } = await import("./installer/index.js");
+        const installStartedAt = Date.now();
         const installed = await ensureTool(this.toolName);
         if (!installed) {
-            this.log(`${this.toolName} auto-install failed`);
-            this.available = false;
+            // #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;
     }
     /**

package/node_modules/pi-lens/dist/clients/session-event-guard.js

@@ -0,0 +1,184 @@
+/**
+ * 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 { probeCtxActive } from "./session-lifecycle.js";
+/**
+ * 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})`,
+    });
+}
+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 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 {
+            const result = handler(event, ctx);
+            if (isThenable(result)) {
+                // Recover the rejection in place. The host awaits the same promise
+                // it would have awaited anyway; it just resolves instead.
+                // SAFETY: the recovered promise settles to `Awaited<R>`, which the
+                // host consumes exactly as it would an `R` — see the note above.
+                return Promise.resolve(result).catch((err) => {
+                    if (isStaleExtensionCtxError(err))
+                        return skip(event, "mid-handler");
+                    throw err;
+                });
+            }
+            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);
+}