@herbertgao/pi-extensions 2026.8.5 → 2026.8.6

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

@@ -15,10 +15,30 @@ import { getGlobalPiLensDir } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { biomeConfigArgs } from "./tool-policy.js";
-import { resolveManagedToolClient } from "./dispatch/runners/utils/runner-helpers.js";
+import { resolveManagedToolClient, } from "./dispatch/runners/utils/runner-helpers.js";
+import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 // --- Client ---
+const PROBE_TIMEOUT_MS = 10_000;
 export class BiomeClient {
-    biomeAvailable = null;
+    /**
+     * Availability memo, backed by the shared transient-aware latch (#1476).
+     *
+     * Biome is the hot-path formatter: before this, ANY probe failure — a
+     * timeout included — collapsed to `{ outcome: "missing" }`, which both
+     * triggered an install and latched `false` for the life of the process. One
+     * slow first format then disabled formatting until restart.
+     */
+    availabilityLatch = createAvailabilityLatch();
+    /** Cause of the last probe, read when the resolution comes back. */
+    lastProbeCause = null;
+    /**
+     * Measurements of the last failed probe, held until the latch decides how
+     * long the verdict lasts. The decision record is emitted after that, so it
+     * can carry `retryAfterMs` — a latch you can see is worth little if the
+     * retry schedule is not greppable beside it (#1474).
+     */
+    lastProbeElapsedMs = 0;
+    lastProbeHostStallMs = 0;
     // Per-cwd cache of the resolved biome binary. Keying by cwd matters in
     // monorepos where different sub-packages each ship their own biome
     // installation; sharing one slot across the whole client would cause
@@ -100,10 +120,15 @@ export class BiomeClient {
      * `ensureInFlight` promise so probing/auto-install isn't duplicated.
      * Mirrors the dedupe pattern in `SgRunner` / `KnipClient` /
      * `DependencyChecker`.
+     *
+     * The memo returns `null` when the last verdict was transient and its
+     * cooldown expired, which re-enters the probe: "biome is not installed" is a
+     * fact worth caching, "the probe timed out" is a moment worth retrying.
      */
     async ensureAvailable() {
-        if (this.biomeAvailable !== null)
-            return this.biomeAvailable;
+        const memo = this.availabilityLatch.read();
+        if (memo !== null)
+            return memo;
         if (this.ensureInFlight)
             return this.ensureInFlight;
         this.ensureInFlight = this.doEnsureAvailable();
@@ -114,23 +139,106 @@ export class BiomeClient {
             this.ensureInFlight = null;
         }
     }
+    /**
+     * Probe `biome --version` and classify the failure through the shared
+     * policy. Only a durable verdict (`missing` / `non-installable`) may reach
+     * the install branch of `resolveManagedToolClient`; a transient one returns
+     * as `transient`, which that seam passes straight back without installing.
+     */
+    async probeBiome() {
+        // The probe budget is enforced by a HOST-side timer, so a stalled event
+        // loop expires it while the child is still healthy. Measure the stall
+        // that overlapped the window and let the classifier see it (#1467).
+        const sampler = startHostStallSampler();
+        const startedAt = Date.now();
+        let result;
+        let hostStallMs;
+        try {
+            result = await this.spawnBiomeAsync(["--version"], PROBE_TIMEOUT_MS);
+        }
+        finally {
+            hostStallMs = sampler.stop();
+        }
+        const elapsedMs = Date.now() - startedAt;
+        if (!result.error && result.status === 0) {
+            this.lastProbeCause = "ok";
+            logAvailabilityDecision({
+                tool: "biome",
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs,
+                latched: true,
+                hostStallMs,
+                budgetMs: PROBE_TIMEOUT_MS,
+            });
+            return { outcome: "success", value: true };
+        }
+        // `unclassifiedFailureOutcome: "missing"` preserves the pre-#1476
+        // meaning of a plain non-zero exit (npx reporting no biome package):
+        // still "missing", still installable. Only the timeout/abort arm changes.
+        const { outcome, cause } = classifyProbeFailure(result, {
+            hostStallMs,
+            unclassifiedFailureOutcome: "missing",
+        });
+        // `classifyProbeFailure` is typed over the full outcome union but never
+        // returns "success" for a failed probe; narrow it for the seam's type.
+        const failureOutcome = outcome === "success" ? "non-installable" : outcome;
+        this.lastProbeCause = cause;
+        this.lastProbeElapsedMs = elapsedMs;
+        this.lastProbeHostStallMs = hostStallMs;
+        // The record is emitted by `doEnsureAvailable`, once the latch has said how
+        // long this verdict holds.
+        return { outcome: failureOutcome };
+    }
     async doEnsureAvailable() {
-        const outcome = await resolveManagedToolClient({
+        const resolved = await resolveManagedToolClient({
             toolId: "biome",
             cwd: process.cwd(),
-            probe: async () => {
-                const result = await this.spawnBiomeAsync(["--version"], 10000);
-                return !result.error && result.status === 0
-                    ? { outcome: "success", value: true }
-                    : { outcome: "missing" };
-            },
+            probe: () => this.probeBiome(),
             acceptInstalled: (installedPath) => {
                 this.autoInstalledBinaryPath = installedPath;
                 return true;
             },
         });
-        this.biomeAvailable = outcome.outcome === "success";
-        return this.biomeAvailable;
+        if (resolved.outcome === "success") {
+            this.availabilityLatch.noteAvailable();
+            // The probe itself logs a clean hit. This arm is the other way to
+            // succeed — the install repaired a durable miss — and it needs its own
+            // record, or "biome went missing and came back" reads as silence.
+            if (this.lastProbeCause !== null && this.lastProbeCause !== "ok") {
+                logAvailabilityDecision({
+                    tool: "biome",
+                    verdict: "available",
+                    outcome: "success",
+                    cause: "ok",
+                    elapsedMs: this.lastProbeElapsedMs,
+                    latched: true,
+                    hostStallMs: this.lastProbeHostStallMs,
+                    budgetMs: PROBE_TIMEOUT_MS,
+                });
+            }
+            return true;
+        }
+        // A transient probe expires; a durable verdict is remembered for the
+        // session exactly as before.
+        const cause = this.lastProbeCause ?? "not-found";
+        const retryAfterMs = this.availabilityLatch.noteUnavailable(resolved.outcome, cause);
+        logAvailabilityDecision({
+            tool: "biome",
+            verdict: "unavailable",
+            outcome: resolved.outcome,
+            cause,
+            elapsedMs: this.lastProbeElapsedMs,
+            latched: resolved.outcome !== "transient",
+            hostStallMs: this.lastProbeHostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+            budgetMs: PROBE_TIMEOUT_MS,
+        });
+        if (resolved.outcome === "transient") {
+            this.log("biome availability probe timed out; will retry (not installing)");
+        }
+        return false;
     }
     /**
      * Check if a file is supported by Biome

package/node_modules/pi-lens/dist/clients/bus-events-logger.js

@@ -1,13 +1,20 @@
 /**
  * Persistent NDJSON trace of `pi.events` bus publish attempts
  * (`pilens:files:touched` #482 / `pilens:diagnostics` #502 /
- * `pilens:format:queued` + `pilens:format:start` #673).
+ * `pilens:diagnostic:disposition` / `pilens:format:queued` +
+ * `pilens:format:start` + `pilens:autofix:start` #673/#684 /
+ * `pi-lens/analysis-complete` + `pi-lens/findings` + `pi-lens/turn-findings`
+ * #1415) — nine event names across five producers.
  *
- * All four producers (clients/bus-publish.ts, clients/diagnostics-publish.ts,
- * clients/format-events-publish.ts) are fire-and-forget: on failure or on a
- * structural no-op (never wired, kill switch off) they only invoke an
- * optional `dbg` callback, which varies by host and is a documented no-op in
- * the MCP host (clients/mcp/session.ts's `dbg: noop`). That leaves
+ * All five producers (clients/bus-publish.ts, clients/diagnostics-publish.ts,
+ * clients/disposition-publish.ts, clients/format-events-publish.ts,
+ * clients/lens-events.ts) are fire-and-forget: on failure or on a structural
+ * no-op (never wired, kill switch off) the four #482/#502/#673/#684
+ * producers only invoke an optional `dbg` callback, which varies by host and
+ * is a documented no-op in the MCP host (clients/mcp/session.ts's
+ * `dbg: noop`); `lens-events.ts` (#1415) has no `dbg` param at all — its
+ * events are purely observational inter-extension telemetry, so this NDJSON
+ * trace is its ONLY failure-visible surface. Either way, that leaves
  * bus-publish outcomes invisible in exactly the context where they matter
  * most — same failure shape as the #544 MCP session_start incident this repo
  * already fixed once.
@@ -26,6 +33,9 @@
  * spam one identical line per write batch for an entire session with zero
  * new information after the first. Both are gated log-once-per-process, the
  * same `hasLoggedFailure` shape the producers already use for emit_failed.
+ * `skipped_stale_session` is an info-level per-occurrence outcome: the emit
+ * seam intentionally declined a target whose associated ctx was confirmed
+ * stale, so it is neither a bus failure nor input for the smells rollup.
  * The empty-batch branch (`paths.length === 0` / `files.length === 0`) is
  * NOT logged at all: every call site already guards against invoking these
  * functions with nothing to report (see clients/pipeline.ts,
@@ -37,17 +47,63 @@ import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
+import { logLatency } from "./latency-logger.js";
 const BUS_EVENTS_LOG_FILE = path.join(getGlobalPiLensDir(), "bus-events.log");
 const writer = createNdjsonLogger({
     filePath: BUS_EVENTS_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,
 });
+const eventRollupCounts = new Map();
+function bumpRollupCount(event, outcome) {
+    const existing = eventRollupCounts.get(event) ?? {
+        emitted: 0,
+        skipped_stale_session: 0,
+        emit_failed: 0,
+    };
+    existing[outcome] += 1;
+    eventRollupCounts.set(event, existing);
+}
 export function logBusEvent(entry) {
+    if (entry.outcome === "emitted" ||
+        entry.outcome === "skipped_stale_session" ||
+        entry.outcome === "emit_failed") {
+        bumpRollupCount(entry.event, entry.outcome);
+    }
     if (isTestMode()) {
         return;
     }
     writer.log({ ts: new Date().toISOString(), ...entry });
 }
+/** Snapshot the current session's rollup, keyed by event name. Non-mutating —
+ *  pair with {@link resetBusEventRollupCounts} at session end. */
+export function getBusEventRollupCounts() {
+    return Object.fromEntries(eventRollupCounts);
+}
+/** Clear the rollup — call once the session-end snapshot has been logged
+ *  (or from tests) so a new session starts from zero. */
+export function resetBusEventRollupCounts() {
+    eventRollupCounts.clear();
+}
+/**
+ * Log one `session_end_bus_rollup` latency row per event NAME that had any
+ * activity this session, then clear the rollup. Called from index.ts's
+ * `session_shutdown` handler (the session-end hook this repo's other
+ * teardown work — LSP fleet shutdown, cache-prefix eviction — already runs
+ * from). A no-op (logs nothing) when nothing was ever published, matching
+ * `formatSmellsSessionStartLine`'s "no noise on an ordinary session" shape.
+ */
+export function emitBusEventRollupAtSessionEnd(cwd) {
+    for (const [event, counts] of eventRollupCounts) {
+        logLatency({
+            type: "phase",
+            phase: "session_end_bus_rollup",
+            filePath: cwd,
+            durationMs: 0,
+            metadata: { event, ...counts },
+        });
+    }
+    resetBusEventRollupCounts();
+}
 export function getBusEventsLogPath() {
     return BUS_EVENTS_LOG_FILE;
 }

package/node_modules/pi-lens/dist/clients/bus-publish.js

@@ -20,7 +20,7 @@
 import { logBusEvent } from "./bus-events-logger.js";
 import { normalizeFilePath } from "./path-utils.js";
 import { appendRecentTouches } from "./recent-touches.js";
-import { createLiveBusEmitter, recordStaleBusFailure, } from "./live-bus-emitter.js";
+import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const BUS_FILES_TOUCHED_EVENT = "pilens:files:touched";
 export const BUS_FILES_TOUCHED_VERSION = 1;
 const liveEmitter = createLiveBusEmitter();
@@ -106,8 +106,14 @@ export function publishFilesTouched(args) {
     }).catch((err) => {
         args.dbg?.(`bus-publish: recent-touches append failed: ${err}`);
     });
-    const busEmit = liveEmitter.get();
-    if (!busEmit) {
+    const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
+        event: BUS_FILES_TOUCHED_EVENT,
+        cwd: normalizeFilePath(args.cwd),
+        reason: args.reason,
+    }));
+    if (resolution.outcome === "stale-session")
+        return;
+    if (resolution.outcome === "unwired") {
         if (!hasLoggedUnwired) {
             hasLoggedUnwired = true;
             logBusEvent({
@@ -119,6 +125,7 @@ export function publishFilesTouched(args) {
         }
         return;
     }
+    const busEmit = resolution.emit;
     try {
         const payload = {
             v: BUS_FILES_TOUCHED_VERSION,
@@ -150,6 +157,7 @@ export function publishFilesTouched(args) {
             cwd: normalizeFilePath(args.cwd),
             reason: args.reason,
             error: String(err),
+            ctxSource: resolution.ctxSource,
         });
         if (!hasLoggedFailure) {
             hasLoggedFailure = true;

package/node_modules/pi-lens/dist/clients/cascade-format.js

@@ -1,10 +1,14 @@
+import { convertLspDiagnostics } from "./dispatch/utils/lsp-diagnostics.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
     const withErrors = neighbors.filter((n) => n.diagnostics.length > 0);
-    if (withErrors.length === 0)
+    const inconclusive = neighbors.filter((n) => n.inconclusive === true && n.diagnostics.length === 0);
+    if (withErrors.length === 0 && inconclusive.length === 0)
         return "";
     const noun = options.noun ?? "neighbor";
-    let out = `📐 Cascade errors in ${withErrors.length} ${noun} file(s) — fix before finishing turn:`;
+    let out = withErrors.length > 0
+        ? `📐 Cascade errors in ${withErrors.length} ${noun} file(s) — fix before finishing turn:`
+        : "";
     for (const neighbor of withErrors) {
         const display = toRunnerDisplayPath(cwd, neighbor.filePath);
         const reason = options.includeReason ? ` reason="${neighbor.reason}"` : "";
@@ -17,5 +21,56 @@ export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
         }
         out += "\n</diagnostics>";
     }
+    if (inconclusive.length > 0) {
+        if (out)
+            out += "\n";
+        out += `⚠️ Cascade diagnostics inconclusive for ${inconclusive.length} ${noun} file(s) — no clean result was confirmed:`;
+        for (const neighbor of inconclusive) {
+            out += `\n  ${toRunnerDisplayPath(cwd, neighbor.filePath)}`;
+        }
+    }
     return out;
 }
+/**
+ * Build the turn-end `CascadeRun` for a neighbour whose diagnostics landed only
+ * AFTER its cascade touch skipped the in-lane wait (#1023's `resolved-found`
+ * quiet-window outcome; #1444 made native TS7 take that same path). Returns
+ * `undefined` when there is nothing agent-facing to say — no ERROR-severity
+ * diagnostics, or nothing the formatter renders.
+ *
+ * Lives here rather than inline in the quiet-window callback so the delivery
+ * path (reconcile → run → turn_end) is testable end to end; index.ts only wires
+ * it to `runtime.appendCascadeRun`.
+ */
+export function buildResolvedFoundCascadeRun(cwd, neighbor) {
+    const { filePath } = neighbor;
+    const diagnostics = convertLspDiagnostics(neighbor.diagnostics.filter((d) => d.severity === 1), filePath, { tool: "lsp" });
+    if (diagnostics.length === 0)
+        return undefined;
+    const neighbors = [
+        { filePath, reason: "references", diagnostics, lspTouched: true },
+    ];
+    const formatted = formatCascadeNeighborDiagnostics(cwd, neighbors, {
+        noun: "cold neighbor",
+    });
+    if (!formatted)
+        return undefined;
+    return {
+        filePath,
+        result: {
+            filePath,
+            impact: {
+                filePath,
+                changedSymbols: [],
+                directImporters: [],
+                directCallers: [],
+                neighborFiles: [filePath],
+                riskFlags: [],
+            },
+            neighbors,
+            formatted,
+        },
+        neighborCount: 1,
+        diagnosticCount: diagnostics.length,
+    };
+}

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

@@ -1,7 +1,9 @@
-import { performance } from "node:perf_hooks";
 // Capture this before the guard's other module initialization so host boot is
-// not charged to extension evaluation (#1374).
-export const PI_LENS_EVAL_STARTED_MS = performance.now();
+// not charged to extension evaluation (#1374). Lives in its own
+// side-effect-free module (#1434 S3d) — see eval-timestamp.ts's docstring for
+// why: `startup-timing.ts` needs this constant but must never trigger a
+// console-guard install merely by importing it.
+import { PI_LENS_EVAL_STARTED_MS } from "./eval-timestamp.js";
 // #1333: install the console guard as an import side-effect so it runs before
 // any other module's initialization code. Installing inside the extension
 // factory is too late — by the time the factory runs, every static/transitive
@@ -10,5 +12,15 @@ export const PI_LENS_EVAL_STARTED_MS = performance.now();
 // MUST remain the first import of index.ts; the enforcement test pins that.
 // installConsoleGuard() itself is idempotent and no-ops under test mode and
 // PI_LENS_CONSOLE_GUARD=0.
-import { installConsoleGuard } from "./extension-log.js";
+// #1434: the guard captures only while pi-lens owns execution, so the module
+// window must be open for the rest of the import graph. index.ts closes it on
+// its last line; an unref'd backstop closes it if that never runs.
+import { installConsoleGuard, openModuleLoadConsoleWindow, } from "./extension-log.js";
 installConsoleGuard();
+openModuleLoadConsoleWindow();
+// Not re-exported: nothing should import the timestamp from this module.
+// `clients/startup-timing.ts` imports it straight from `eval-timestamp.ts`,
+// which is what keeps that import side-effect-free (S3d). The `void` keeps
+// the import from looking unused to lint while documenting that this module
+// only needs the ordering (evaluate eval-timestamp.ts first), not the value.
+void PI_LENS_EVAL_STARTED_MS;

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

@@ -15,6 +15,7 @@ import { createSubsystemLogger } from "./extension-log.js";
 import * as path from "node:path";
 import { findNearestMarkerRoot } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 function emptyResult(language) {
     return {
         success: false,
@@ -39,6 +40,21 @@ const VULTURE_EXCLUDES = [
     "*/__pycache__/*",
     "*/.eggs/*",
 ];
+// Decorators whose target is called by a framework, never by name in the tree.
+// vulture cannot see those call sites, so every such symbol is a permanent
+// false positive that reappears in every scan — the fastest way to teach a
+// reader to stop reading the advisory. Glob-matched by vulture itself.
+const VULTURE_IGNORE_DECORATORS = [
+    "@pytest.fixture",
+    "@pytest.fixture(*",
+    "@fixture",
+    "@fixture(*",
+    "@app.*",
+    "@router.*",
+    "@celery.task*",
+    "@task",
+    "@shared_task*",
+];
 // vulture line: `path/to/file.py:12: unused function 'foo' (60% confidence)`
 const VULTURE_LINE = /^(.*?):(\d+): unused (\w[\w ]*?) '([^']+)' \((\d+)% confidence\)\s*$/;
 /**
@@ -86,7 +102,12 @@ export function parseVultureOutput(output, root) {
 export class PythonDeadCodeClient {
     id = "python";
     language = "Python";
-    available = null;
+    /**
+     * Transient-aware memo (#1467): only a durable "vulture is not installed"
+     * verdict is remembered for the session. A probe that timed out expires and
+     * is re-probed, so vulture cannot be disabled for the process by one stall.
+     */
+    availabilityLatch = createAvailabilityLatch();
     resolved = null;
     ensureInFlight = null;
     inFlight = new Map();
@@ -103,6 +124,10 @@ export class PythonDeadCodeClient {
     detect(cwd) {
         return this.resolveProjectRoot(cwd) !== null;
     }
+    owns(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        return ext === ".py" || ext === ".pyi";
+    }
     /**
      * Nearest dir with a Python project marker, never at/above $HOME and never
      * escaping a VCS boundary — same containment rules as KnipClient so a scan
@@ -121,8 +146,9 @@ export class PythonDeadCodeClient {
         ], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
     }
     async ensureAvailable() {
-        if (this.available !== null)
-            return this.available;
+        const memo = this.availabilityLatch.read();
+        if (memo !== null)
+            return memo;
         if (this.ensureInFlight)
             return this.ensureInFlight;
         this.ensureInFlight = this.doEnsureAvailable();
@@ -146,19 +172,81 @@ export class PythonDeadCodeClient {
             { cmd: "python", prefix: ["-m", "vulture"] },
             { cmd: "python3", prefix: ["-m", "vulture"] },
         ];
+        // A timeout on ANY candidate means the machine, not the tool, answered —
+        // the run gets a bounded retry instead of a permanent skip (#1467).
+        let sawTransient = false;
+        let transientCause = "probe-timeout";
+        // Accumulated across ALL candidates, because the failure verdicts below
+        // are about the whole sweep rather than any one probe. Reporting zero
+        // here would erase the evidence that cracked #1467: four 5s probes and
+        // a stalled host look identical to an absent tool without these two
+        // numbers.
+        const sweepStartedAt = Date.now();
+        let sweepHostStallMs = 0;
         for (const c of candidates) {
-            const probe = await safeSpawnAsync(c.cmd, [...c.prefix, "--version"], {
-                timeout: 5000,
-            });
+            const sampler = startHostStallSampler();
+            const startedAt = Date.now();
+            let probe;
+            let hostStallMs;
+            try {
+                probe = await safeSpawnAsync(c.cmd, [...c.prefix, "--version"], {
+                    timeout: 5000,
+                });
+            }
+            finally {
+                hostStallMs = sampler.stop();
+                sweepHostStallMs += hostStallMs;
+            }
             if (!probe.error && probe.status === 0) {
                 this.resolved = c;
-                this.available = true;
+                this.availabilityLatch.noteAvailable();
                 this.log(`vulture found: ${[c.cmd, ...c.prefix].join(" ")}`);
+                logAvailabilityDecision({
+                    tool: "vulture",
+                    verdict: "available",
+                    outcome: "success",
+                    cause: "ok",
+                    elapsedMs: Date.now() - startedAt,
+                    latched: true,
+                    hostStallMs,
+                    budgetMs: 5000,
+                });
                 return true;
             }
+            const classified = classifyProbeFailure(probe, { hostStallMs });
+            if (classified.outcome === "transient") {
+                sawTransient = true;
+                transientCause = classified.cause;
+            }
+        }
+        if (sawTransient) {
+            const retryAfterMs = this.availabilityLatch.noteUnavailable("transient", transientCause);
+            this.log("vulture probe timed out; will retry (not treated as missing)");
+            logAvailabilityDecision({
+                tool: "vulture",
+                verdict: "unavailable",
+                outcome: "transient",
+                cause: transientCause,
+                elapsedMs: Date.now() - sweepStartedAt,
+                hostStallMs: sweepHostStallMs,
+                latched: false,
+                retryAfterMs,
+                budgetMs: 5000,
+            });
+            return false;
         }
-        this.available = false;
+        this.availabilityLatch.noteUnavailable("missing", "not-found");
         this.log("vulture not installed; skipping (no auto-install)");
+        logAvailabilityDecision({
+            tool: "vulture",
+            verdict: "unavailable",
+            outcome: "missing",
+            cause: "not-found",
+            elapsedMs: Date.now() - sweepStartedAt,
+            hostStallMs: sweepHostStallMs,
+            latched: true,
+            budgetMs: 5000,
+        });
         return false;
     }
     async analyze(cwd) {
@@ -193,6 +281,7 @@ export class PythonDeadCodeClient {
             ".",
             `--min-confidence=${this.minConfidence}`,
             `--exclude=${VULTURE_EXCLUDES.join(",")}`,
+            `--ignore-decorators=${VULTURE_IGNORE_DECORATORS.join(",")}`,
         ];
         const result = await safeSpawnAsync(invocation.cmd, args, {
             timeout: ANALYSIS_TIMEOUT_MS,
@@ -258,30 +347,46 @@ export function deadCodeIssueCount(result) {
         result.unusedDeps.length +
         result.unlistedDeps.length);
 }
+/** Every bucket flattened — delta diffing and diagnostic mapping want one list. */
+export function deadCodeIssues(result) {
+    return [
+        ...result.unusedExports,
+        ...result.unusedFiles,
+        ...result.unusedDeps,
+        ...result.unlistedDeps,
+    ];
+}
 /**
- * Format cached dead-code results into one turn_end advisory, or "" when there
- * is nothing to report. Merges multiple languages (polyglot repos) under one
- * `[Dead code]` heading so it reads consistently next to the Knip advisory.
- * Advisory-only: these are project-wide signals, never blockers.
+ * Stable identity for diffing one scan against the previous one.
+ *
+ * Deliberately excludes the line number. An edit shifts every line below it,
+ * and the delta is then filtered to exactly the files the edit touched — so a
+ * line in the key turns each shifted pre-existing finding into a "newly unused"
+ * report under a heading that blames the agent's own edit for orphaning it.
+ * Inserting four lines above one real finding produced four false ones.
  */
-export function formatDeadCodeAdvisory(results, maxPerLang = 10) {
-    const withFindings = results.filter((r) => r.success && deadCodeIssueCount(r) > 0);
-    if (withFindings.length === 0)
+export function deadCodeIssueKey(issue) {
+    return `${issue.category}:${issue.file ?? ""}:${issue.name}`;
+}
+/**
+ * Format this turn's ATTRIBUTABLE delta — symbols that became unused in files
+ * the agent just edited — or "" when there is nothing to report. Mirrors the
+ * Knip advisory's contract deliberately: the project-wide list is not injected
+ * per turn (hundreds of pre-existing findings would drown the blockers and burn
+ * context every turn), it stays available on demand via lens_diagnostics.
+ */
+export function formatDeadCodeDelta(issues, language, max = 5) {
+    if (issues.length === 0)
         return "";
-    const lines = [];
-    for (const r of withFindings) {
-        const count = deadCodeIssueCount(r);
-        lines.push(`${r.language}: ${count} unused symbol(s)`);
-        for (const issue of r.unusedExports.slice(0, maxPerLang)) {
-            const loc = issue.file
-                ? ` (${issue.file}${issue.line ? `:${issue.line}` : ""})`
-                : "";
-            lines.push(`    - unused ${issue.kind} '${issue.name}'${loc}`);
-        }
-        if (r.unusedExports.length > maxPerLang) {
-            lines.push(`    … and ${r.unusedExports.length - maxPerLang} more`);
-        }
+    let report = `💀 Newly unused ${language} symbols in files you edited — check if callers need updating (dead-code):\n`;
+    for (const issue of issues.slice(0, max)) {
+        const loc = issue.file
+            ? `${issue.file}${issue.line ? `:${issue.line}` : ""}`
+            : "(unknown)";
+        report += `  ${loc} — unused ${issue.kind} ${issue.name}\n`;
+    }
+    if (issues.length > max) {
+        report += `  … and ${issues.length - max} more\n`;
     }
-    return ("💀 [Dead code] project-wide unused symbols — verify before removing:\n  " +
-        lines.join("\n  "));
+    return report;
 }