@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

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

@@ -12,10 +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,
@@ -28,17 +33,18 @@ 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
@@ -145,13 +151,13 @@ export class PythonDeadCodeClient {
             "tox.ini",
         ], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
     }
-    async ensureAvailable() {
+    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;
         }
@@ -159,15 +165,39 @@ 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"] },
@@ -183,6 +213,10 @@ export class PythonDeadCodeClient {
         // 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 sampler = startHostStallSampler();
             const startedAt = Date.now();
@@ -213,7 +247,11 @@ export class PythonDeadCodeClient {
                 });
                 return true;
             }
-            const classified = classifyProbeFailure(probe, { hostStallMs });
+            const classified = classifyProbeFailure(probe, {
+                hostStallMs,
+                command: c.cmd,
+            });
+            sweepEvidence = classified.evidence;
             if (classified.outcome === "transient") {
                 sawTransient = true;
                 transientCause = classified.cause;
@@ -232,6 +270,8 @@ export class PythonDeadCodeClient {
                 latched: false,
                 retryAfterMs,
                 budgetMs: 5000,
+                classifiedBy: "probe",
+                ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
             });
             return false;
         }
@@ -246,6 +286,9 @@ export class PythonDeadCodeClient {
             hostStallMs: sweepHostStallMs,
             latched: true,
             budgetMs: 5000,
+            // Every candidate probe was classified, and none was transient (#1500).
+            classifiedBy: "probe",
+            ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
         });
         return false;
     }
@@ -258,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,
@@ -273,14 +316,35 @@ 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, {
@@ -299,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,
                 };
             }
@@ -357,16 +443,22 @@ export function deadCodeIssues(result) {
     ];
 }
 /**
- * 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.
+ * 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 stableFindingKey(...parts) {
+    return parts.map((part) => part ?? "").join(":");
+}
+/** Stable identity for diffing one scan against the previous one. */
 export function deadCodeIssueKey(issue) {
-    return `${issue.category}:${issue.file ?? ""}:${issue.name}`;
+    return stableFindingKey(issue.category, issue.file, issue.name);
 }
 /**
  * Format this turn's ATTRIBUTABLE delta — symbols that became unused in files

package/node_modules/pi-lens/dist/clients/deadline-utils.js

@@ -38,8 +38,15 @@ export function withDeadline(promise, options) {
     const onReject = options.onReject ?? "propagate";
     const ms = options.ms ??
         (options.deadlineAt !== undefined ? options.deadlineAt - Date.now() : 0);
-    // Past deadline / non-positive budget: settle immediately, no timer.
+    // Past deadline / non-positive budget: settle immediately, no timer. This
+    // branch returns before the race below ever runs, so — same reason as the
+    // loser-leg catch a few lines down — `promise` needs its own no-op catch
+    // here too: without it, a `promise` that eventually rejects (the caller
+    // already invoked it; this function only decides how long to wait on it)
+    // surfaces as an unhandled rejection instead of being silently superseded
+    // by the immediate timeout/undefined settlement.
     if (ms <= 0) {
+        promise.catch(() => { });
         return onTimeout === "undefined"
             ? Promise.resolve(undefined)
             : Promise.reject(new Error(`Timeout after ${Math.max(0, ms)}ms`));

package/node_modules/pi-lens/dist/clients/debug-handles.js

@@ -140,6 +140,11 @@ export function flushDebugHandlesLog() {
 }
 function safeGetActiveResourcesInfo() {
     try {
+        // SAFETY: `process.getActiveResourcesInfo` is a real Node API (>=17.3)
+        // that @types/node does not declare on `Process`. The cast only widens
+        // the type to say the method MIGHT be there; the `typeof fn ===
+        // "function"` guard on the next line is what actually decides, so a
+        // runtime without it returns [] rather than throwing.
         const fn = process.getActiveResourcesInfo;
         return typeof fn === "function" ? fn.call(process) : [];
     }

package/node_modules/pi-lens/dist/clients/degradation-ledger.js

@@ -1,11 +1,28 @@
 /** Bounded, process-local telemetry for behavior degraded during one session. */
 import { logExtension } from "./extension-log.js";
+import { LEDGER_FIELD_MAX, truncateForLedger } from "./ledger-bounds.js";
+import { logLatency } from "./latency-logger.js";
+import { getSinkWriteFailures, resetSinkWriteFailures } from "./ndjson-logger.js";
+// Re-exported so existing importers keep one name for the ledger's bound.
+export { LEDGER_FIELD_MAX, truncateForLedger };
 const ENTRIES_PER_KIND = 20;
 const MAX_DISTINCT_KINDS = 32;
 const OVERFLOW_KIND = "other";
 const groups = new Map();
 const onceKeys = new Set();
 const tallies = new Map();
+// Monotonic session-boundary counter (#1536 review F5): callers that keep
+// their OWN once-per-session latch outside the ledger (a per-instance Set
+// the ledger itself doesn't own) can compare this lazily at use time and
+// clear their latch on a mismatch — the same clear-on-transition shape as
+// project-trust.ts's trustGeneration, but keyed to the ledger's own reset
+// (resetDegradationLedger, wired into handleSessionStart) rather than a
+// trust change.
+let ledgerGeneration = 0;
+/** Current session generation. Bump on every `resetDegradationLedger()`. */
+export function getDegradationLedgerGeneration() {
+    return ledgerGeneration;
+}
 export function recordDegradation(record) {
     try {
         const kind = boundedKind(record.kind);
@@ -16,6 +33,7 @@ export function recordDegradation(record) {
             group = { count: 0, entries: [] };
             groups.set(kind, group);
         }
+        const admitted = group.entries.length < ENTRIES_PER_KIND;
         group.count += 1;
         // Bounded at RECORD time (#1366 review): reasons carry arbitrary error
         // text; a 10KB message must never become a 10KB health line or a 10KB
@@ -23,10 +41,12 @@ export function recordDegradation(record) {
         group.entries.push({ subject, reason });
         if (group.entries.length > ENTRIES_PER_KIND)
             group.entries.shift();
+        return admitted;
     }
     catch (error) {
         debugLedgerFailure("record", error);
         // Telemetry must never break the observed path.
+        return false;
     }
 }
 /** Record at most once per kind/subject during the current session. */
@@ -38,7 +58,9 @@ export function recordDegradationOnce(record) {
         if (onceKeys.has(key))
             return;
         onceKeys.add(key);
-        recordDegradation({ kind, subject, reason: record.reason });
+        if (recordDegradation({ kind, subject, reason: record.reason })) {
+            logDurableDegradation(kind, subject, 1);
+        }
     }
     catch (error) {
         debugLedgerFailure("record-once", error);
@@ -48,6 +70,14 @@ export function recordDegradationOnce(record) {
 /**
  * Count a repeated degradation while retaining one latest-reason entry per
  * kind/subject. The group count remains the exact event total.
+ *
+ * Returns `true` when this call is the FIRST occurrence recorded for this
+ * kind/subject pair (the ledger is the single source of truth for that
+ * tally already — via `tallies` — so callers that need a once-per-subject
+ * "rising edge" signal, e.g. to gate a verbose one-time log line before
+ * falling back to the bounded count, read it off this return value instead
+ * of hand-rolling their own parallel `Set`/latch). #1716 reuses this same
+ * signal to gate `navRequest`'s detailed timeout/late-answer log writes.
  */
 export function incrementDegradationCount(record) {
     try {
@@ -62,24 +92,49 @@ export function incrementDegradationCount(record) {
             group = { count: 0, entries: [] };
             groups.set(kind, group);
         }
-        group.count += 1;
-        const entry = { subject, reason: truncateForLedger(`${reason} (count: ${count})`) };
         const existing = group.entries.findIndex((candidate) => candidate.subject === subject);
+        const admitted = existing >= 0 || group.entries.length < ENTRIES_PER_KIND;
+        group.count += 1;
+        // #1816: append the count AFTER truncation, never before. `reason` is
+        // already bounded above, so re-truncating the concatenation pushed the
+        // suffix past LEDGER_FIELD_MAX and silently ate it — a 200-char reason
+        // lost the one field that says how often the degradation fired.
+        const entry = { subject, reason: `${reason} (count: ${count})` };
         if (existing >= 0)
             group.entries.splice(existing, 1);
         group.entries.push(entry);
         if (group.entries.length > ENTRIES_PER_KIND)
             group.entries.shift();
+        // Durable rows use the summary's admission and emit the first event and
+        // power-of-two milestones only, keeping the sink bounded.
+        if (admitted && isPowerOfTwo(count)) {
+            logDurableDegradation(kind, subject, count);
+        }
+        return count === 1;
     }
     catch (error) {
         debugLedgerFailure("increment", error);
         // Telemetry must never break the observed path.
+        return false;
     }
 }
-/** Detached snapshot, grouped in first-seen kind order. */
-const LEDGER_FIELD_MAX = 200;
-function normalizeForLedger(value) {
-    return String(value ?? "unknown");
+/**
+ * Persist the accepted ledger mutation through the existing rotated NDJSON
+ * latency stream. `logLatency` owns the timestamp, PID, serialization, secret
+ * redaction, and write queue. The subject and kind were already bounded by the
+ * ledger before reaching this seam.
+ */
+function logDurableDegradation(kind, subject, count) {
+    logLatency({
+        type: "phase",
+        phase: "degradation_ledger",
+        filePath: subject,
+        durationMs: 0,
+        metadata: { kind, subject, count, ledgerGeneration },
+    });
+}
+function isPowerOfTwo(value) {
+    return value > 0 && (value & (value - 1)) === 0;
 }
 function boundedKind(value) {
     const kind = truncateForLedger(value);
@@ -88,19 +143,29 @@ function boundedKind(value) {
     // Keep one slot available for all kinds beyond the cardinality bound.
     return groups.size < MAX_DISTINCT_KINDS - 1 ? kind : OVERFLOW_KIND;
 }
-function truncateForLedger(value) {
-    const text = normalizeForLedger(value);
-    return text.length > LEDGER_FIELD_MAX
-        ? `${text.slice(0, LEDGER_FIELD_MAX)}…`
-        : text;
-}
 export function getDegradationSummary() {
-    return [...groups.entries()].map(([kind, group]) => ({
+    const summary = [...groups.entries()].map(([kind, group]) => ({
         kind,
         count: group.count,
         droppedCount: group.count - group.entries.length,
         latestReasons: group.entries.map((entry) => ({ ...entry })),
     }));
+    // Folded in at read time, not written into `groups` (#1970) — see the
+    // `log-sink-write-failure` doc comment on `DegradationKind` for why this
+    // kind never goes through `recordDegradation`.
+    const sinkFailures = getSinkWriteFailures();
+    if (sinkFailures.length > 0) {
+        summary.push({
+            kind: "log-sink-write-failure",
+            count: sinkFailures.reduce((total, sink) => total + sink.droppedCount, 0),
+            droppedCount: 0,
+            latestReasons: sinkFailures.map((sink) => ({
+                subject: truncateForLedger(sink.file),
+                reason: truncateForLedger(`${sink.droppedCount} dropped write(s) after reopen-retry failed`),
+            })),
+        });
+    }
+    return summary;
 }
 function isRenderableSummary(value) {
     if (!Array.isArray(value))
@@ -148,6 +213,11 @@ export function resetDegradationLedger() {
     groups.clear();
     onceKeys.clear();
     tallies.clear();
+    ledgerGeneration++;
+    // #1970, catalog shape 17: the sink write-failure tally is a
+    // process-lifetime latch too — it re-arms alongside the rest of the
+    // ledger rather than surviving past the session that observed it.
+    resetSinkWriteFailures();
 }
 export const DEGRADATION_ENTRIES_PER_KIND = ENTRIES_PER_KIND;
 export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;

package/node_modules/pi-lens/dist/clients/demoted-finding-render.js

@@ -0,0 +1,155 @@
+/**
+ * Body degradation for a DEMOTED finding (#1944).
+ *
+ * The demotion gates (#1631 dependency-drift, #1641 past-EOF) move a record
+ * out of the authoritative blocker channel and into the advisory channel.
+ * Until this module existed they changed the CHANNEL and nothing else: the
+ * advisory embedded the blocker body verbatim, so the agent still read
+ * "🔴 STOP — 11 issue(s) must be fixed" with dead line numbers under two
+ * hedge lines it ignored. Live evidence (session 01a0234c, 2026-08-21): the
+ * agent spent four re-run detours and about 7.4k tokens on a record whose
+ * coordinates no longer existed, then explained an unrelated REAL blocker
+ * away as "mid-edit state" in the same session.
+ *
+ * The rule this module owns, once, for every gated surface: a demoted body
+ * loses its authority vocabulary and its dead coordinates, and it says so in
+ * its own words. `clients/finding-delivery-gate.ts` documents the surrounding
+ * contract; this is the one implementation of its "Demotion rendering" arm
+ * for surfaces that carry a RENDERED BODY rather than a per-diagnostic row.
+ * Per-row surfaces (`widget-state.ts`, `tools/lens-diagnostics.ts`) already
+ * swap the coordinate for `PAST_EOF_STALE_MARKER` at render time and have no
+ * body to degrade.
+ *
+ * Pure and leaf: no store, no coordinator, no I/O. The caller supplies the
+ * dead lines it already computed while deciding to demote, so this module
+ * never re-derives a verdict from rendered prose (the
+ * re-derivation-vs-correlation screen).
+ */
+/** Suffix that replaces a cited coordinate the file no longer has. */
+export const DEAD_LINE_ANNOTATION = "(line no longer exists)";
+/**
+ * Authority vocabulary a demoted body must not carry, with its degraded
+ * replacement. Ordered: the full banner rewrite runs first so the narrower
+ * fallbacks only ever see text the banner rule did not already cover.
+ *
+ * This table is the single source of truth for the rule. A surface must not
+ * hand-roll its own "strip the STOP" pass — that is how #1631, #1641, and
+ * #1664 each ended up with a different answer to the same question.
+ *
+ * POSITION-ANCHORED (#1944 review F1). These patterns run over the BANNER
+ * region only, never the whole body. Diagnostic messages are arbitrary text
+ * from arbitrary runners, and they legitimately contain both tokens: the
+ * reviewer's probe turned ts(2304) `Cannot find name 'STOP'` into `Cannot
+ * find name 'Previously flagged'`, and mangled an English "must be fixed"
+ * inside a rule message. Rewriting a finding's own words is a worse defect
+ * than the banner it was cleaning up. See `splitBannerRegion`.
+ */
+const AUTHORITY_REWRITES = [
+    [
+        /[^\S\n]*(?:🔴|⛔|❌)?[^\S\n]*STOP[^\S\n]*[—–-][^\S\n]*(\d+)[^\S\n]+issue\(s\)[^\S\n]+must be fixed:?/g,
+        "$1 issue(s) were flagged before this file changed; the coordinates below may no longer exist:",
+    ],
+    [/(?:🔴|⛔|❌)[^\S\n]*STOP\b[^\S\n]*[—–-]?/g, "Previously flagged —"],
+    [/\bSTOP\b/g, "Previously flagged"],
+    [/\bmust be fixed\b/g, "were flagged"],
+];
+/** `  L310: message` / `L310 message` at the head of a rendered row. */
+const CITED_LINE_RE = /^([^\S\n]*)L(\d+)\b/;
+/**
+ * Split a rendered body into its BANNER region and its CONTENT region
+ * (#1944 review F1).
+ *
+ * The body this module degrades is `InlineBlockerRecord.summary`, and its one
+ * producer is `formatDiagnostics(inlineBlockers, "blocking")`
+ * (`clients/dispatch/utils/format-utils.ts`), reaching the store as
+ * `dispatchResult.blockerOutput` -> `PipelineResult.inlineBlockerSummary` ->
+ * `recordInlineBlockers`. (`buildEnrichedBlockerOutput` in
+ * `clients/pipeline.ts` renders the same shape with code snippets, but it
+ * feeds the TOOL-RESULT output shown inline during the write, not this
+ * stored summary. #1944 review round: naming it here as a producer was
+ * wrong.) The shape is a header, then one `  L<n>: <message>` row per
+ * diagnostic, then indented continuations (`💡 Fix: …`) and an optional
+ * `… and N more` tail. So the first cited-line row is the boundary:
+ * everything above it is ours to rewrite, everything from it down is the
+ * findings' own words.
+ *
+ * A body with no cited row at all — `formatDiagnostics` omits `L<n>` for a
+ * lineless diagnostic — falls back to the first NON-BLANK line. Leading
+ * blanks must be skipped rather than counted (#1944 verify round, Edge-D):
+ * `formatDiagnostics` opens its output with a newline, so a naive "first
+ * line is the banner" rule degrades an empty string and leaves the real
+ * header at full authority. Production is currently saved from that only by
+ * an undocumented `.trim()` at `clients/pipeline.ts` (`inlineBlockerSummary`),
+ * and this module claims to own the rule, so it must hold on its own input.
+ */
+function splitBannerRegion(lines) {
+    const firstCitedRow = lines.findIndex((line) => CITED_LINE_RE.test(line));
+    if (firstCitedRow !== -1)
+        return { bannerEnd: firstCitedRow };
+    const firstNonBlank = lines.findIndex((line) => line.trim() !== "");
+    return { bannerEnd: firstNonBlank === -1 ? 0 : firstNonBlank + 1 };
+}
+/**
+ * Degrade one demoted finding's rendered body.
+ *
+ * Two independent transforms, deliberately separable so each can be proven by
+ * its own test (and so deleting either one reds a different assertion):
+ *
+ *   1. Authority vocabulary: the STOP banner and the "must be fixed"
+ *      imperative are rewritten to past-tense, non-directive wording.
+ *   2. Dead coordinates: every cited `L<n>` whose line the file no longer has
+ *      renders as `L<n> (line no longer exists)`. The message text stays —
+ *      demote, never drop (#1419).
+ */
+export function degradeDemotedFindingBody(summary, options = {}) {
+    const deadLines = new Set(options.deadLines ?? []);
+    let authorityMarkersRemoved = 0;
+    const sourceLines = summary.split("\n");
+    const { bannerEnd } = splitBannerRegion(sourceLines);
+    const degradedLines = sourceLines.map((line, index) => {
+        // Content rows keep every character. Only the banner region is ours.
+        if (index >= bannerEnd)
+            return line;
+        let rewritten = line;
+        for (const [pattern, replacement] of AUTHORITY_REWRITES) {
+            rewritten = rewritten.replace(pattern, (...args) => {
+                authorityMarkersRemoved += 1;
+                // Expand `$n` against this match's capture groups by hand. A nested
+                // `String.replace` with the SAME global regex would clobber the
+                // outer call's `lastIndex` mid-iteration.
+                return replacement.replace(/\$(\d)/g, (_, digit) => String(args[Number(digit)] ?? ""));
+            });
+        }
+        return rewritten;
+    });
+    let body = degradedLines.join("\n");
+    const deadLinesAnnotated = [];
+    if (deadLines.size > 0) {
+        body = degradedLines
+            .map((line) => {
+            const hit = CITED_LINE_RE.exec(line);
+            if (!hit)
+                return line;
+            const cited = Number.parseInt(hit[2] ?? "", 10);
+            if (!Number.isFinite(cited) || !deadLines.has(cited))
+                return line;
+            deadLinesAnnotated.push(cited);
+            return `${hit[1] ?? ""}L${cited} ${DEAD_LINE_ANNOTATION}${line.slice(hit[0].length)}`;
+        })
+            .join("\n");
+    }
+    return { body, authorityMarkersRemoved, deadLinesAnnotated };
+}
+/**
+ * The one-line note a surface appends when it RETIRES a demoted finding after
+ * its single degraded delivery. Rendered inside the advisory itself, so an
+ * empty advisory section can only ever mean "nothing to say" — if something
+ * was dropped, this line is in the payload (#1944 AC3).
+ */
+export function formatRetirementNote(deadLines) {
+    const cited = deadLines.length > 0
+        ? ` (cited ${deadLines.length === 1 ? "line" : "lines"} ${deadLines.join(", ")})`
+        : "";
+    return (`Retired after this delivery${cited}: the file no longer has these lines, ` +
+        "so this finding cannot be re-confirmed and will not be served again.");
+}