@herbertgao/pi-extensions 2026.9.2 → 2026.9.4

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

@@ -13,6 +13,7 @@ import * as path from "node:path";
 import { createAvailabilityChecker, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
 import { isFileKind } from "./file-kinds.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { resolveToolCwd } from "./tool-cwd.js";
 import { ruffConfigArgs } from "./tool-policy.js";
 // --- Client ---
 const ruffAvailability = createAvailabilityChecker("ruff", ".exe");
@@ -44,8 +45,11 @@ export class RuffClient {
     }
     /**
      * Async auto-fix variant for pipeline use (non-blocking spawn).
-     * `cwd` is the dispatch language root (used for config discovery); when
-     * omitted it defaults to the file's directory.
+     * `cwd` is the dispatch language root. It is the seam's starting point,
+     * not the answer: `resolveToolCwd` walks from the file to the nearest
+     * `pyproject.toml`/`ruff.toml`/`.ruff.toml` at or above it, capped inside
+     * `cwd` (and at `$HOME` when there is none), so a file in a nested package
+     * gets that package's config rather than the workspace-root one.
      */
     async fixFileAsync(filePath, cwd) {
         if (!(await this.ensureAvailable())) {
@@ -67,15 +71,20 @@ export class RuffClient {
         }
         try {
             const before = await fs.promises.readFile(absolutePath, "utf-8");
+            // #2894: the root ruff resolves its config from now comes from the
+            // shared seam, not a local `cwd ?? path.dirname(file)`. `tool-policy.ts`
+            // requires the lint runner (`ruff.ts`, on `resolveRunnerCwd`) and this
+            // autofix path to consume the SAME policy; deriving the root two
+            // different ways is how they drift, and the hand-rolled form ignored a
+            // nested `pyproject.toml` whenever the caller passed a workspace root.
+            const ruffCwd = resolveToolCwd("runner", "ruff", absolutePath, {
+                ...(cwd !== undefined && { cwd }),
+            });
             // Shared config-args seam (#1247): the lint runner consumes the same
             // builder, so `check --fix` can never drift to ruff's default rule
             // set when the project lacks its own config and the package-owned
             // core.toml fallback applies.
-            const configArgs = ruffConfigArgs(cwd ?? path.dirname(absolutePath));
-            const spawnOpts = {
-                timeout: 10000,
-                cwd: cwd ?? path.dirname(absolutePath),
-            };
+            const configArgs = ruffConfigArgs(ruffCwd);
             const pre = await safeSpawnAsync(this.ruffCommand, [
                 "check",
                 "--output-format",
@@ -84,12 +93,12 @@ export class RuffClient {
                 "py310",
                 ...configArgs,
                 absolutePath,
-            ], spawnOpts);
+            ], { timeout: 10000, cwd: ruffCwd });
             const beforeDiags = pre.stdout?.trim()
                 ? this.parseOutput(pre.stdout, absolutePath)
                 : [];
             const fixableCount = beforeDiags.filter((d) => d.fixable).length;
-            const fix = await safeSpawnAsync(this.ruffCommand, ["check", "--fix", ...configArgs, absolutePath], { timeout: 15000, cwd: cwd ?? path.dirname(absolutePath) });
+            const fix = await safeSpawnAsync(this.ruffCommand, ["check", "--fix", ...configArgs, absolutePath], { timeout: 15000, cwd: ruffCwd });
             if (fix.error) {
                 return {
                     success: false,

package/node_modules/pi-lens/dist/clients/runtime-agent-end.js

@@ -39,6 +39,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
     // to fall back to "claim as orphaned" (see claimDeferredFormatFiles).
     const { claimed, staleClaimed, deferredToOwner, droppedOrphans } = runtime.claimDeferredMutations(currentSessionId, Date.now(), staleAfterMs, ctxCwd ?? runtime.projectRoot);
     const records = [...claimed, ...staleClaimed];
+    const scheduledTurnId = records[0]?.queuedTurnId;
     const requeuedKinds = new Set();
     // S2d (gap 4, #1432 review): the aggregate `agent_end_deferred_mutation_drain`
     // row only carried a coalesced `requeuedKinds` set with no reason, per-call
@@ -65,6 +66,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
             toolName: "agent_end",
             filePath: ctxCwd ?? runtime.projectRoot,
             phase: "agent_end_deferred_mutation_requeue",
+            turnId: pending[0]?.queuedTurnId,
             durationMs: 0,
             metadata: {
                 reason,
@@ -170,6 +172,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
             toolName: "agent_end",
             filePath: ctxCwd ?? runtime.projectRoot,
             phase: "agent_end_deferred_format_stale_claim",
+            turnId: scheduledTurnId,
             durationMs: 0,
             metadata: {
                 fileCount: staleClaimed.length,
@@ -307,6 +310,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         toolName: "agent_end",
         filePath: ctxCwd ?? runtime.projectRoot,
         phase: "agent_end_deferred_format_start",
+        turnId: scheduledTurnId,
         durationMs: 0,
         metadata: {
             fileCount: records.length,
@@ -491,6 +495,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                 toolName: "agent_end",
                 filePath,
                 phase: "deferred_format_file",
+                turnId: record.queuedTurnId,
                 durationMs: Date.now() - fileStart,
                 metadata: {
                     changed: result.formatChanged,
@@ -635,6 +640,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                     toolName: "agent_end",
                     filePath: ctxCwd ?? runtime.projectRoot,
                     phase: "actionable_warnings_autofix",
+                    turnId: scheduledTurnId,
                     durationMs: Date.now() - fixStart,
                     metadata: {
                         considered: fixSummary.considered,
@@ -657,6 +663,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         toolName: "agent_end",
         filePath: ctxCwd ?? runtime.projectRoot,
         phase: "agent_end_deferred_mutation_drain",
+        turnId: scheduledTurnId,
         durationMs: Date.now() - startedAt,
         metadata: {
             autofixRecords: autofixRecords.length,
@@ -671,6 +678,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         filePath: ctxCwd ?? runtime.projectRoot,
         durationMs: Date.now() - startedAt,
         result: "deferred_format_complete",
+        turnId: scheduledTurnId,
         metadata: {
             queued: summary.queued,
             formatted: summary.formatted,
@@ -685,6 +693,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         toolName: "agent_end",
         filePath: ctxCwd ?? runtime.projectRoot,
         phase: "agent_end_deferred_format_done",
+        turnId: scheduledTurnId,
         durationMs: Date.now() - startedAt,
         metadata: {
             formatted: summary.formatted,

package/node_modules/pi-lens/dist/clients/runtime-coordinator.js

@@ -11,6 +11,7 @@ import { ReadGuard } from "./read-guard.js";
 import { RUNTIME_CONFIG } from "./runtime-config.js";
 import { TurnSummaryCollector } from "./turn-summary.js";
 import { deriveProviderFromModelId } from "./model-provider.js";
+import { beginTurnContext, setTurnContextSession } from "./turn-context.js";
 /**
  * Bounded receipt ring capacity (defect shape 9: bound the axis that grows —
  * per-mutation receipts are unbounded across a long session). Oldest receipts
@@ -259,6 +260,7 @@ export class RuntimeCoordinator {
         // by resetForSession().
         this._turnStartProjectSeq = this._projectSeq;
         this._turnIndex += 1;
+        beginTurnContext(this._telemetrySessionId);
         this._writeIndex = 0;
         this._reportedThisTurn.clear();
         this._writtenThisTurn.clear();
@@ -362,6 +364,7 @@ export class RuntimeCoordinator {
     setTelemetryIdentity(identity) {
         if (identity.sessionId && identity.sessionId.trim()) {
             this._telemetrySessionId = identity.sessionId.trim();
+            setTurnContextSession(this._telemetrySessionId);
         }
         const model = identity.model?.trim();
         const provider = identity.provider?.trim();
@@ -1029,6 +1032,7 @@ export class RuntimeCoordinator {
             existing.toolNames.add(toolName);
             existing.kinds.add(kind);
             existing.queuedTurnIndex = this._turnIndex;
+            existing.queuedTurnId = `${this._telemetrySessionId}:${this._turnIndex}`;
             existing.ownerSessionId = ownerSessionId;
             existing.originCwd = resolvedOriginCwd;
             return addedKind;
@@ -1042,6 +1046,7 @@ export class RuntimeCoordinator {
             toolNames: new Set([toolName]),
             kinds: new Set([kind]),
             queuedTurnIndex: this._turnIndex,
+            queuedTurnId: `${this._telemetrySessionId}:${this._turnIndex}`,
             ownerSessionId,
             originCwd: resolvedOriginCwd,
         });

package/node_modules/pi-lens/dist/clients/runtime-session.js

@@ -42,6 +42,7 @@ import { resetSafeSpawnWindowsCommandCache } from "./safe-spawn.js";
 import { resetAnalyzerBootstrapSessionState, } from "./bootstrap.js";
 import { getSlowFsVerdict, isSlowFs, slowFsDegradationNotice, } from "./slow-fs.js";
 import { countRecentSmells, formatSmellsSessionStartLine, resetSmellsSessionState, } from "./smells-rollup.js";
+import { resetSituationalToolTelemetry } from "./situational-tool-telemetry.js";
 import { findNearestProjectRoot, getStartupScanMaxEntries, isStartupScanVerdictFresh, resolveStartupScanContext, } from "./startup-scan.js";
 import { getSubagentIdentity, isSubagentSession, subagentLightModeNotice, } from "./subagent-mode.js";
 import { TrivyClient } from "./trivy-client.js";
@@ -1361,17 +1362,16 @@ function scheduleDeferredToolProbesWithClients(deps, languageProfile, startupDef
 /**
  * Session-start orientation prepended as a context message (gated by the
  * context-injection toggle). Deliberately lean: it names the high-value tools
- * and the one non-obvious behaviour (mode=all resurfaces stale blocking errors)
+ * and the distinction between cached reporting and active verification
  * — per-tool argument detail lives in each tool's own registered description, so
  * re-documenting it here would just pay the tokens twice every session.
  */
 export const SESSION_START_GUIDANCE = [
     "📌 pi-lens active — automated checks run on every edit/write; blocking errors (including pre-existing) show inline and must be fixed.\n" +
         "Key tools (see each tool's own description for args):\n" +
-        "• lens_diagnostics — session-wide diagnostic state; mode=all resurfaces stale blocking errors that dropped from turn context.\n" +
+        "• lens_diagnostics — source=session reads cache; empty cache ≠ clean; use source=lsp scope=paths for changed files with absent or stale findings.\n" +
         "• symbol_search → module_report → read_symbol/read_enclosing — ranked identifier search, then navigable outline/callback handles + exact body reads; cheaper than reading a whole file before editing.\n" +
-        "• lsp_diagnostics — probe LSP for errors in a file/folder/workspace.\n" +
-        "• Situational (activate via pi_lens_activate_tools): lsp_navigation, ast_grep_search, ast_grep_replace, ast_grep_dump.",
+        "• Situational (activate via pi_lens_activate_tools): lsp_navigation, ast_grep_search, ast_grep_replace. Use ast_grep_search with dump=true to inspect AST nodes.",
 ];
 export async function handleSessionStart(deps) {
     resetDegradationLedger();
@@ -1814,6 +1814,15 @@ export async function handleSessionStart(deps) {
     // #1123 item 3: a fresh session can re-report smells that a prior session
     // already surfaced once (see `checkSmellsAndNoteOnce`'s once-per-session gate).
     resetSmellsSessionState();
+    // #2800 item 8: the situational-tool dead-weight observation (which tools
+    // this session never activated or called) is session-scoped, so its sets
+    // and once-latch re-arm here beside the other registered resets. Both hosts
+    // open the session's row through startSituationalToolTelemetrySession()
+    // BEFORE this handler runs, and a repeated MCP session_start refresh
+    // legitimately re-runs this handler — so the reset only acts when no
+    // telemetry session is open; clearing a live session here would wipe the
+    // calls recorded before the refresh.
+    resetSituationalToolTelemetry();
     // #1782: re-arm the workspace-diagnostics cache session clock. Entries
     // written before this instant assert findings from a session that is over,
     // so they must revalidate before they can be served as current again.

package/node_modules/pi-lens/dist/clients/runtime-tool-result.js

@@ -21,7 +21,7 @@ import { replayThroughMutationBridge, storedLineHashesFor, } from "./observed-mu
 import { getAmbientAbortSignal } from "./safe-spawn.js";
 import { resolveToolCallCorrelationId } from "./tool-event.js";
 import { boundedIndexesForCount, createReadGuardEditBatchSummary, getReadGuardCorrelationId, logReadGuardEvent, } from "./read-guard-logger.js";
-import { notifyExternalFileChange } from "./lsp/index.js";
+import { notifyExternalFileChange, resyncGitChangedFiles, } from "./lsp/index.js";
 import { runPipeline } from "./pipeline.js";
 import { renderPostAutofixNotice, } from "./post-autofix-notice.js";
 import { syncGitGuardRecord } from "./git-guard.js";
@@ -897,6 +897,9 @@ export async function handleToolResult(deps) {
                     durationMs: Date.now() - started,
                     result: `changed:${opaquePaths.length}`,
                 });
+                void resyncGitChangedFiles(opaquePaths).catch((err) => {
+                    dbg(`git-change LSP resync failed: ${err}`);
+                });
             }
         }
         // wp iterates opaquePaths VERBATIM (already normalizeMapKey keys), so the

package/node_modules/pi-lens/dist/clients/runtime-turn.js

@@ -13,6 +13,7 @@ import { getKnipIgnorePatterns } from "./file-utils.js";
 import { formatCacheAgeLabel } from "./finding-delivery-gate.js";
 import { getFullScanWallClockMs, isWorkspaceSweepActive, runWhenWorkspaceSweepIdle, SWEEP_IDLE_SAFETY_MARGIN_MS, } from "./lsp/workspace-sweep-hold.js";
 import { isTestRoleCollateral } from "./collateral-test-role.js";
+import { classifyAndFilterFindings, } from "./gitleaks-client.js";
 import { dedupeSecretFindings, fromAstGrepWarnings, fromGitleaks, fromTrivySecrets, isSecretWarning, secretLocationKey, } from "./secret-findings.js";
 import { deadCodeIssueKey, deadCodeIssues, formatDeadCodeDelta, stableFindingKey, } from "./dead-code-client.js";
 import { logDeadCodeScan } from "./dead-code-logger.js";
@@ -49,6 +50,8 @@ import { emitBounded } from "./bounded-telemetry.js";
 import { degradeDemotedFindingBody, formatDeliveryCapNote, formatRetirementNote, } from "./demoted-finding-render.js";
 import { STALE_LINE_MARKER } from "./stale-marker.js";
 import { getActiveSessionId } from "./session-lifecycle.js";
+import { bounded } from "./deadline-utils.js";
+import { HOOK_WALL_BUDGET_MS } from "./hook-budgets.js";
 import { drainRenderedDependencyDriftFilePaths, getWidgetBlockingFilesForSweep, incrementWidgetDependencyDriftDelivery, markWidgetFileBlockersStale, recordRunner, retireWidgetDependencyDriftBlockers, } from "./widget-state.js";
 /** Maximum detailed notify-stall coverage-gap rows emitted in one turn. */
 const LATE_AUX_COVERAGE_GAP_DETAIL_CAP_PER_TURN = 20;
@@ -1483,6 +1486,26 @@ export async function handleTurnEnd(deps) {
     // provenance) — a blocker, since credentials need rotation before merge.
     const gitleaksData = cacheManager.readCache("gitleaks", cwd)?.data;
     const trivySecretsData = trivyCacheEntry?.data;
+    // Gitleaks deliberately scans gitignored local files and nested repositories
+    // so an explicit security audit can still inspect them. The adapter is the
+    // source of truth for whether a finding belongs in a blocking delivery lane;
+    // filter here before freshness handling so demoted findings cannot leak into
+    // either the blocker or stale-secret turn context.
+    const boundedClassification = await bounded(classifyAndFilterFindings(gitleaksData?.findings ?? [], cwd), {
+        ms: HOOK_WALL_BUDGET_MS.turn_end,
+        signal: deps.signal,
+        hook: "turn_end",
+        label: "classifyAndFilterFindings",
+    });
+    const classifiedGitleaksFindings = boundedClassification ?? gitleaksData?.findings ?? [];
+    if (boundedClassification === undefined) {
+        recordDegradationOnce({
+            kind: "gitleaks_classification_timeout",
+            subject: cwd,
+            reason: "gitleaks classification exceeded the turn_end budget; retained raw findings to fail open",
+        });
+    }
+    const blockingGitleaksFindings = classifiedGitleaksFindings.filter((finding) => gitleaksFindingToProjectDiagnostic(cwd, finding).semantic === "blocking");
     // #1461 slice 1 (#1460): the gitleaks cache is TTL-only, so a finding for a
     // file deleted after the scan is still served as a 🔴 blocker for the rest
     // of the 30-minute window — the live case, and 119 of 126 findings in
@@ -1497,7 +1520,7 @@ export async function handleTurnEnd(deps) {
     // would let any edit — malicious or accidental — mute a real secret.
     const gitleaksGate = gateFindingsByPathFreshness({
         store: "gitleaks",
-        findings: gitleaksData?.findings ?? [],
+        findings: blockingGitleaksFindings,
         cwd,
         scannedAt: gitleaksData?.scannedAt,
         citedPath: (finding) => finding.file,
@@ -2882,6 +2905,7 @@ export async function handleTurnEnd(deps) {
     let lateAuxCoverageGapDropCount = 0;
     const lateAuxStuckPairs = [];
     if (drainedPairs.length > 0) {
+        const lateObserverDeadline = Date.now() + HOOK_WALL_BUDGET_MS.turn_end;
         const byFile = new Map();
         for (const pair of drainedPairs) {
             const list = byFile.get(pair.filePath);
@@ -2993,6 +3017,19 @@ export async function handleTurnEnd(deps) {
                         }
                         continue;
                     }
+                    // A demoted auxiliary still answers through this late path. Feed the
+                    // publication-minus-mark interval into the re-promotion streak. This is
+                    // delivery latency observed by the drain, not the scanner's total scan
+                    // latency. Cache priming is
+                    // below the freshness gate so a changed file cannot resurrect stale data.
+                    if (typeof service.observeLateAuxiliaryAnswer === "function") {
+                        await bounded(service.observeLateAuxiliaryAnswer(lateAuxPath, pair.serverId, cachedEntry.publishedAt - pair.markedAtMs), {
+                            ms: Math.max(1, lateObserverDeadline - Date.now()),
+                            signal: deps.signal /* late observer */,
+                            hook: "turn_end",
+                            label: "observeLateAuxiliaryAnswer",
+                        });
+                    }
                     if (rawDiags.length === 0) {
                         lateAuxCleanConfirmed += 1;
                         continue;
@@ -3045,6 +3082,16 @@ export async function handleTurnEnd(deps) {
                         }
                         continue;
                     }
+                    // #2810 round 4: this drain does NOT write the hash-bound
+                    // last-known record. The prime it used to call could only fire when
+                    // a record already existed at the pair's hash — which requires a
+                    // FULLY covered touch of those exact bytes, the one case where the
+                    // scanner's findings are already in the record — so it was a no-op
+                    // in the demoted steady state it was added for, and a #570/#1470
+                    // hazard everywhere else (an auxiliary-only array replacing the
+                    // merged one). Late findings reach the agent as the gated advisory
+                    // below; the turn-end hash-guarded fast path stays cold for a file
+                    // whose touch was partial, which is exactly what #1470 requires.
                     const lines = gate.live.map((f) => `  ${displayLateAuxPath}:${f.line}:${f.column} [${f.rule}] ${f.message}`);
                     lateAuxDelivered += gate.live.length;
                     lateAuxAnswered += 1;

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

@@ -14,7 +14,7 @@
  */
 import * as path from "node:path";
 import { createSubsystemLogger } from "./extension-log.js";
-import { safeSpawnAsync } from "./safe-spawn.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";
@@ -132,7 +132,7 @@ export class SecurityScanClient {
                 const { findManagedToolBinary } = await import("./installer/index.js");
                 const managed = await findManagedToolBinary(this.toolName);
                 return {
-                    probe: await safeSpawnAsync(managed ?? this.toolName, versionArgs, {
+                    probe: await probeToolAsync(managed ?? this.toolName, versionArgs, {
                         timeout: 5000,
                     }),
                     binaryPath: managed ?? null,

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

@@ -64,7 +64,22 @@
  * 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 { 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
@@ -99,6 +114,59 @@ function recordStaleSkip(eventName, detectedAt) {
         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");
 }
@@ -131,7 +199,7 @@ function guardSessionEvent(eventName, handler, onStaleResult, options) {
             // below.
             return skip(event, "pre-dispatch");
         try {
-            const result = handler(event, ctx);
+            const result = runWithTurnContext(stableSessionId(ctx), () => 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.

package/node_modules/pi-lens/dist/clients/sg-runner.js

@@ -12,6 +12,7 @@ import { getSgCommand, resolveManagedToolClient, } from "./dispatch/runners/util
 import { getProjectIgnoreGlobs } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { probeToolAsync } from "./tool-probe.js";
 import { truncatedByOutputCap } from "./spawn-output-cap.js";
 import { createSingleFlight } from "./single-flight.js";
 import { classifyProbeFailure, describeInstallAttempt, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
@@ -459,7 +460,7 @@ export class SgRunner {
         let result;
         let hostStallMs;
         try {
-            result = await safeSpawnAsync(cmd, [...argsPrefix, "--version"], {
+            result = await probeToolAsync(cmd, [...argsPrefix, "--version"], {
                 timeout: PROBE_TIMEOUT_MS,
             });
         }

package/node_modules/pi-lens/dist/clients/situational-tool-telemetry.js

@@ -0,0 +1,108 @@
+import { logExtension } from "./extension-log.js";
+import { TOOL_REGISTRY } from "./tool-config.js";
+const situationalTools = TOOL_REGISTRY.filter((tool) => "situational" in tool && tool.situational === true).map((tool) => tool.name);
+const situationalToolSet = new Set(situationalTools);
+const activated = new Set();
+const called = new Set();
+let sessionStarted = false;
+let emitted = false;
+// MCP-only connection-terminal latch: once the connection's row is recorded,
+// repeated initialize/tool-call starts must not reopen the session.
+let connectionEnded = false;
+// Which host owns the open session; only MCP may arm connectionEnded. Pi state
+// belongs to the conversation and survives in-process session rebuilds.
+let sessionHost = "mcp";
+function observe(set, name) {
+    if (situationalToolSet.has(name)) {
+        set.add(name);
+    }
+}
+function clearObservations() {
+    activated.clear();
+    called.clear();
+}
+export function observeSituationalToolActivation(names) {
+    for (const name of names)
+        observe(activated, name);
+}
+export function observeSituationalToolCall(name) {
+    observe(called, name);
+}
+export function resetSituationalToolTelemetry() {
+    // A live telemetry session owns its observation sets: both hosts open the
+    // session (which resets the sets) BEFORE handleSessionStart runs, and a
+    // repeated MCP session_start refresh legitimately re-runs that handler —
+    // clearing here would wipe the calls recorded before the refresh. This
+    // registered reset therefore only acts when no session is open.
+    if (sessionStarted)
+        return;
+    clearObservations();
+    emitted = false;
+}
+/**
+ * Open the telemetry session for one host.
+ *
+ * Pi owns one observation set per session file. A shutdown with a
+ * `targetSessionFile` emits the conversation that is ending before the host
+ * opens the replacement. Reload keeps the same file, so its factory rebuild
+ * does not split the row. A process restart opens an empty set and recovers nothing:
+ * pi-lens's own activation memory (`rememberedLazyTools` in `index.ts`) is
+ * empty in a new process, so the restore deactivates every situational tool,
+ * and the host's restored active set is evidence of REGISTRATION, not of
+ * model activation (#2866 review F1). MCP remains connection-scoped.
+ */
+export function startSituationalToolTelemetrySession(host) {
+    if (host === "mcp") {
+        if (connectionEnded)
+            return;
+        if (sessionStarted)
+            return;
+        sessionHost = "mcp";
+        clearObservations();
+        emitted = false;
+        sessionStarted = true;
+        return;
+    }
+    if (sessionStarted) {
+        sessionHost = "pi";
+        return;
+    }
+    sessionHost = "pi";
+    clearObservations();
+    emitted = false;
+    sessionStarted = true;
+}
+/** Emit the one session-end row and make repeated shutdown calls harmless. */
+export function endSituationalToolTelemetry() {
+    if (!sessionStarted)
+        return;
+    emitSituationalDeadWeight();
+    if (sessionHost === "mcp")
+        connectionEnded = true;
+    clearObservations();
+    emitted = false;
+    sessionStarted = false;
+}
+export function emitSituationalDeadWeight() {
+    if (emitted)
+        return;
+    emitted = true;
+    const used = new Set([...activated, ...called]);
+    logExtension({
+        subsystem: "tools",
+        level: "debug",
+        message: "situational tool dead weight",
+        metadata: {
+            tools: situationalTools.filter((name) => !used.has(name)),
+        },
+    });
+}
+/** Test-only view of the module's state, for the #1635 session-state registry probe. */
+export function _getSituationalToolTelemetryStateForTests() {
+    return {
+        activated: activated.size,
+        called: called.size,
+        emitted,
+        sessionStarted,
+    };
+}