@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/child-unref.js

@@ -60,13 +60,24 @@ export function unrefChildAndPipes(child) {
  * here already has).
  */
 export function spawnCollectStdout(command, args, options) {
+    return spawnCollectStdoutResult(command, args, options).then((result) => result.stdout);
+}
+/**
+ * `spawnCollectStdout` plus the reason the output is what it is. Same spawn,
+ * unref, collect, settle plumbing; the only additions are an optional hard
+ * timeout and a status discriminator. Never rejects.
+ */
+export function spawnCollectStdoutResult(command, args, options, collectOptions = {}) {
     return new Promise((resolve) => {
         let settled = false;
-        const settle = (value) => {
+        let timer;
+        const settle = (result) => {
             if (settled)
                 return;
             settled = true;
-            resolve(value);
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
         };
         try {
             const child = nodeSpawn(command, args, options);
@@ -75,11 +86,48 @@ export function spawnCollectStdout(command, args, options) {
             child.stdout?.on("data", (chunk) => {
                 out += chunk.toString();
             });
-            child.once("error", () => settle(""));
-            child.once("close", () => settle(out));
+            child.once("error", (error) => settle({ stdout: "", status: "spawn-error", error }));
+            child.once("close", (code, signal) => settle(code === 0 && signal === null
+                ? { stdout: out, status: "ok" }
+                : {
+                    stdout: "",
+                    status: "exit-error",
+                    exitCode: code,
+                    exitSignal: signal,
+                }));
+            const timeoutMs = collectOptions.timeoutMs;
+            if (typeof timeoutMs === "number" && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    // Settle only AFTER the child's fate is known. Killing and
+                    // resolving in the same tick bounds the caller and abandons the
+                    // child, which is the leak this timeout exists to prevent.
+                    void terminateTimedOutChild(child, collectOptions.onTimeout).then((timeoutKill) => settle({ stdout: out, status: "timeout", timeoutKill }));
+                }, timeoutMs);
+                timer.unref();
+            }
         }
-        catch {
-            settle("");
+        catch (error) {
+            settle({ stdout: "", status: "spawn-error", error });
         }
     });
 }
+/** Run the caller's termination handler, or the bare-signal default, and
+ *  never let either throw out of the timeout path. */
+async function terminateTimedOutChild(child, onTimeout) {
+    if (onTimeout) {
+        try {
+            return await onTimeout(child);
+        }
+        catch {
+            // A handler that threw did not verify anything.
+            return "unverified";
+        }
+    }
+    try {
+        child.kill();
+    }
+    catch {
+        // best-effort — the child may already be gone
+    }
+    return "unverified";
+}

package/node_modules/pi-lens/dist/clients/code-quality-warnings.js

@@ -1,29 +1,47 @@
-import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 import { getProjectDataDir } from "./file-utils.js";
+import { normalizeMessage, stableFindingId } from "./finding-identity.js";
 import { normalizeMapKey } from "./path-utils.js";
-function normalizeMessage(message) {
-    return message.replace(/\s+/g, " ").trim().toLowerCase();
-}
-function hashText(value, length = 10) {
-    return createHash("sha256").update(value).digest("hex").slice(0, length);
-}
-function relativeFile(filePath, cwd) {
-    const rel = path.relative(cwd, filePath).replace(/\\/g, "/");
-    return rel && !rel.startsWith("..") ? rel : normalizeMapKey(filePath);
-}
+/**
+ * Report-budget precedence (#1777). A hint is an opinion; a warning is a
+ * finding. When the report is capped, warnings must be spent first, or an
+ * alphabetically-early file's hints can push every real warning out of the
+ * agent's view — the exact "hints dominate the stream" failure the hint tier
+ * exists to prevent.
+ */
+const TIER_BUDGET_ORDER = [
+    "warning",
+    "info",
+    "hint",
+];
+/** #1816: was a local `relativeFile|tool|rule|code|normalizedMessage|line`
+ * hash (raw, non-canonicalized `relativeFile`, 10-char hash), independently
+ * hand-rolled from `actionable-warnings.ts`'s twin and
+ * `diagnostic-dispositions.ts`'s canonicalizing original. Now the shared
+ * `finding-identity.js` builder (canonicalizes `cwd`/`filePath` through
+ * `normalizeMapKey`, hashes to 12 chars). No back-compat migration needed
+ * here: `cq:` ids are never a keyed lookup — `buildCodeQualityWarningsReport`
+ * regenerates the whole report fresh every turn, callers only ever cache and
+ * replay the report wholesale (`tools/lens-diagnostics.ts` reads it via
+ * `cacheManager.readCache<CodeQualityWarningsReport>`, never by `id`), and
+ * `appendCodeQualityWarningsHistory` just append-only-logs the id for
+ * observability, never look it back up. Contrast `actionable-warnings.ts`,
+ * whose `actionable-warning-state.json` DOES key a persisted suppression
+ * store on `aw:` — that one migrates. */
 function createCodeQualityWarningId(args) {
-    const parts = [
-        relativeFile(args.filePath, args.cwd),
-        args.tool ?? "",
-        args.rule ?? "",
-        String(args.code ?? ""),
-        normalizeMessage(args.message),
-        String(args.line ?? ""),
-    ];
-    return `cq:${hashText(parts.join("|"))}`;
+    return stableFindingId("cq:", {
+        cwd: args.cwd,
+        filePath: args.filePath,
+        parts: [
+            args.tool,
+            args.rule,
+            args.code,
+            normalizeMessage(args.message),
+            args.line,
+        ],
+    });
 }
 function categorize(diagnostic) {
     const haystack = `${diagnostic.tool} ${diagnostic.rule ?? ""} ${diagnostic.code ?? ""} ${diagnostic.message}`.toLowerCase();
@@ -93,11 +111,22 @@ export function buildCodeQualityWarningsReport(args) {
             continue;
         byId.set(warning.id, warning);
     }
-    const merged = [...byId.values()]
-        .sort((a, b) => a.displayPath.localeCompare(b.displayPath) ||
+    const byDisplayOrder = (a, b) => a.displayPath.localeCompare(b.displayPath) ||
         (a.line ?? 0) - (b.line ?? 0) ||
-        a.message.localeCompare(b.message))
-        .slice(0, maxWarnings);
+        a.message.localeCompare(b.message);
+    // Spend the budget tier by tier (see TIER_BUDGET_ORDER), then restore
+    // display order so the report still reads file by file, line by line.
+    const candidates = [...byId.values()].sort(byDisplayOrder);
+    const merged = [];
+    for (const tier of TIER_BUDGET_ORDER) {
+        for (const warning of candidates) {
+            if (merged.length >= maxWarnings)
+                break;
+            if (warning.severity === tier)
+                merged.push(warning);
+        }
+    }
+    merged.sort(byDisplayOrder);
     const byFile = new Map();
     for (const warning of merged) {
         const arr = byFile.get(warning.filePath) ?? [];
@@ -131,6 +160,11 @@ export function buildCodeQualityWarningsReport(args) {
         summary: {
             warnings: merged.length,
             files: files.length,
+            byTier: {
+                warning: merged.filter((w) => w.severity === "warning").length,
+                info: merged.filter((w) => w.severity === "info").length,
+                hint: merged.filter((w) => w.severity === "hint").length,
+            },
             topRules,
         },
     };
@@ -205,8 +239,26 @@ export function formatCodeQualityWarningsAdvisory(report) {
         .slice(0, 3)
         .map((entry) => `${entry.rule}×${entry.count}`)
         .join(", ");
+    // #1777: name the tiers, in the same descending-loudness order the on-demand
+    // ast-grep surface uses (`formatDiagnostics`, clients/ast-grep-client.ts).
+    // A tier with no findings is omitted rather than printed as zero.
+    const byTier = report.summary.byTier ?? { warning: 0, info: 0, hint: 0 };
+    // The line is worth its space only when a quiet tier is present; an
+    // all-warning turn already says everything in the count above.
+    const tiers = byTier.hint || byTier.info
+        ? [
+            byTier.warning ? `${byTier.warning} warning` : undefined,
+            byTier.info ? `${byTier.info} info` : undefined,
+            byTier.hint ? `${byTier.hint} hint` : undefined,
+        ]
+            .filter(Boolean)
+            .join(", ")
+        : "";
     return [
         `Code-quality warnings introduced/touched this turn: ${report.summary.warnings} across ${report.summary.files} file(s).`,
+        tiers
+            ? `By tier: ${tiers}. Hint and info are style opinions, not defects.`
+            : undefined,
         topRules ? `Top rules: ${topRules}` : undefined,
         "Details written to .pi-lens/cache/code-quality-warnings.json",
         "No action required unless you are already refactoring these areas.",

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

@@ -12,9 +12,15 @@
  * implementing DeadCodeClient and adding to getDeadCodeClients().
  */
 import { createSubsystemLogger } from "./extension-log.js";
+import { incrementDegradationCount } from "./degradation-ledger.js";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { findNearestMarkerRoot } from "./path-utils.js";
+import { getScratchTreeFnmatchPatterns } from "./scratch-tree-policy.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { firstOutputLine, spawnFailedWithNoOutput, } from "./dispatch/runners/utils/spawn-outcome.js";
+import { formatToolFailure } from "./dispatch/runners/utils/tool-failure.js";
 function emptyResult(language) {
     return {
         success: false,
@@ -27,17 +33,33 @@ function emptyResult(language) {
 }
 const ANALYSIS_TIMEOUT_MS = 30_000;
 // Directories never worth scanning for the user's own dead code.
+//
+// Single-sourced from `scratch-tree-policy.ts`'s `EXCLUDED_DIRS`-derived list
+// (#1562 sweep finding: this array had hand-drifted from `EXCLUDED_DIRS` —
+// missing `.pi`/`.claude`/`.next`/`.turbo`/etc, the same single-source-of-
+// truth defect #883 named for per-language lists). `site-packages`/`.eggs`
+// are Python-packaging-specific and have no `EXCLUDED_DIRS` counterpart (no
+// other scanner needs them), so they stay as a small local addition rather
+// than polluting the shared cross-tool list.
+const VULTURE_PYTHON_ONLY_EXCLUDES = ["*/site-packages/*", "*/.eggs/*"];
 const VULTURE_EXCLUDES = [
-    "*/.venv/*",
-    "*/venv/*",
-    "*/.tox/*",
-    "*/build/*",
-    "*/dist/*",
-    "*/node_modules/*",
-    "*/.git/*",
-    "*/site-packages/*",
-    "*/__pycache__/*",
-    "*/.eggs/*",
+    ...getScratchTreeFnmatchPatterns(),
+    ...VULTURE_PYTHON_ONLY_EXCLUDES,
+];
+// 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 +108,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 +130,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,12 +151,13 @@ export class PythonDeadCodeClient {
             "tox.ini",
         ], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
     }
-    async ensureAvailable() {
-        if (this.available !== null)
-            return this.available;
+    async ensureAvailable(root) {
+        const memo = this.availabilityLatch.read();
+        if (memo !== null)
+            return memo;
         if (this.ensureInFlight)
             return this.ensureInFlight;
-        this.ensureInFlight = this.doEnsureAvailable();
+        this.ensureInFlight = this.doEnsureAvailable(root);
         try {
             return await this.ensureInFlight;
         }
@@ -133,32 +165,131 @@ export class PythonDeadCodeClient {
             this.ensureInFlight = null;
         }
     }
-    async doEnsureAvailable() {
+    /**
+     * `<root>/.venv/bin/vulture` (and `venv`/Windows `Scripts` equivalents),
+     * checked by existence only — no spawn. A project's own venv is the vulture
+     * that project's own config and dependency set were written against; the
+     * bare `vulture`/`python -m vulture` PATH probes below only ever see
+     * whatever happens to be active in the CALLING shell, not the project's
+     * (#1731, discipline B — the same venv-first shape sqlfluff's binary
+     * resolution already uses, `runner-helpers.ts` `createVenvFinder`).
+     */
+    venvCandidates(root) {
+        const isWin = process.platform === "win32";
+        const relPaths = isWin
+            ? [
+                path.join(".venv", "Scripts", "vulture.exe"),
+                path.join("venv", "Scripts", "vulture.exe"),
+            ]
+            : [path.join(".venv", "bin", "vulture"), path.join("venv", "bin", "vulture")];
+        return relPaths
+            .map((rel) => path.join(root, rel))
+            .filter((full) => fs.existsSync(full))
+            .map((full) => ({ cmd: full, prefix: [] }));
+    }
+    async doEnsureAvailable(root) {
         // Presence-gated, NOT auto-installed. vulture is a pure-Python package
         // with no standalone binary, so "auto-install" would mean `pip install`
         // into whatever Python environment happens to be active — wrong and
         // intrusive for uv / poetry / conda / pipx users. So we only use vulture
-        // when the user already has it, probing both the `vulture` console script
-        // and `python -m vulture` (the script dir is frequently not on PATH even
-        // when the package is installed). Mirrors govulncheck's no-install gating.
+        // when the user already has it, probing the project's own venv first
+        // (#1731), then the `vulture` console script and `python -m vulture` on
+        // PATH (the script dir is frequently not on PATH even when the package
+        // is installed). Mirrors govulncheck's no-install gating.
         const candidates = [
+            ...(root ? this.venvCandidates(root) : []),
             { cmd: "vulture", prefix: [] },
             { 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;
+        /** What the last classified candidate returned (#1500 review): this was
+         * computed and thrown away, so every vulture row said "missing" with no
+         * trace of which candidate reported what. */
+        let sweepEvidence;
         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,
+                command: c.cmd,
+            });
+            sweepEvidence = classified.evidence;
+            if (classified.outcome === "transient") {
+                sawTransient = true;
+                transientCause = classified.cause;
+            }
         }
-        this.available = false;
+        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,
+                classifiedBy: "probe",
+                ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
+            });
+            return 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,
+            // Every candidate probe was classified, and none was transient (#1500).
+            classifiedBy: "probe",
+            ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
+        });
         return false;
     }
     async analyze(cwd) {
@@ -170,7 +301,7 @@ export class PythonDeadCodeClient {
                 summary: "No Python project root found; vulture skipped",
             };
         }
-        if (!(await this.ensureAvailable())) {
+        if (!(await this.ensureAvailable(root))) {
             return {
                 ...emptyResult(this.language),
                 success: true,
@@ -185,14 +316,36 @@ export class PythonDeadCodeClient {
         this.inFlight.set(key, promise);
         return promise;
     }
+    /**
+     * True when `<root>/pyproject.toml` carries a `[tool.vulture]` table.
+     * vulture's own config discovery reads that table, but CLI flags override
+     * it — passing `--min-confidence`/`--exclude` unconditionally silently
+     * overrode a project's own thresholds and ignore list (#1731, discipline A).
+     * Same shape as `hasSqlfluffConfig`/`hasMypyConfig` in `tool-policy.ts`: a
+     * plain string search, no TOML parser, matching the section header only.
+     */
+    hasProjectVultureConfig(root) {
+        try {
+            const content = fs.readFileSync(path.join(root, "pyproject.toml"), "utf-8");
+            return content.includes("[tool.vulture]");
+        }
+        catch {
+            return false;
+        }
+    }
     async runAnalyze(root) {
         const startMs = Date.now();
         const invocation = this.resolved ?? { cmd: "vulture", prefix: [] };
+        // Let the project's own [tool.vulture] config win (#1731, discipline A):
+        // vulture discovers it unaided, but these two flags override it when
+        // passed, so they are omitted whenever the project ships that table.
+        const hasConfig = this.hasProjectVultureConfig(root);
         const args = [
             ...invocation.prefix,
             ".",
-            `--min-confidence=${this.minConfidence}`,
-            `--exclude=${VULTURE_EXCLUDES.join(",")}`,
+            ...(hasConfig ? [] : [`--min-confidence=${this.minConfidence}`]),
+            ...(hasConfig ? [] : [`--exclude=${VULTURE_EXCLUDES.join(",")}`]),
+            `--ignore-decorators=${VULTURE_IGNORE_DECORATORS.join(",")}`,
         ];
         const result = await safeSpawnAsync(invocation.cmd, args, {
             timeout: ANALYSIS_TIMEOUT_MS,
@@ -210,14 +363,36 @@ export class PythonDeadCodeClient {
         }
         // vulture writes parse/usage errors to stderr and exits 1 with no
         // stdout findings; distinguish that from "found dead code" (exit 1 WITH
-        // findings on stdout).
+        // findings on stdout). #1736 sweep: the ORIGINAL guard here required
+        // non-empty stderr to call it an error, so a nonzero exit with BOTH
+        // empty stdout and empty stderr (a silent crash) still fell through to
+        // "No dead code found" -- the same empty-distinguishes-clean-from-errored
+        // gap the knip fix closes. A nonzero exit with no findings on stdout is
+        // never clean now, regardless of whether stderr said anything.
         const output = result.stdout || "";
         if (!output.trim()) {
             const stderr = (result.stderr || "").trim();
-            if (result.status !== 0 && stderr) {
+            // Same discriminator every dispatch/runners linter uses
+            // (`spawnFailedWithNoOutput`) rather than a parallel hand-rolled
+            // check (result.error is already handled above, so this reduces to
+            // the `status !== 0` half).
+            if (spawnFailedWithNoOutput(result, output)) {
+                // #1816: one shared wording, one truncation, signal named.
+                const reason = formatToolFailure({
+                    tool: "vulture",
+                    status: result.status,
+                    signal: result.signal,
+                    stderr: result.stderr,
+                });
+                this.log(reason);
+                incrementDegradationCount({
+                    kind: "runner-empty-result",
+                    subject: "vulture",
+                    reason,
+                });
                 return {
                     ...emptyResult(this.language),
-                    summary: `vulture error: ${stderr.split("\n")[0]}`,
+                    summary: stderr ? `vulture error: ${firstOutputLine(stderr)}` : reason,
                     durationMs,
                 };
             }
@@ -258,30 +433,52 @@ 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.
+ * Joins finding-identity parts into a stable key for diffing one scan
+ * against the previous one. The string-only signature is load-bearing: a
+ * line/column number cannot be passed without a compile error. An edit
+ * shifts every line below it, and a scan 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 (#1477, #1483). Shared by
+ * knip's per-turn delta in runtime-turn.ts so the rule lives in one place.
  */
-export function formatDeadCodeAdvisory(results, maxPerLang = 10) {
-    const withFindings = results.filter((r) => r.success && deadCodeIssueCount(r) > 0);
-    if (withFindings.length === 0)
+export function stableFindingKey(...parts) {
+    return parts.map((part) => part ?? "").join(":");
+}
+/** Stable identity for diffing one scan against the previous one. */
+export function deadCodeIssueKey(issue) {
+    return stableFindingKey(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;
 }