@herbertgao/pi-extensions 2026.8.6 → 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/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,27 @@
 /** 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";
+// 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 +32,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 +40,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 +57,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 +69,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 +91,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,12 +142,6 @@ 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]) => ({
         kind,
@@ -148,6 +196,7 @@ export function resetDegradationLedger() {
     groups.clear();
     onceKeys.clear();
     tallies.clear();
+    ledgerGeneration++;
 }
 export const DEGRADATION_ENTRIES_PER_KIND = ENTRIES_PER_KIND;
 export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;