@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

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/child-unref.js

@@ -0,0 +1,85 @@
+/**
+ * Shared plumbing for best-effort, fire-and-forget child-process spawns
+ * (shape 4 of the recurring-defect catalog in AGENTS.md: "a timer / promise /
+ * worker / child that outlives its one-shot settle"). Extracted from the
+ * orphan reaper's `unrefReaperChild`/`spawnCollectStdout` (#1153/#1160) into a
+ * shared, dependency-free module so every one-shot
+ * `spawn(..., { stdio: ["ignore","pipe",...] })` call site in the codebase —
+ * the reaper's enumeration/kill spawns AND the resource sampler's Windows
+ * CIM/powershell spawns (#1155) — uses the exact same unref+collect shape
+ * instead of re-deriving it (also closes the #1155 PR's SonarCloud
+ * new-code-duplication finding: two near-identical spawn→collect-stdout
+ * blocks in `clients/resource-sampler.ts` collapsed to one shared helper).
+ *
+ * Deliberately has NO imports beyond `node:child_process` types, so both
+ * `clients/instance-reaper.ts` and `clients/resource-sampler.ts` (which
+ * `clients/safe-spawn.ts` itself depends on) can import this without risking
+ * a circular-import chain.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+/**
+ * Detach a best-effort, fire-and-forget child process from the event loop.
+ *
+ * A piped, `data`-listener-attached stdout/stderr/stdin stream keeps the libuv
+ * loop REFERENCED even after `child.unref()` — the child handle and every
+ * live stdio stream must all be unref'd, or a settled one-shot process (e.g.
+ * `pi --print`) cannot exit until the child `close`s. Unref only means "do
+ * not keep the process alive FOR this best-effort work": in an interactive/
+ * long-lived session the loop stays referenced for other reasons, so the
+ * child's `data`/`close` events still fire normally and callers still collect
+ * output/usage; only a genuinely-settled one-shot is allowed to exit without
+ * waiting for it. Never throws.
+ */
+export function unrefChildAndPipes(child) {
+    try {
+        child.unref();
+        // Child stdio pipes are `net.Socket`s at runtime (which expose `unref`),
+        // but are typed as `Readable`/`Writable` (which do not) — cast to the
+        // optional-`unref` shape and guard, so an un-piped ("ignore") stream is a
+        // no-op rather than a crash.
+        for (const stream of [child.stdout, child.stderr, child.stdin]) {
+            stream?.unref?.();
+        }
+    }
+    catch {
+        // best-effort — unref must never throw out of a fire-and-forget spawn
+    }
+}
+/**
+ * Spawn a best-effort, fire-and-forget child, accumulate its full stdout, and
+ * resolve with the collected text (empty string on a synchronous spawn
+ * failure or an `error` event). Consolidates the spawn → unref →
+ * pipe-stdout → `close` plumbing shared by every one-shot OS-process-table
+ * query in the codebase — each caller supplies only its command/args/options
+ * and does its own output parse. The child + its stdio pipes are `unref`'d
+ * here (via `unrefChildAndPipes`) so a settled one-shot `pi --print` process
+ * can exit without waiting, and both the unref and the collect plumbing live
+ * in exactly ONE place rather than being re-derived at each spawn site.
+ * Never rejects — any failure resolves to `""`, which every caller's parse
+ * turns into an empty/absent result (the best-effort contract every caller
+ * here already has).
+ */
+export function spawnCollectStdout(command, args, options) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        try {
+            const child = nodeSpawn(command, args, options);
+            unrefChildAndPipes(child);
+            let out = "";
+            child.stdout?.on("data", (chunk) => {
+                out += chunk.toString();
+            });
+            child.once("error", () => settle(""));
+            child.once("close", () => settle(out));
+        }
+        catch {
+            settle("");
+        }
+    });
+}

package/node_modules/pi-lens/dist/clients/codebase-model.js

@@ -13,18 +13,25 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
+import { writeFileAtomic } from "./atomic-write.js";
+import { parseSymbolKey } from "./call-graph.js";
+import { detectFileRole } from "./file-role.js";
+import { isExternalOrVendorFile } from "./path-utils.js";
+import { isBuildArtifact } from "./source-filter.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
-const DEFAULT_TOKEN_BUDGET = 1500;
+export const DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET = 1500;
 const MAX_CALLS_PER_SYMBOL = 10;
 const MIN_IN_DEGREE = 0.5; // skip symbols with low centrality (avoids noise)
+/** Persisted model schema version. Bump when the persisted shape changes. */
+export const CODEBASE_MODEL_VERSION = 1;
 // ── Builder ───────────────────────────────────────────────────────────────────
 function inferKind(symbolKey) {
-    const name = symbolKey.split(":").pop() ?? "";
-    if (/^[A-Z]/.test(name))
+    const parsed = parseSymbolKey(symbolKey);
+    if (parsed.kind === "class")
         return "class";
-    if (name.includes("."))
+    if (parsed.kind === "method" || parsed.symbolName?.includes("."))
         return "method";
-    return "function";
+    return /^[A-Z]/.test(parsed.symbolName ?? "") ? "class" : "function";
 }
 function estimateTokens(entry) {
     const text = [
@@ -45,7 +52,15 @@ function estimateTokens(entry) {
  * @param cwd     Project root — used to compute relative file paths.
  * @param budget  Maximum total token budget (default 1500).
  */
-export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
+export function buildCodebaseModel(graph, cwd, budget = DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET, identity) {
+    // Standalone callers may build an unpersisted projection without the
+    // review-graph coordinator. Persisted/session models pass the canonical
+    // review-graph identity explicitly; this fallback is only a local call-graph
+    // identity for builder-only use.
+    const modelIdentity = identity ?? {
+        reviewGraphVersion: graph.builtAt || "call-graph-unknown",
+        reviewGraphSignature: graph.builtAt || "call-graph-unknown",
+    };
     // Sort all callee keys by in-degree descending
     const ranked = [...graph.inDegree.entries()]
         .filter(([, score]) => score >= MIN_IN_DEGREE)
@@ -56,16 +71,16 @@ export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
     for (const [calleeKey, inDegree] of ranked) {
         if (totalTokens >= budget)
             break;
-        const parts = calleeKey.split(":");
-        const name = parts.pop() ?? calleeKey;
-        const filePath = parts.join(":");
-        // Skip if file is in test/node_modules/generated directories
-        if (filePath.includes("node_modules") ||
-            filePath.includes(".test.") ||
-            filePath.includes(".spec.") ||
-            filePath.includes("/__tests__/") ||
-            filePath.includes("/dist/") ||
-            filePath.includes("/generated/")) {
+        const parsedCallee = parseSymbolKey(calleeKey);
+        const name = parsedCallee.symbolName ?? calleeKey;
+        const filePath = parsedCallee.filePath;
+        // Keep this projection aligned with the shared file-role policy. The
+        // call graph is derived from the canonical review graph, so the model
+        // carries that graph's identity rather than inventing a second freshness
+        // policy.
+        const fileRole = detectFileRole(filePath);
+        if (fileRole === "test" || fileRole === "generated" ||
+            isExternalOrVendorFile(filePath, cwd) || isBuildArtifact(filePath)) {
             continue;
         }
         // Deduplicate by name when the same function appears in multiple files
@@ -73,11 +88,11 @@ export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
             continue;
         seenNames.add(name);
         const calls = [...(graph.callees.get(calleeKey) ?? new Set())]
-            .map((k) => k.split(":").pop() ?? k)
+            .map((k) => parseSymbolKey(k).symbolName ?? k)
             .filter(Boolean)
             .slice(0, MAX_CALLS_PER_SYMBOL);
         const calledBy = [...(graph.callers.get(calleeKey) ?? new Set())]
-            .map((k) => k.split(":").pop() ?? k)
+            .map((k) => parseSymbolKey(k).symbolName ?? k)
             .filter((n) => !n.startsWith("file:"))
             .slice(0, MAX_CALLS_PER_SYMBOL);
         const file = filePath
@@ -98,9 +113,12 @@ export function buildCodebaseModel(graph, cwd, budget = DEFAULT_TOKEN_BUDGET) {
         totalTokens += tokens;
     }
     const allFiles = new Set([...graph.callers.keys(), ...graph.callees.keys()]
-        .map((k) => k.split(":").slice(0, -1).join(":"))
+        .map((k) => parseSymbolKey(k).filePath)
         .filter(Boolean));
     return {
+        version: CODEBASE_MODEL_VERSION,
+        reviewGraphVersion: modelIdentity.reviewGraphVersion,
+        reviewGraphSignature: modelIdentity.reviewGraphSignature,
         generatedAt: new Date().toISOString(),
         totalSymbols: graph.inDegree.size,
         totalFiles: allFiles.size,
@@ -119,16 +137,27 @@ export function saveCodebaseModel(cwd, model) {
     const cacheFile = cacheFilePath(cwd);
     try {
         fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
-        fs.writeFileSync(cacheFile, JSON.stringify(model), "utf-8");
-        fs.writeFileSync(metaFilePath(cwd), JSON.stringify({ savedAt: new Date().toISOString(), entryCount: model.entries.length, totalTokens: model.totalTokens }), "utf-8");
+        writeFileAtomic(cacheFile, JSON.stringify(model));
+        writeFileAtomic(metaFilePath(cwd), JSON.stringify({ savedAt: new Date().toISOString(), entryCount: model.entries.length, totalTokens: model.totalTokens }));
     }
     catch {
         // Non-fatal — next session rebuilds.
     }
 }
-export function loadCodebaseModel(cwd) {
+/** Load only a model matching the canonical identity it was derived from. */
+export function loadCodebaseModel(cwd, expectedIdentity) {
     try {
-        return JSON.parse(fs.readFileSync(cacheFilePath(cwd), "utf-8"));
+        const raw = JSON.parse(fs.readFileSync(cacheFilePath(cwd), "utf-8"));
+        if (raw.version !== CODEBASE_MODEL_VERSION ||
+            typeof raw.reviewGraphVersion !== "string" || raw.reviewGraphVersion.length === 0 ||
+            typeof raw.reviewGraphSignature !== "string" || raw.reviewGraphSignature.length === 0 ||
+            typeof raw.generatedAt !== "string" ||
+            !Array.isArray(raw.entries))
+            return undefined;
+        if (raw.reviewGraphVersion !== expectedIdentity.reviewGraphVersion ||
+            raw.reviewGraphSignature !== expectedIdentity.reviewGraphSignature)
+            return undefined;
+        return raw;
     }
     catch {
         return undefined;

package/node_modules/pi-lens/dist/clients/collateral-test-role.js

@@ -0,0 +1,40 @@
+/**
+ * Shared test-role predicate for COLLATERAL cascade/impact surfaces (#1080).
+ *
+ * The review graph is already tests-free (`review-graph/builder.ts` applies
+ * `detectFileRole(file) !== "test"` at its walk/incremental chokepoints), but
+ * several collateral surfaces re-derive neighbors from OTHER sources that never
+ * saw that filter — LSP reference expansion, module-level downstream expansion,
+ * the reverse-dependency index, and the passive-diagnostics fallback — so an
+ * unignored `*.test.*` / `tests/` file can still leak into cascade neighbor
+ * output, the formatted impact header/counts, the turn-end call-graph advisory,
+ * and the persisted call-graph-impact diagnostics.
+ *
+ * This composes the SINGLE existing structural classifier (`detectFileRole`) —
+ * no second matcher, no private test-filename list, no duplicated patterns. The
+ * project ignore matcher (`getProjectIgnoreMatcher`) is applied separately and
+ * unchanged at each surface; this predicate only adds the test-ROLE half of the
+ * display policy the review graph already enforces.
+ *
+ * Honesty (#1080 acceptance criteria):
+ *  - A KNOWN `"test"` role is filtered from the collateral surface.
+ *  - If role classification cannot be obtained (an unexpected throw), the
+ *    candidate is RETAINED (`false`) rather than dropped — filtering must never
+ *    invent a heuristic or silently drop a potentially actionable file, and must
+ *    never convert an incomplete/indeterminate computation into a clean result.
+ */
+import { detectFileRole } from "./file-role.js";
+/**
+ * True when `filePath` is a KNOWN test-role file that must not surface as a
+ * collateral cascade/impact neighbor. Path-based only (no content needed for
+ * the test-role branch of `detectFileRole`). Fail-open: any classifier error
+ * returns `false` (retain the candidate).
+ */
+export function isTestRoleCollateral(filePath) {
+    try {
+        return detectFileRole(filePath) === "test";
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -10,6 +10,7 @@
  * maintainability index (Halstead-free), LOC/comments, code entropy, and AI-slop
  * indicators. These are silent metrics surfaced in the session summary.
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { firstChildOfType, withTreeSitterRoot, resolveTreeSitterLanguage, walk, } from "./tree-sitter-shared.js";
@@ -371,7 +372,7 @@ export class ComplexityClient {
     log;
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[complexity] ${msg}`)
+            ? createSubsystemLogger("complexity")
             : () => { };
     }
     /** True if the file's grammar has a complexity node mapping. */

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

@@ -0,0 +1,26 @@
+// Capture this before the guard's other module initialization so host boot is
+// 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
+// import has already evaluated, so a dependency writing to console during
+// module init would still hit the TUI raw (#1338 review finding). This module
+// 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.
+// #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/cooperative-budget.js

@@ -0,0 +1,42 @@
+/** Monotonic cooperative-work budgeting for event-loop-sensitive bulk work. */
+export function createDeadline(budgetMs) {
+    const boundedBudget = Math.max(0, budgetMs);
+    let startedAt = performance.now();
+    return {
+        expired: () => performance.now() - startedAt >= boundedBudget,
+        reset: () => {
+            startedAt = performance.now();
+        },
+    };
+}
+export async function yieldIfOverBudget(deadline) {
+    if (!deadline.expired())
+        return false;
+    await new Promise((resolve) => setImmediate(resolve));
+    deadline.reset();
+    return true;
+}
+export async function forEachCooperatively(items, fn, options) {
+    const deadline = createDeadline(options.budgetMs);
+    const assertContinuing = () => {
+        if (options.shouldContinue?.() === false) {
+            throw new Error(options.abortMessage ?? "cooperative work superseded");
+        }
+    };
+    let index = 0;
+    for (const item of items) {
+        // Check before each unit: this per-unit check is what bounds abort
+        // latency (one work unit, not an iteration checkpoint). The post-yield
+        // check below only matters after the final unit's yield, so superseded
+        // work is reported aborted rather than completed.
+        assertContinuing();
+        const result = fn(item, index++);
+        if (result !== undefined &&
+            typeof result.then === "function") {
+            await result;
+        }
+        if (deadline.expired() && (await yieldIfOverBudget(deadline))) {
+            assertContinuing();
+        }
+    }
+}

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

@@ -11,9 +11,11 @@
  * Phase 1 ships Python via `vulture`. Future phases add Go/Rust/etc. by
  * implementing DeadCodeClient and adding to getDeadCodeClients().
  */
+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,
@@ -38,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*$/;
 /**
@@ -85,14 +102,19 @@ 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();
     log;
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[dead-code:python] ${msg}`)
+            ? createSubsystemLogger("dead-code:python")
             : () => { };
     }
     get minConfidence() {
@@ -102,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
@@ -120,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();
@@ -145,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) {
@@ -192,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,
@@ -257,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;
 }