@herbertgao/pi-extensions 2026.9.7 → 2026.9.9

package/node_modules/pi-lens/dist/clients/persistent-reverify.js

@@ -0,0 +1,271 @@
+/**
+ * #3170 — the bounded persistent-reverify pass.
+ *
+ * A finding whose own file is unchanged is re-delivered turn after turn from
+ * the persisted actionable-warnings report without ever being re-observed
+ * against the live server: the in-band publish carries forward DEFERRED-origin
+ * file entries while their file has not moved
+ * (`mergeActionableWarningsReports`'s scope guard), and the delta freshness
+ * gate passes them because the file's mtime has not moved either. When the
+ * root cause was fixed in a DIFFERENT file, the carried finding is stale in
+ * fact but fresh by every on-disk axis.
+ *
+ * This module re-observes those files at turn_end, BEFORE the advisory
+ * assembles, and the replacement entries fold into the turn's SINGLE in-band
+ * publish (#3176 F1: a separate replacement publish spends the carry marker
+ * and the main publish then drops the entries at the scope guard — the
+ * blocker the review caught).
+ *
+ * Review-round contracts (#3176):
+ * - **F2**: the fresh observation converts through the PRODUCER's own
+ *   pipeline (`enrichFileFromLsp` — severity-2, code-action enrichment,
+ *   fixable-only, the per-file caps), fed the touch's collected diagnostics
+ *   as the cached arm so no second pull happens. No re-implementation.
+ * - **F3**: an empty result is clean ONLY when the touch itself answers
+ *   `confirmation: "confirmed"` — the silent-on-clean rule (#240/#533/#1253).
+ *   A bare `{diags: []}` (the house double's silent empty, a tier-3 server
+ *   still analyzing, a `skipReason`) is UNCONFIRMED: the carried warnings are
+ *   kept verbatim and the render labels the gap. `touched.inconclusive` is
+ *   `resolveTouchVerdict`'s output computed service-side and is honored
+ *   directly.
+ * - **F4**: every await is bound-wrapped (`bounded()`); `maxClientWaitMs` is
+ *   only the spawn/ready budget, not a request ceiling.
+ * - **F6**: no skip guard — every deferred-origin entry re-verifies each
+ *   turn (re-arm), per the issue's failure table.
+ *
+ * Bounds: at most {@link MAX_REVERIFY_FILES} files per turn_end, a wall
+ * budget of {@link REVERIFY_BUDGET_MS}, the turn-end abort signal, and no
+ * new durable state — candidates come from the persisted report itself,
+ * which is what was delivered last turn.
+ */
+import * as fs from "node:fs";
+import { enrichFileFromLsp } from "./actionable-warnings.js";
+import { bounded } from "./deadline-utils.js";
+import { logLatency } from "./latency-logger.js";
+import { touchCompletedConfirmationPolicy, } from "./lsp/diagnostic-binding.js";
+import { findAuxiliaryProfileForSource } from "./dispatch/auxiliary-lsp.js";
+/** At most this many files are re-observed per turn_end (the drift backstop's
+ * own 4-resyncs-per-pass precedent). */
+export const MAX_REVERIFY_FILES = 4;
+/** Wall-clock budget for the whole pass; a touch that cannot answer inside
+ * its remaining slice is recorded unconfirmed, never waited out. */
+export const REVERIFY_BUDGET_MS = 3000;
+/** The touch options the `source=lsp` probe uses, with this pass's source. */
+const TOUCH_SOURCE = "persistent_reverify";
+/**
+ * Select the report's re-verify candidates: DEFERRED-origin file entries (the
+ * only population the in-band publish carries forward, so the only population
+ * that re-serves across turns — F6: with no skip guard, so every carried
+ * entry re-verifies each turn) whose file stat is UNCHANGED since the entry's
+ * own observation stamp. A file that changed is skipped and counted — the
+ * edit path already re-observed it. Missing files are skipped too: the delta
+ * freshness gate drops them outright.
+ */
+export function selectPersistentReverifyFiles(report, nowMs = Date.now()) {
+    const candidates = [];
+    let skippedChanged = 0;
+    for (const entry of report.files) {
+        if (entry.origin !== "deferred")
+            continue;
+        // F3 (population half): the pass re-observes through a PRIMARY-scope
+        // touch, so an auxiliary-lane finding can never be re-confirmed — an
+        // entry carrying aux-sourced warnings is skipped (kept verbatim),
+        // never scored dropped. The aux lookup is the one shared seam.
+        if (entry.warnings.some((w) => findAuxiliaryProfileForSource(w.source ?? "") !== undefined)) {
+            continue;
+        }
+        const stamp = entry.generatedAt ? Date.parse(entry.generatedAt) : NaN;
+        if (!Number.isFinite(stamp) || stamp > nowMs)
+            continue;
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(entry.filePath).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (mtimeMs > stamp) {
+            skippedChanged += 1;
+            continue;
+        }
+        if (candidates.length < MAX_REVERIFY_FILES)
+            candidates.push(entry);
+    }
+    return { candidates, skippedChanged };
+}
+/**
+ * Run the bounded re-verify pass over the report's candidates and build the
+ * replacement entries for the caller's single in-band publish. Never throws:
+ * an unexpected per-file failure degrades that file to `unconfirmed` (kept
+ * verbatim, labeled), which is the shape-48 direction — the harm reaching the
+ * user is a hidden real finding, worse than re-delivering a stale one.
+ */
+export async function runPersistentReverify(args) {
+    const started = Date.now();
+    const deadlineAt = started + (args.budgetMs ?? REVERIFY_BUDGET_MS);
+    const nowMs = args.nowMs ?? started;
+    const { candidates, skippedChanged } = selectPersistentReverifyFiles(args.report, nowMs);
+    const outcomes = [];
+    const replacementFiles = [];
+    let touched = 0;
+    // F2: the producer's own pipeline (enrichFileFromLsp) — constructed once,
+    // reused per candidate. deltaOnly: false (a re-observation is not gated on
+    // this turn's modified ranges — the file was not edited).
+    const buildArgs = {
+        cwd: args.cwd,
+        sessionId: args.report.sessionId,
+        turnIndex: 0,
+        files: [],
+        modifiedRangesByFile: new Map(),
+        dispatchWarnings: [],
+        includeLspCodeActions: true,
+        deltaOnly: false,
+        ...(args.signal !== undefined ? { signal: args.signal } : {}),
+        lspBudgetMs: REVERIFY_BUDGET_MS,
+        dbg: () => { },
+    };
+    // R3-4: every candidate the budget or the abort cut, so the phase row
+    // distinguishes "the pass ran out of time" from "the server answered
+    // nothing". Counted from what the loop actually reached, never predicted.
+    let processed = 0;
+    for (const entry of candidates) {
+        if (args.signal?.aborted || Date.now() >= deadlineAt)
+            break;
+        processed += 1;
+        let content;
+        try {
+            content = fs.readFileSync(entry.filePath, "utf-8");
+        }
+        catch {
+            outcomes.push({
+                filePath: entry.filePath,
+                displayPath: entry.displayPath,
+                outcome: "unconfirmed",
+                dropped: 0,
+                kept: entry.warnings.length,
+            });
+            replacementFiles.push({ ...entry, reVerifyIncomplete: true });
+            continue;
+        }
+        // F4: the touch is bound-wrapped — `maxClientWaitMs` bounds the
+        // spawn/ready window, `bounded()` is the request ceiling.
+        let touchedResult;
+        try {
+            touchedResult = await bounded(args.lspService.touchFile(entry.filePath, content, {
+                diagnostics: "document",
+                collectDiagnostics: true,
+                source: TOUCH_SOURCE,
+                clientScope: "primary",
+            }), {
+                ms: Math.max(250, deadlineAt - Date.now()),
+                signal: args.signal,
+                hook: "turn_end",
+                label: "persistent_reverify_touch",
+            });
+        }
+        catch {
+            // The never-throws contract: a wedged touch degrades to unconfirmed
+            // (kept verbatim, labeled), never an escaped error.
+            touchedResult = undefined;
+        }
+        // F3 (#3176): an empty result is clean ONLY when the touch COMPLETED
+        // its confirmation policy — the silent-on-clean rule (#240/#533/#1253).
+        // A bare `{diags: []}` (the house double's silent empty, a tier-3
+        // server still analyzing) or a `skipReason` is UNCONFIRMED: the carried
+        // warnings are kept verbatim and the render labels the gap.
+        // `touched.inconclusive` is resolveTouchVerdict's output, computed
+        // service-side, and is honored directly.
+        // R3-3: read the policy through `touchCompletedConfirmationPolicy`, the
+        // #1470 seam, NOT the literal `confirmation !== "confirmed"` that
+        // `diagnostic-binding.ts:274-288` exists to forbid: `partial` means
+        // every server except the named cut-off auxiliaries answered, so the
+        // primary's silent-clean gates ran to completion and its observation is
+        // as trustworthy as a full confirmation. The literal labels a file the
+        // primary fully answered and keeps a finding the touch just re-derived.
+        if (touchedResult === undefined ||
+            touchedResult.inconclusive === true ||
+            touchedResult.skipReason !== undefined ||
+            (touchedResult.diagnosticsUnsupportedServerIds ?? []).length > 0 ||
+            !touchCompletedConfirmationPolicy(touchedResult)) {
+            outcomes.push({
+                filePath: entry.filePath,
+                displayPath: entry.displayPath,
+                outcome: "unconfirmed",
+                dropped: 0,
+                kept: entry.warnings.length,
+            });
+            replacementFiles.push({ ...entry, reVerifyIncomplete: true });
+            continue;
+        }
+        touched += 1;
+        // F2: the touch's collected diagnostics feed the producer's pipeline
+        // as the cached arm — no second pull, the producer's filters and
+        // caps are reused verbatim.
+        // F4: the outer await is bound-wrapped too — the module carries ZERO
+        // syntactic unbounded awaits (#2523 slice-3 worklist), and the hard
+        // ceiling composes with enrichFileFromLsp's own internal deadline.
+        const freshRecords = (await bounded(enrichFileFromLsp(args.cwd, buildArgs, { filePath: entry.filePath, cached: touchedResult.diags }, {
+            lspService: args.lspService,
+            pullTimeoutMs: 2000,
+            deadlineAt,
+            ...(args.signal !== undefined ? { signal: args.signal } : {}),
+            site: { hook: "turn_end", label: "persistent_reverify" },
+        }), {
+            ms: Math.max(250, deadlineAt - Date.now()),
+            signal: args.signal,
+            hook: "turn_end",
+            label: "persistent_reverify_enrich",
+        })) ?? [];
+        let dropped = 0;
+        let kept = 0;
+        for (const warning of entry.warnings) {
+            const stillThere = freshRecords.some((record) => record.rule === warning.rule && record.message === warning.message);
+            if (stillThere)
+                kept += 1;
+            else
+                dropped += 1;
+        }
+        const outcome = freshRecords.length === 0
+            ? "clean"
+            : dropped === 0
+                ? "reconfirmed"
+                : "mixed";
+        outcomes.push({
+            filePath: entry.filePath,
+            displayPath: entry.displayPath,
+            outcome,
+            dropped,
+            kept,
+        });
+        replacementFiles.push({
+            ...entry,
+            warnings: freshRecords,
+            reVerified: true,
+            generatedAt: new Date(nowMs).toISOString(),
+        });
+    }
+    logLatency({
+        type: "phase",
+        toolName: "turn_end",
+        filePath: args.cwd,
+        phase: "persistent_reverify",
+        durationMs: Date.now() - started,
+        metadata: {
+            candidates: candidates.length,
+            touched,
+            clean: outcomes.filter((o) => o.outcome === "clean").length,
+            reconfirmed: outcomes.filter((o) => o.outcome === "reconfirmed").length,
+            mixed: outcomes.filter((o) => o.outcome === "mixed").length,
+            unconfirmed: outcomes.filter((o) => o.outcome === "unconfirmed").length,
+            skippedChanged,
+            skippedBudget: candidates.length - processed,
+        },
+    });
+    return {
+        outcomes,
+        replacementFiles,
+        candidates: candidates.length,
+        touched,
+        skippedChanged,
+    };
+}

package/node_modules/pi-lens/dist/clients/pipeline.js

@@ -923,6 +923,15 @@ export async function runFormatPhase(filePath, getFormatService, dbg, signal, bu
  *       → const randomInt = Math.floor(result);
  */
 function buildEnrichedBlockerOutput(blockers, fileContent = "") {
+    // #3188: no blockers, no banner. The delivery gate above can retract every
+    // blocker (all cited files deleted), and the header interpolates the count,
+    // so without this the agent reads "🔴 STOP — 0 issue(s) must be fixed:" with
+    // nothing under it. Same guard, same reason, as `formatDiagnostics` in
+    // dispatch/utils/format-utils.ts — it belongs to the renderer, not to each
+    // call site, because the #2028 branch below cannot gate on the count without
+    // falling through to the UNGATED raw output.
+    if (blockers.length === 0)
+        return "";
     // Empty fileContent (readback failed, e.g. deleted-file race) still
     // renders the gated blocker list - just without per-line snippets.
     const fileLines = fileContent ? fileContent.split("\n") : [];
@@ -1228,7 +1237,12 @@ export async function runPipeline(ctx, deps) {
             const rest = dispatchResult.output.slice(dispatchResult.blockerOutput.length);
             if (rest)
                 gatedOut += rest;
-            output += `\n\n${gatedOut}`;
+            // #3188: every blocker retracted and nothing after the blocker
+            // section leaves nothing to say — appending the separator alone would
+            // still deliver a (whitespace-only) tool-result block, because
+            // `handleToolResult` decides delivery on `output` truthiness.
+            if (gatedOut)
+                output += `\n\n${gatedOut}`;
         }
         else {
             output += `\n\n${dispatchResult.output}`;

package/node_modules/pi-lens/dist/clients/runtime-turn.js

@@ -40,6 +40,8 @@ import { getLSPService } from "./lsp/index.js";
 import { drainPendingAuxCapEvictedCount, drainPendingAuxiliaryCoverage, isPendingAuxiliaryPastRearmTtl, rearmPendingAuxiliaryCoverage, MAX_LATE_AUX_REARMS, pendingAuxiliaryCoverageSize, } from "./lsp/pending-aux-coverage.js";
 import { convertLspDiagnostics } from "./dispatch/utils/lsp-diagnostics.js";
 import { retagAuxiliaryDiagnostics } from "./dispatch/auxiliary-lsp.js";
+import { runPersistentReverify, } from "./persistent-reverify.js";
+import { cascadeCarrySuffix } from "./cascade-format.js";
 import { applyFindingPolicy, loadProjectRulePolicyMap, renderedRuleIdentities, } from "./dispatch/finding-policy.js";
 import { detectFileRole } from "./file-role.js";
 import { drainPendingRunnerFindings, dropStaleRunnerFindings, pendingRunnerFindingsSize, } from "./dispatch/pending-runner-findings.js";
@@ -894,6 +896,24 @@ export async function handleTurnEnd(deps) {
         return true;
     });
     const cascadeResults = cascadeRuns.flatMap((r) => r.result ? [r.result] : []);
+    // Fix B (#3167): which results belong to a CARRIED run — the label is
+    // per-result at render time, so the run→result pairing must survive the
+    // flatMap above (which discards the wrapper).
+    // Fix B (#3168 F6): the success-path record — latency.log could not show
+    // the feature ever rendered without it (the only phases were the drop/
+    // settle records). One bounded record per turn, emitted after both render
+    // sections below.
+    let carriedRunsRendered = 0;
+    let labeledAdvisories = 0;
+    const carriedMetaByResult = new Map();
+    for (const r of cascadeRuns) {
+        if (r.result && (r.carriedTurns ?? 0) > 0 && r.carriedTurns !== undefined) {
+            carriedMetaByResult.set(r.result, {
+                carriedTurns: r.carriedTurns,
+                observedAt: r.observedAt,
+            });
+        }
+    }
     // #1550 class sweep: every cascade record below summarises `cascadeResults`
     // — runs, which carry their own paths and can be carried across turns
     // (#1443) — so labelling them with the turn's first EDITED file is the same
@@ -931,7 +951,16 @@ export async function handleTurnEnd(deps) {
             const pk = normalizeMapKey(result.filePath);
             const ownsAny = result.neighbors.some((n) => neighborOwner.get(normalizeMapKey(n.filePath)) === pk);
             if (ownsAny && result.formatted) {
-                parts.push(result.formatted);
+                // Fix B (#3167/#3168): a carried run's re-rendered blocker is labeled
+                // so the agent can tell it from a fresh observation — with the
+                // run's own observation age (#3168 F3).
+                const carryMeta = carriedMetaByResult.get(result);
+                const carrySuffix = cascadeCarrySuffix(carryMeta?.carriedTurns, carryMeta?.observedAt);
+                parts.push(carrySuffix
+                    ? `${result.formatted}\n${carrySuffix}`
+                    : result.formatted);
+                if (carrySuffix)
+                    carriedRunsRendered += 1;
                 injectedNeighborCount += result.neighbors.length;
                 injectedDiagnosticCount += result.neighbors.reduce((s, n) => s + n.diagnostics.length, 0);
             }
@@ -1081,27 +1110,59 @@ export async function handleTurnEnd(deps) {
         // "ℹ️ Advisory — no action required this turn:" label, so an imperative
         // ("review dependents manually") would contradict it. The #533 substance
         // stays: a clean cascade result does NOT cover these files' dependents.
-        const graphAdvisory = buildAdvisory(graphRuns, {
+        // Fix B (#3167/#3168 F4): a coverage advisory computed from a CARRIED
+        // indeterminate run describes the previous turn's evidence — label it so
+        // the absence-of-coverage statement is not read as current. A MIXED
+        // bucket (some carried, some fresh) is left UNLABELED: a Math.max
+        // suffix on the finished multi-line advisory would attach the carry to
+        // a file that was not carried.
+        const withCarryLabel = (advisory, runs) => {
+            if (advisory === undefined)
+                return undefined;
+            const carried = runs.filter((r) => (r.carriedTurns ?? 0) > 0);
+            if (carried.length === 0 || carried.length !== runs.length) {
+                return advisory;
+            }
+            // #3168 F13: the bucket's age is the OLDEST carried observation, and
+            // only when EVERY carried run carries one. A `Math.min` sentinel
+            // (`?? Number.MAX_SAFE_INTEGER`) silently ignored the unstamped runs
+            // and stated a confident age for a bucket that contains an unaged
+            // one; one missing stamp collapses the age half to the helper's
+            // neutral "scan age unknown" wording instead.
+            const stamps = carried.map((r) => r.observedAt);
+            const observedAt = stamps.every((s) => s !== undefined)
+                ? Math.min(...stamps)
+                : undefined;
+            const suffix = cascadeCarrySuffix(carried[0]?.carriedTurns, observedAt);
+            if (!suffix)
+                return advisory;
+            labeledAdvisories += 1;
+            // #3168 F11: newline, as the blocker path does above. A space join
+            // welded the suffix onto the LAST bullet of a multi-bullet advisory,
+            // so the carry label read as a property of that one file.
+            return `${advisory}\n${suffix}`;
+        };
+        const graphAdvisory = withCarryLabel(buildAdvisory(graphRuns, {
             lead: (fileCount, reasons) => `Cascade could not compute downstream impact for ${fileCount} edited file(s) this turn — ` +
                 `the review graph was unavailable (${reasons}), so their dependents were not ` +
                 `cascade-checked and a clean cascade result does not cover them.`,
             fallbackDetail: (r) => r.indeterminate?.reason === "missing_node"
                 ? "changed file not in the review graph"
                 : "review graph unavailable",
-        });
+        }), graphRuns);
         // @delivery-surface: runtime-turn:cascade-coverage-advisory
         if (graphAdvisory)
             advisoryParts.push(graphAdvisory);
-        const bindingAdvisory = buildAdvisory(bindingRuns, {
+        const bindingAdvisory = withCarryLabel(buildAdvisory(bindingRuns, {
             lead: (fileCount, reasons) => `Cascade identified dependents for ${fileCount} edited file(s) this turn, but their ` +
                 `diagnostics could not be freshly confirmed (${reasons}) and were withheld — a clean ` +
                 `cascade result does not cover them.`,
             fallbackDetail: () => "cascade diagnostics withheld (binding rejected)",
-        });
+        }), bindingRuns);
         // @delivery-surface: runtime-turn:cascade-coverage-advisory
         if (bindingAdvisory)
             advisoryParts.push(bindingAdvisory);
-        const budgetAdvisory = buildAdvisory(budgetRuns, {
+        const budgetAdvisory = withCarryLabel(buildAdvisory(budgetRuns, {
             lead: (fileCount, reasons) => `Cascade checked the selected neighbors for ${fileCount} edited file(s) this turn, ` +
                 `but some eligible dependents were not checked because the cascade budget ` +
                 `was exhausted (${reasons}); a clean cascade result does not cover them.`,
@@ -1114,7 +1175,7 @@ export async function handleTurnEnd(deps) {
                     ? `${detail}; transitive expansion was capped before all eligible dependents were enumerated`
                     : detail;
             },
-        });
+        }), budgetRuns);
         // @delivery-surface: runtime-turn:cascade-coverage-advisory
         if (budgetAdvisory)
             advisoryParts.push(budgetAdvisory);
@@ -1152,6 +1213,14 @@ export async function handleTurnEnd(deps) {
             },
         });
     }
+    // Fix B (#3168 F6): the success-path record — see the counters above.
+    if (carriedRunsRendered > 0 || labeledAdvisories > 0) {
+        logCascade({
+            phase: "cascade_carry_rendered",
+            filePath: cascadeLogFilePath,
+            metadata: { carriedRunsRendered, labeledAdvisories },
+        });
+    }
     const cascadeSkipped = {
         blockers: 0,
         non_code: 0,
@@ -2672,7 +2741,37 @@ export async function handleTurnEnd(deps) {
             fileSeqByPath.set(filePath, getFileSeq.call(runtime, filePath));
         }
     }
+    let reverify;
     if (getFlag("lens-actionable-warnings")) {
+        // #3170: re-verify carried deferred findings before the advisory
+        // assembles — a finding whose file is unchanged re-serves from the
+        // persisted report without ever being re-observed; root-cause-fixed-
+        // elsewhere findings converge here instead of repeating. Bounded in the
+        // module (≤4 files, wall budget, abort signal). #3176 F1: the
+        // replacement entries fold into THIS turn's single in-band publish
+        // below — a separate replacement publish spends the carry marker and
+        // this publish then drops the entries at the scope guard (the blocker
+        // the review caught).
+        const persistedReport = cacheManager.readCache("actionable-warnings", cwd, Number.MAX_SAFE_INTEGER)?.data;
+        if (persistedReport?.files?.some((entry) => entry.origin === "deferred")) {
+            const reverifyLspService = getLSPService();
+            if (reverifyLspService) {
+                // #2523: the hook-path await is bound-wrapped with the hook's own
+                // budget and signal; the pass's internal deadline (3s) is the
+                // tighter of the two.
+                reverify = await bounded(runPersistentReverify({
+                    report: persistedReport,
+                    cwd,
+                    lspService: reverifyLspService,
+                    signal: getAmbientAbortSignal(),
+                }), {
+                    ms: HOOK_WALL_BUDGET_MS.turn_end,
+                    signal: getAmbientAbortSignal(),
+                    hook: "turn_end",
+                    label: "persistent_reverify",
+                });
+            }
+        }
         try {
             const report = await buildActionableWarningsReport({
                 cwd,
@@ -2751,6 +2850,24 @@ export async function handleTurnEnd(deps) {
             // forward only entries a DEFERRAL produced, and only while their
             // file has not moved, so a `turn_delta` report does not accumulate
             // every prior turn's findings.
+            // #3176 F1: the re-verify replacements fold into THIS report — one
+            // in-band publish total, so the carry marker is spent exactly once and
+            // the merged report cannot drop the entries behind the publish (the
+            // blocker the review caught).
+            if (reverify?.replacementFiles.length) {
+                const replacementByPath = new Map(reverify.replacementFiles.map((file) => [
+                    normalizeMapKey(file.filePath),
+                    file,
+                ]));
+                const files = (report.files ?? []).map((file) => replacementByPath.get(normalizeMapKey(file.filePath)) ?? file);
+                for (const replacement of reverify.replacementFiles) {
+                    if (!files.some((file) => normalizeMapKey(file.filePath) ===
+                        normalizeMapKey(replacement.filePath))) {
+                        files.push(replacement);
+                    }
+                }
+                report.files = files;
+            }
             const publishResult = publishActionableWarningsReport(cacheManager, cwd, report, {
                 origin: "in-band",
                 getFileSeq: getFileSeq

package/node_modules/pi-lens/dist/clients/skills-resolver.js

@@ -82,7 +82,43 @@ export function resolveSkillPaths(importMetaUrl) {
     });
     if (health.status !== "healthy") {
         const entryDir = path.dirname(fileURLToPath(importMetaUrl));
-        const reason = `${describeBundledResourceHealth(health, skillsDir, `no SKILL.md (or loadable .md) found under ${skillsDir}`)} (entry loaded from ${entryDir})`;
+        const healthDescription = describeBundledResourceHealth(health, skillsDir, `no SKILL.md (or loadable .md) found under ${skillsDir}`);
+        // #3175: two DIFFERENT strings, not one `reason` reused for both sinks
+        // as this used to be.
+        //
+        // `notifyReason` (uncapped — `notifyUserDegradation` never truncates)
+        // keeps the full, natural description: classification first, then
+        // where the entry file that triggered this lookup was loaded from.
+        const notifyReason = `${healthDescription} (entry loaded from ${entryDir})`;
+        // `ledgerReason` is built from a SHORT, path-free classification tag
+        // instead of `healthDescription`, because the LEDGER's `reason` field
+        // IS capped (`truncateForLedger`, `LEDGER_FIELD_MAX` = 200 chars,
+        // head-preserving — see `ledger-bounds.ts`) and `healthDescription`
+        // repeats `skillsDir` in full — already recorded, untruncated, in
+        // `subject` below whenever it's under the cap on its own. A
+        // managed-cache `skillsDir` plus this entry's `entryDir` sharing one
+        // long root routinely sums past 200 chars (#3175: TMPDIR ~60+ chars is
+        // a real dry-roll and CI-lane shape, not a pathological one); a
+        // head-preserving cap over the OLD concatenation (dir-bearing text
+        // first, `entryDir` last) then kept the redundant path and dropped the
+        // one fact nothing else records — which entry file's directory
+        // triggered this lookup (#2587's "entry file copied out of the
+        // package tree" case is exactly this). Simply swapping that order is
+        // NOT enough: `healthDescription`'s own `unreadable` branch reads
+        // `cannot read ${dir} (${fsErrorCode})`, so `dir` sitting in the
+        // MIDDLE of the classification text can still push `fsErrorCode`
+        // itself off the cap once `entryDir` leads. Dropping the redundant
+        // path from the ledger's copy entirely — keeping only the
+        // classification word/code — removes that squeeze instead of moving
+        // it, and leaves comfortable room (entry directories under roughly
+        // 150 chars fit whole) for every managed-cache/npm-install layout
+        // observed so far.
+        const classification = health.status === "unreadable"
+            ? `cannot read (${health.fsErrorCode})`
+            : health.status === "empty"
+                ? "no SKILL.md found"
+                : "no such directory";
+        const ledgerReason = `${classification} (entry loaded from ${entryDir})`;
         // #2626 review F3: the notify-once gate previously re-derived "have we
         // already recorded this" by scanning `getDegradationSummary()` and
         // comparing the RAW `skillsDir` against subjects the ledger stores
@@ -99,7 +135,7 @@ export function resolveSkillPaths(importMetaUrl) {
         // never silently replace it. Passed explicitly rather than inferred
         // from `label` so this stays a per-caller decision, not a convention
         // the next caller has to remember.
-        reportBundledResourceDirHealth(SKILLS_DIR_MISSING_KIND, skillsDir, health, "skills", reason, `pi-lens: registers zero skills — ${reason}.`);
+        reportBundledResourceDirHealth(SKILLS_DIR_MISSING_KIND, skillsDir, health, "skills", ledgerReason, `pi-lens: registers zero skills — ${notifyReason}.`);
     }
     return [skillsDir];
 }