pi-lens 4.2.1 → 4.4.0

package/dist/clients/deferred-lsp-work.js

@@ -1,106 +0,0 @@
-/**
- * The one owner of "work that keeps talking to the LSP service after the hook
- * that started it has returned" (#2504 review round 2, F3).
- *
- * #2504 moved the cold-cache actionable-warnings fresh-pull loop off the
- * awaited `turn_end` hook. That loop then had effectively ONE bound: it
- * captured the COMPLETED turn's `ctx.signal` — which `index.ts` clears from
- * the ambient slot in its `finally`, so it can never fire — plus a 60 s wall
- * deadline checked only BETWEEN files. A wedged `getDiagnostics` was therefore
- * unbounded, the loop kept opening files (and could re-spawn servers) after
- * `turn_end` returned and after the LSP idle reset, a `session_shutdown`
- * landing mid-loop hit the #234 spawn-at-teardown shape, and the handle was a
- * module-level `let` with no reset that a second deferral simply overwrote.
- *
- * This module supplies the missing halves: ONE registered handle (held by
- * whichever deferral got there first, released when its work settles — see
- * `armDeferredLspWork`) and ONE abort signal that
- * `resetLSPService` fires — the single choke point through which
- * `session_shutdown`, `session_start` and the idle reset all retire the
- * service, so no caller has to remember to wire each lifecycle event
- * separately. Aborting only ever settles a promise; it never spawns, which is
- * what AGENTS.md's #234 teardown rule requires of anything reachable from
- * `session_shutdown`.
- *
- * Deliberately a zero-dependency leaf, for the same reason
- * `map-with-concurrency.ts` is one: `clients/lsp/index.ts` must not gain an
- * import edge to `actionable-warnings.ts` (and through it `lsp/edits.ts`,
- * `lsp-mutation.ts`, the durable store …) for a 20-line handle registry.
- */
-let deferredController;
-let deferredWork;
-/**
- * Abort the in-flight deferred LSP work, if any, and drop the slot.
- *
- * Safe at teardown: it settles a promise and spawns nothing. Idempotent — a
- * second call with no armed work is a no-op.
- */
-export function abortDeferredLspWork(reason) {
-    const controller = deferredController;
-    deferredController = undefined;
-    deferredWork = undefined;
-    controller?.abort(new Error(reason));
-}
-/**
- * Claim the deferred-work slot, or `undefined` when an incumbent still holds
- * it. THE INCUMBENT WINS (#2504 review round 3, F-A(d)).
- *
- * Round 2 had arming ABORT the previous deferral, reasoning that two loops
- * must not run concurrently against one LSP service. The first half of that is
- * right and still holds — there is exactly one slot. The second half was
- * backwards about which loop to keep. A deferral is armed by a turn that
- * primed NO LSP cache, which in a live editing session is every turn; so every
- * turn cancelled its predecessor, and an aborted loop publishes nothing by
- * design (its service is presumed gone). Back-to-back editing turns therefore
- * delivered NOTHING AT ALL — the exact delivery AC #2504 exists to preserve.
- *
- * Keeping the incumbent inverts that: the loop that is already talking to the
- * service runs to completion and publishes, and the newcomer is declined and
- * says so out loud. The cost is stated rather than silent — the declining
- * turn's cold files go unchecked on this channel until a later turn defers.
- *
- * Declining cannot latch. `registerDeferredLspWork` releases the slot the
- * moment the work settles, and the loop itself is bounded twice over
- * (`ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS` between files, a per-round-trip
- * timeout inside them), so an incumbent always yields the slot in bounded
- * time. Teardown is unaffected: `abortDeferredLspWork` still evicts the
- * incumbent unconditionally, which is how `resetLSPService` retires it.
- */
-export function armDeferredLspWork() {
-    if (isDeferredLspWorkArmed())
-        return undefined;
-    const controller = new AbortController();
-    deferredController = controller;
-    deferredWork = undefined;
-    return controller.signal;
-}
-/**
- * Register the armed work's promise so callers (and tests) have something to
- * await. Ignored when the slot has already been re-armed or aborted since — a
- * late registration must not resurrect a retired handle.
- *
- * Registration also arranges the RELEASE (#2504 review round 3, F-A(d)):
- * because the slot now turns a newcomer away rather than evicting the
- * incumbent, something has to hand it back, and the only correct moment is
- * when the work settles. Guarded on identity, so a slot re-armed or aborted in
- * the meantime is never cleared by a stale finalizer.
- */
-export function registerDeferredLspWork(signal, work) {
-    if (deferredController?.signal !== signal)
-        return;
-    deferredWork = work;
-    void work.finally(() => {
-        if (deferredController?.signal !== signal)
-            return;
-        deferredController = undefined;
-        deferredWork = undefined;
-    });
-}
-/** The in-flight deferred work, or an already-resolved promise when idle. */
-export function awaitDeferredLspWork() {
-    return deferredWork ?? Promise.resolve();
-}
-/** True while a deferral holds the slot and has not been aborted. */
-export function isDeferredLspWorkArmed() {
-    return deferredController?.signal.aborted === false;
-}

package/dist/clients/degradation-ledger.js

@@ -1,396 +0,0 @@
-/** Bounded, process-local telemetry for behavior degraded during one session. */
-import { logExtension } from "./extension-log.js";
-import { DEGRADATION_ENTRIES_PER_KIND, LEDGER_FIELD_MAX, truncateForLedger, } from "./ledger-bounds.js";
-import { logLatency } from "./latency-logger.js";
-import { getSinkRotations, getSinkOptionConflicts, getSinkWriteFailures, resetSinkRotations, resetSinkWriteFailures, } from "./ndjson-logger.js";
-// #2146: pulled at READ time, never pushed. `process-singletons.ts` is a
-// dependency leaf on purpose — it cannot import this module without closing a
-// no-client-cycles cycle through instance-registry/instance-reaper — so the
-// ledger reaches IN for its reset log, the same inversion `getSinkWriteFailures`
-// above uses.
-import { getProcessSingletonResets, PROCESS_SINGLETON_RESET_KIND, } from "./process-singletons.js";
-// #2506: same inversion, same reason — the log-dir resolver cannot import this
-// module (directly OR dynamically). THIS module is on a no-client-cycles cycle
-// via extension-log.ts; the resolver's whole correctness argument is that it
-// sits off every cycle, so an edge in that direction would put it back on one.
-// `getGlobalPiLensLogDir()`'s probe-home-redirect event is therefore written
-// into `probe-home-state.ts` and read back here instead. See that module's doc
-// comment for the full account.
-import { getProbeHomeRedirectEvent } from "./probe-home-state.js";
-// Re-exported so existing importers keep one name for the ledger's bound.
-export { LEDGER_FIELD_MAX, truncateForLedger };
-const ENTRIES_PER_KIND = DEGRADATION_ENTRIES_PER_KIND;
-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);
-        const subject = truncateForLedger(record.subject);
-        const reason = truncateForLedger(record.reason);
-        let group = groups.get(kind);
-        if (!group) {
-            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
-        // retained string.
-        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. */
-export function recordDegradationOnce(record) {
-    try {
-        const kind = boundedKind(record.kind);
-        const subject = truncateForLedger(record.subject);
-        const key = `${kind}\0${subject}`;
-        if (onceKeys.has(key))
-            return;
-        onceKeys.add(key);
-        if (recordDegradation({ kind, subject, reason: record.reason })) {
-            logDurableDegradation(kind, subject, 1, record.metadata, record.code);
-        }
-    }
-    catch (error) {
-        debugLedgerFailure("record-once", error);
-        // Telemetry must never break the observed path.
-    }
-}
-/**
- * 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 {
-        const kind = boundedKind(record.kind);
-        const subject = truncateForLedger(record.subject);
-        const reason = truncateForLedger(record.reason);
-        const key = `${kind}\0${subject}`;
-        const count = (tallies.get(key) ?? 0) + 1;
-        tallies.set(key, count);
-        let group = groups.get(kind);
-        if (!group) {
-            group = { count: 0, entries: [] };
-            groups.set(kind, group);
-        }
-        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, record.metadata, record.code);
-        }
-        return count === 1;
-    }
-    catch (error) {
-        debugLedgerFailure("increment", error);
-        // Telemetry must never break the observed path.
-        return false;
-    }
-}
-/**
- * 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, metadata, code) {
-    const boundedMetadata = boundLedgerMetadata(metadata);
-    logLatency({
-        type: "phase",
-        phase: "degradation_ledger",
-        filePath: subject,
-        durationMs: 0,
-        metadata: {
-            ...boundedMetadata,
-            kind,
-            subject,
-            count,
-            ledgerGeneration,
-            // Reserved row field, written AFTER the bounded caller metadata so the
-            // `MAX_METADATA_KEYS` cap cannot evict the stable code (#2418).
-            ...(code ? { code } : {}),
-        },
-    });
-}
-const MAX_METADATA_KEYS = 8;
-function boundLedgerMetadata(metadata) {
-    if (!metadata)
-        return {};
-    const entries = Object.entries(metadata);
-    const kept = entries.slice(0, MAX_METADATA_KEYS);
-    const bounded = Object.fromEntries(kept.map(([key, value]) => [key, truncateForLedger(value)]));
-    const dropped = entries.length - kept.length;
-    if (dropped > 0)
-        bounded.metadataDropped = dropped;
-    return bounded;
-}
-function isPowerOfTwo(value) {
-    return value > 0 && (value & (value - 1)) === 0;
-}
-function boundedKind(value) {
-    const kind = truncateForLedger(value);
-    if (groups.has(kind) || kind === OVERFLOW_KIND)
-        return kind;
-    // Keep one slot available for all kinds beyond the cardinality bound.
-    return groups.size < MAX_DISTINCT_KINDS - 1 ? kind : OVERFLOW_KIND;
-}
-export function getDegradationSummary() {
-    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`),
-            })),
-        });
-    }
-    // #2505, same read-time fold: a mid-session rotation is visible without
-    // this module writing about it through the very sink family it is
-    // reporting on — see the `log-sink-rotated` doc comment on
-    // `DegradationKind`.
-    const sinkRotations = getSinkRotations();
-    const rotated = sinkRotations.filter((sink) => sink.rotationCount > 0);
-    if (rotated.length > 0) {
-        summary.push({
-            kind: "log-sink-rotated",
-            count: rotated.reduce((total, sink) => total + sink.rotationCount, 0),
-            droppedCount: 0,
-            latestReasons: rotated.map((sink) => ({
-                subject: truncateForLedger(sink.file),
-                reason: truncateForLedger(`${sink.rotationCount} rotation(s) at the configured byte bound`),
-            })),
-        });
-    }
-    // A rotation the writer ATTEMPTED and could not complete is a different
-    // fact from a rotation that happened, and the only signal that a sink is
-    // growing past its bound right now (#2505 review F2).
-    const rotateFailed = sinkRotations.filter((sink) => sink.failureCount > 0);
-    if (rotateFailed.length > 0) {
-        summary.push({
-            kind: "log-sink-rotate-failed",
-            count: rotateFailed.reduce((total, sink) => total + sink.failureCount, 0),
-            droppedCount: 0,
-            latestReasons: rotateFailed.map((sink) => ({
-                subject: truncateForLedger(sink.file),
-                reason: truncateForLedger(`${sink.failureCount} failed rotation attempt(s); this sink is growing past its byte bound`),
-            })),
-        });
-    }
-    const optionConflicts = getSinkOptionConflicts();
-    if (optionConflicts.length > 0) {
-        summary.push({
-            kind: "log-sink-option-conflict",
-            count: optionConflicts.length,
-            droppedCount: 0,
-            latestReasons: optionConflicts.map((sink) => ({
-                subject: truncateForLedger(sink.file),
-                reason: truncateForLedger("shared writer rotation options differed across module graphs; first writer retained ownership"),
-            })),
-        });
-    }
-    // #2146, same read-time fold: process-singleton resets live in the leaf
-    // module's own bounded log. One entry per family, so this group's count is
-    // the number of families this build could not adopt, never an event tally.
-    const singletonResets = getProcessSingletonResets();
-    if (singletonResets.length > 0) {
-        summary.push({
-            kind: PROCESS_SINGLETON_RESET_KIND,
-            count: singletonResets.length,
-            droppedCount: 0,
-            latestReasons: singletonResets.map((reset) => ({
-                subject: truncateForLedger(reset.family),
-                reason: truncateForLedger(reset.reason),
-            })),
-        });
-    }
-    // #2506, same read-time fold: `getGlobalPiLensLogDir()`'s probe-home redirect
-    // fires at most once per process (see `probe-home-state.ts`), so this is a
-    // presence check, not a tally.
-    const probeHomeRedirect = getProbeHomeRedirectEvent();
-    if (probeHomeRedirect) {
-        summary.push({
-            kind: "global-dir-probe-redirect",
-            count: 1,
-            droppedCount: 0,
-            latestReasons: [
-                {
-                    subject: truncateForLedger(probeHomeRedirect.probeHome),
-                    reason: truncateForLedger(`PI_LENS_HOME unset with cwd in an agent worktree/tmp probe context (${probeHomeRedirect.cwd}), or PILENS_PROBE=1 forced it; LOGS redirected away from the real home directory (tools, bin and instances.json are unaffected)`),
-                },
-            ],
-        });
-    }
-    return summary;
-}
-function isRenderableSummary(value) {
-    if (!Array.isArray(value))
-        return false;
-    return value.every((group) => {
-        if (group === null || typeof group !== "object")
-            return false;
-        const candidate = group;
-        return (typeof candidate.kind === "string" &&
-            typeof candidate.count === "number" &&
-            Array.isArray(candidate.latestReasons) &&
-            candidate.latestReasons.every((entry) => entry !== null &&
-                typeof entry === "object" &&
-                typeof entry.subject === "string" &&
-                typeof entry.reason === "string"));
-    });
-}
-/**
- * Kinds that record something the system did ON PURPOSE, correctly, and
- * that a reader only needs a tally of — never a call to action (#2505
- * review). A routine log rotation at the configured bound is the writer
- * working as designed; giving it the same warning marker a real
- * degradation gets trains the reader to ignore the marker. The FAILED
- * rotation is the line that has to stand out, so it is deliberately NOT
- * in this set.
- */
-const INFORMATIONAL_DEGRADATION_KINDS = new Set([
-    "log-sink-rotated",
-    // #2504 review round 8 (S1): both fire on the ordinary re-edit cadence
-    // (a carry-forward window closing, or a session boundary) and are
-    // self-healing -- the next turn's analysis or deferral re-observes the
-    // file -- so a `⚠` overstates them the same way a routine log rotation
-    // would.
-    "actionable-warnings-inband-superseded",
-    "actionable-warnings-deferred-superseded",
-    // #2523: a hook await abandoned because the session is tearing down. The
-    // teardown signal firing is the design working, so it is a tally; the
-    // BUDGET blow-out (`hook-await-exceeded`) is the line that has to stand
-    // out, and a caller's own Escape records nothing at all.
-    "hook-await-abandoned",
-    // #2524: can fire on a query that ultimately settles `ok` (see the kind's
-    // doc comment above) and is frequent/self-healing by design — a `⚠` would
-    // cry wolf on the sampler's ordinary best-effort data loss.
-    "resource-sampler-scanner-escalated",
-    // #2874: a successful legacy-directory migration is an upgrade tally, not
-    // a call to action. The hash-only subject avoids exposing the project path.
-    "data_dir_migrated",
-]);
-export function renderDegradationLines(summary = getDegradationSummary()) {
-    if (!isRenderableSummary(summary))
-        return [];
-    if (summary.length === 0)
-        return [];
-    return [
-        "Degradations:",
-        ...summary.map((group) => {
-            if (INFORMATIONAL_DEGRADATION_KINDS.has(group.kind)) {
-                return `  ${group.kind}: ${group.count}`;
-            }
-            const latest = group.latestReasons.at(-1);
-            return `  ⚠ ${group.kind}: ${group.count}${latest ? ` — ${latest.subject}: ${latest.reason}` : ""}`;
-        }),
-    ];
-}
-function debugLedgerFailure(operation, error) {
-    try {
-        logExtension({
-            subsystem: "degradation-ledger",
-            level: "debug",
-            message: `${operation} failed: ${error instanceof Error ? error.message : String(error)}`,
-        });
-    }
-    catch {
-        // Debug logging must not compromise the non-fatal telemetry contract.
-    }
-}
-/** Session-boundary/test reset. */
-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();
-    // #2505, same catalog shape 17 re-arm: a rotation tally recurs (new writes
-    // keep crossing the bound), so clearing it costs nothing and a later
-    // session re-observes the fact fresh.
-    resetSinkRotations();
-    // #2146 review F3: the OTHER pulled source, `getProcessSingletonResets()`,
-    // deliberately does NOT re-arm here, and the difference from its neighbour
-    // above is the point. A sink write failure recurs — new writes fail, so
-    // clearing the tally costs nothing and a later session re-observes the
-    // problem. A process-singleton reset happens once, at module-evaluation
-    // time, and cannot recur: after it, the container holds only compatible
-    // cells. Clearing it would show the fact in the first session's
-    // `pilens_health` and hide it from every session after, which is exactly
-    // when someone reads that line. The row is bounded independently of the
-    // session (one entry per family, capped at 16), so leaving it costs a fixed
-    // handful of lines and keeps a process-scope fact visible for the process's
-    // life. Deliberate exception to catalog shape 17, not an oversight.
-    //
-    // `getProbeHomeRedirectEvent()` (#2506) is the same shape as the
-    // process-singleton case above and for the same reason: the redirect is
-    // resolved at most once per PROCESS (memoized in the `globalThis` slot
-    // `probe-home-state.ts` owns, not a session-scoped one), so it cannot
-    // recur within this process's life either — clearing it here would hide
-    // the fact from every session after the first in the same probe process.
-}
-// Re-exported so every existing importer keeps its specifier. The value now
-// lives in the `ledger-bounds.js` leaf (#2426), so a producer that only needs
-// the BOUND does not have to import the ledger — and cannot be broken by a test
-// that mocks it wholesale.
-export { DEGRADATION_ENTRIES_PER_KIND };
-export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;

package/dist/clients/demoted-finding-render.js

@@ -1,169 +0,0 @@
-/**
- * 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.");
-}
-/**
- * The one-line note a surface appends when it RETIRES a dependency-drift
- * demotion at its delivery cap (#1950). Deliberately worded differently from
- * {@link formatRetirementNote}: that one means the finding is provably
- * unrecoverable (the cited lines are gone), while THIS retirement is a
- * bounded-noise cap on a record that is still recoverable — a fresh dispatch
- * of the file could still confirm or clear it. Saying "cannot be re-confirmed"
- * here would be false.
- */
-export function formatDeliveryCapNote(deliveryCount) {
-    return (`Not shown again after ${deliveryCount} deliveries with no re-run: ` +
-        "this finding may still be accurate, but re-serving it further adds no " +
-        "new information. A fresh dispatch of this file will re-confirm or clear it.");
-}