@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/README.md

@@ -34,6 +34,112 @@ pi-lens gives AI coding agents fast, language-aware feedback while they write/ed
 - MCP server (experimental) so Claude Code or any MCP client can drive the
   same diagnostics/read-substitute tools pi-lens exposes to pi
 
+## Architecture
+
+Most lifecycle events enter through one wrapper, which drops and counts events
+that arrive on a replaced session. `tool_call` registers raw: it delegates
+straight to a handler that owns its own total guard. Events fan out into the
+edit-time lane and the LSP lane. Both lanes write into the findings stores.
+Nothing reaches the agent from those stores until a freshness gate or an
+explicit age label clears it.
+
+```mermaid
+flowchart TD
+    subgraph host["pi host"]
+        HOST["Host events<br/>tool_call, tool_result, turn_start/end,<br/>session_start/shutdown, agent_end, context"]
+        WRAP["Stale-ctx wrapper<br/>skips and counts events on a replaced session<br/>tool_result, turn_start, turn_end, agent_end,<br/>agent_settled, session_start, context"]
+    end
+
+    subgraph guards["Guards"]
+        RG["Read-guard<br/>blocks edits that lack prior reading"]
+        GG["Git-guard<br/>holds commit/push while findings stay unresolved"]
+    end
+
+    subgraph edit["Edit-time lane"]
+        PIPE["Post-write pipeline<br/>secrets, format, autofix, sync, lint, tests"]
+        PLAN["Dispatch plan<br/>per file kind, per capability group"]
+        RUN["Runners<br/>format, lint, types, security, smells, docs"]
+        STRUCT["Structural rules<br/>tree-sitter queries and ast-grep"]
+        BUS["files-touched bus<br/>tells extensions which paths moved"]
+    end
+
+    subgraph lsp["LSP lane"]
+        POOL["Client pool<br/>warm reuse, idle eviction"]
+        DIAGS["File and workspace diagnostics"]
+        CASC["Impact cascade<br/>tiered wait policy"]
+    end
+
+    STORES["Findings stores<br/>widget state, warning caches, project snapshot"]
+
+    subgraph gate["Freshness gating"]
+        FRESH["Path freshness<br/>mtime vs scan time, past-EOF, dependency drift"]
+        DISPO["Dispositions<br/>false-positive, suppress, defer, flagged"]
+        LABEL["Explicit age label<br/>for findings no path gate can check"]
+    end
+
+    subgraph deliver["Delivery surfaces"]
+        TURN["Turn-end findings injection"]
+        WIDGET["Widget and footer tally"]
+        TOOLS["lens_diagnostics tool"]
+        NUDGE["Agent nudges"]
+    end
+
+    SESSION["Session lifecycle<br/>primary, sequential replacement, concurrent secondary"]
+    SINKS["Observability sinks<br/>latency.log, degradation ledger, bounded telemetry,<br/>cache observability, cascade and tree-sitter logs"]
+
+    HOST --> WRAP
+    HOST -->|tool_call, raw| RG
+    HOST -->|tool_call, raw| GG
+    WRAP -->|session_start| SESSION
+    WRAP -->|tool_result| PIPE
+    WRAP -->|tool_result, records reads and writes| RG
+    SESSION --> POOL
+    SESSION --> STORES
+    PIPE --> PLAN
+    PLAN --> RUN
+    PLAN --> STRUCT
+    PIPE --> POOL
+    PIPE --> BUS
+    POOL --> DIAGS
+    DIAGS --> CASC
+    RUN --> STORES
+    STRUCT --> STORES
+    DIAGS --> STORES
+    CASC --> STORES
+    BUS --> NUDGE
+    RG -->|read and edit history filter| NUDGE
+    STORES --> FRESH
+    STORES --> LABEL
+    FRESH --> DISPO
+    DISPO --> TURN
+    DISPO --> WIDGET
+    DISPO --> TOOLS
+    LABEL --> TURN
+    TURN --> GG
+    WRAP --> SINKS
+    PIPE --> SINKS
+    RUN --> SINKS
+    STRUCT --> SINKS
+    POOL --> SINKS
+    CASC --> SINKS
+    RG --> SINKS
+    GG --> SINKS
+    FRESH --> SINKS
+```
+
+Architecture-level view, updated when a lane changes. Per-tool inventories live
+in [features](docs/features.md) and
+[language coverage](docs/language-coverage.md). Today the edit-time lane carries
+45+ runner modules over 35+ file kinds, and the LSP lane speaks to a dozen-plus
+language servers.
+
+The gating box is an abstraction, not a call order. Freshness covers several
+independent mechanisms: path freshness against scan time, past-EOF line checks,
+and forward-import dependency drift. Dispositions are one more filter alongside
+them, not a second stage every finding walks through. Read the box as "a finding
+passes the gates that apply to it", and see `clients/finding-delivery-gate.ts`
+for the per-surface contract.
+
 ## Install
 
 ```bash
@@ -213,11 +319,19 @@ Thanks goes to these wonderful people:
     </tr>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/pppobear"><img src="https://avatars.githubusercontent.com/u/21952175?v=4" width="100px;" alt=""/><br /><sub><b>pppobear</b></sub></a><br /><a href="#bug-pppobear" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/bcachet"><img src="https://avatars.githubusercontent.com/u/45542?v=4" width="100px;" alt=""/><br /><sub><b>Bertrand Cachet</b></sub></a><br /><a href="#code-bcachet" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/EarthChen"><img src="https://avatars.githubusercontent.com/u/20179425?v=4" width="100px;" alt=""/><br /><sub><b>earthchen</b></sub></a><br /><a href="#code-EarthChen" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Don-Yin"><img src="https://avatars.githubusercontent.com/u/65135356?v=4" width="100px;" alt=""/><br /><sub><b>Don Yin</b></sub></a><br /><a href="#code-Don-Yin" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ELA718"><img src="https://avatars.githubusercontent.com/u/193304463?v=4" width="100px;" alt=""/><br /><sub><b>ELA718</b></sub></a><br /><a href="#doc-ELA718" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/sujeito-operator/pilot"><img src="https://avatars.githubusercontent.com/u/313599463?v=4" width="100px;" alt=""/><br /><sub><b>Sujeito Operator</b></sub></a><br /><a href="#code-sujeito-operator" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.blahs.life/"><img src="https://avatars.githubusercontent.com/u/620336?v=4" width="100px;" alt=""/><br /><sub><b>Dan Blah</b></sub></a><br /><a href="#bug-danblah" title="Bug reports">🐛</a></td>
+    </tr>
+    <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/3choBoomer"><img src="https://avatars.githubusercontent.com/u/521828?v=4" width="100px;" alt=""/><br /><sub><b>Nathan Cooke</b></sub></a><br /><a href="#code-3choBoomer" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/white-hat"><img src="https://avatars.githubusercontent.com/u/922988?v=4" width="100px;" alt=""/><br /><sub><b>Eli Stark</b></sub></a><br /><a href="#code-white-hat" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/marvtub"><img src="https://avatars.githubusercontent.com/u/33159023?v=4" width="100px;" alt=""/><br /><sub><b>Marvin Aziz</b></sub></a><br /><a href="#code-marvtub" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mjfaga"><img src="https://avatars.githubusercontent.com/u/7584015?v=4" width="100px;" alt=""/><br /><sub><b>Mark Faga</b></sub></a><br /><a href="#code-mjfaga" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aeturnal"><img src="https://avatars.githubusercontent.com/u/219271200?v=4" width="100px;" alt=""/><br /><sub><b>aeturnal</b></sub></a><br /><a href="#code-aeturnal" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://marvinaziz.de/"><img src="https://avatars.githubusercontent.com/u/33159023?v=4" width="100px;" alt=""/><br /><sub><b>Marvin Aziz</b></sub></a><br /><a href="#code-marvtub" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mjfaga"><img src="https://avatars.githubusercontent.com/u/7584015?v=4" width="100px;" alt=""/><br /><sub><b>Mark</b></sub></a><br /><a href="#code-mjfaga" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://aeturnal.io/"><img src="https://avatars.githubusercontent.com/u/219271200?v=4" width="100px;" alt=""/><br /><sub><b>aeturnal</b></sub></a><br /><a href="#code-aeturnal" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/floatGray"><img src="https://avatars.githubusercontent.com/u/44295302?v=4" width="100px;" alt=""/><br /><sub><b>floatGray</b></sub></a><br /><a href="#code-floatGray" title="Code">💻</a></td>
     </tr>
   </tbody>

package/node_modules/pi-lens/config/ruff/core.toml

@@ -16,10 +16,52 @@ select = [
   "SIM",  # flake8-simplify (simplifiable constructs)
   "C4",   # flake8-comprehensions (unnecessary comprehension patterns)
   "PIE",  # flake8-pie (misc lints)
+  "S",    # flake8-bandit (Bandit-equivalent security checks; refs #1757)
 ]
 
+# C90 (mccabe cyclomatic complexity) — considered and NOT enabled (refs #1757).
+# Measured against `requests` (mature, well-styled: 2 hits over the default
+# threshold of 10, both genuinely complex) and `pandas` (379 hits) — the
+# signal is real complexity, not false positives, but the volume on a large
+# pre-existing codebase would drown the security signal `S` adds in the same
+# pass. C90 is a maintainability metric, not a Bandit-equivalent security
+# check, so it stays out of scope for this issue. Revisit as its own opt-in
+# if pi-lens grows a "code health" ruleset.
+
+# S sub-rules excluded below were triaged by running `ruff check --select S`
+# against tests/fixtures/real-bugs/python/silent-and-security.py (this repo's
+# own security fixture — 3/3 true positives: S110, S105, S307) and against the
+# `requests` and `pip` packages installed under a local Python 3.11 (394
+# combined S findings across two mature, widely-audited real-world
+# codebases) — chosen as the "2-3 real fixtures" because pi-lens's own repo
+# only has ~15 Python files, too small to expose over-firing sub-rules.
 ignore = [
   "E501",   # line too long — formatter handles this
   "B008",   # function call in default argument — common FastAPI/typer pattern
   "SIM108", # ternary operator — readability is subjective
+
+  # S101 assert: 354 of 394 S hits (90%) across requests+pip were bare
+  # `assert` statements — the risk `S101` warns about (asserts stripped under
+  # `python -O`) is real only for security-enforcement code, not general
+  # application or test code, where `assert` is idiomatic (pytest). Pure
+  # noise at this volume.
+  "S101",
+  # S311 suspicious-non-cryptographic-random-usage: every hit observed
+  # (e.g. pip/_internal/utils/filesystem.py building a temp-file suffix) was
+  # a non-security use of `random` — file names, jitter, sampling. Ruff
+  # cannot distinguish security-sensitive randomness from ordinary use.
+  "S311",
+  # S603 subprocess-without-shell-equals-true: fires on every list-argument
+  # `subprocess.run(...)`/`Popen(...)` call regardless of whether the
+  # arguments are attacker-controlled — this is the RECOMMENDED safe form
+  # (no shell=True), yet it was the rule's only trigger condition in every
+  # one of the 10 hits observed in pip. Bandit's own docs note this rule's
+  # high false-positive rate; excluded for the same reason upstream projects
+  # commonly disable it.
+  "S603",
+  # S607 start-process-with-partial-path: fires whenever a subprocess call
+  # names its executable by PATH lookup (`["rustc", "--version"]`) instead of
+  # an absolute path — standard practice for any CLI-wrapping code, and both
+  # observed hits in pip were exactly that pattern, not a real vulnerability.
+  "S607",
 ]

package/node_modules/pi-lens/dist/clients/actionable-warnings.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { hashText, normalizeMessage, stableFindingId, } from "./finding-identity.js";
 import { applyWorkspaceEdit } from "./lsp/edits.js";
 import { getLSPService } from "./lsp/index.js";
 import { normalizeMapKey } from "./path-utils.js";
@@ -14,19 +15,47 @@ let beforeWarningStateLockForTests = null;
 export function _setBeforeWarningStateLockForTests(hook) {
     beforeWarningStateLockForTests = hook;
 }
-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);
-}
+/** #1816: was a local `relativeFile|tool|source|code|rule|normalizedMessage|
+ * line` hash, hand-rolled independently of `diagnostic-dispositions.ts`'s
+ * canonicalizing version — this is now the shared `finding-identity.js`
+ * builder (which DOES canonicalize both `cwd` and `filePath` through
+ * `normalizeMapKey` before relativizing, and hashes to 12 chars, matching
+ * dispositions). See `legacyActionableWarningId` below for the pre-#1816
+ * formula, kept only for on-disk suppression-store migration. */
 export function createActionableWarningId(args) {
+    return stableFindingId("aw:", {
+        cwd: args.cwd,
+        filePath: args.filePath,
+        parts: [
+            args.tool,
+            args.source,
+            args.code,
+            args.rule,
+            normalizeMessage(args.message),
+            args.line,
+        ],
+    });
+}
+/** PRE-#1816 id formula (raw, non-canonicalized `relativeFile`; 10-char
+ * hash). `actionable-warning-state.json` is a keyed, persisted store — a
+ * warning suppressed under the old formula must not silently reappear as
+ * unsuppressed just because this module unified onto the canonical,
+ * 12-char id. `suppressionFor`/`updateWarningState` use this ONLY to look up
+ * and migrate a still-pending old entry forward; nothing ever WRITES under
+ * this id. Do not canonicalize this function — that would make it identical
+ * to `createActionableWarningId` and silently defeat the migration lookup
+ * for every path that actually needed canonicalizing (the #533 class this
+ * whole item exists to fix). Review-round F3 (#1816): this guard is only
+ * provable under a MIS-CASED path fixture — a fixture whose raw and
+ * canonical forms coincide (a bare mkdtempSync path) makes canonicalizing
+ * this function a no-op, so the regression test must seed under a mis-cased
+ * segment (see `actionable-warnings.test.ts`'s migration describe block) or
+ * the guard passes vacuously either way. */
+function legacyActionableWarningId(args) {
+    const rel = path.relative(args.cwd, args.filePath).replace(/\\/g, "/");
+    const legacyRelativeFile = rel && !rel.startsWith("..") ? rel : normalizeMapKey(args.filePath);
     const parts = [
-        relativeFile(args.filePath, args.cwd),
+        legacyRelativeFile,
         args.tool ?? "",
         args.source ?? "",
         String(args.code ?? ""),
@@ -34,7 +63,7 @@ export function createActionableWarningId(args) {
         normalizeMessage(args.message),
         String(args.line ?? ""),
     ];
-    return `aw:${hashText(parts.join("|"))}`;
+    return `aw:${hashText(parts.join("|"), 10)}`;
 }
 function actionSafety(action) {
     const kind = action.kind ?? "";
@@ -93,7 +122,28 @@ function updateWarningState(cwd, warnings) {
             const now = new Date().toISOString();
             state.warnings ??= {};
             for (const warning of warnings) {
-                const existing = state.warnings[warning.id] ?? {};
+                // #1816 migration: this warning may still be recorded under the
+                // pre-#1816 id (raw relativeFile, 10-char hash) from before this
+                // store unified onto the canonical id. Fold that entry forward
+                // onto the current id and drop the stale key, so a warning
+                // suppressed before the migration stays suppressed, and repeated
+                // re-encounters converge the store onto one id per warning
+                // instead of accumulating both forever.
+                //
+                // Review-round F1: this MUST read `warning.legacyId` — the value
+                // `suppressionFor` already computed from the exact identity args
+                // used at lookup time — and must NEVER re-derive a legacy id from
+                // `warning.rule`/`tool`/`source`/`code`. Those fields hold
+                // DISPLAY values that diverge from the id-construction args for
+                // LSP-origin records (see `ActionableWarningRecord.legacyId`'s
+                // doc comment), so a re-derivation here would compute a
+                // different legacy id than the one `suppressionFor` checked,
+                // permanently bifurcating the store.
+                const legacyId = warning.legacyId;
+                const legacyEntry = legacyId && legacyId !== warning.id
+                    ? state.warnings[legacyId]
+                    : undefined;
+                const existing = state.warnings[warning.id] ?? legacyEntry ?? {};
                 state.warnings[warning.id] = {
                     ...existing,
                     status: existing.status ?? "active",
@@ -101,6 +151,8 @@ function updateWarningState(cwd, warnings) {
                     lastSeenAt: now,
                     seenCount: (existing.seenCount ?? 0) + 1,
                 };
+                if (legacyEntry && legacyId)
+                    delete state.warnings[legacyId];
             }
             return state;
         },
@@ -115,36 +167,64 @@ function updateWarningState(cwd, warnings) {
         }),
     });
 }
-function suppressionFor(cwd, id) {
-    const entry = readSuppressionState(cwd).warnings?.[id];
+/** Looks up suppression under the current id, falling back to the pre-#1816
+ * id (see `legacyActionableWarningId`) so a warning suppressed before this
+ * migration doesn't silently reappear as unsuppressed. `args` is the exact
+ * identity shape both id builders take.
+ *
+ * Also RETURNS the `legacyId` it computed (review-round F1, #1816): the
+ * caller carries it onto the record's `legacyId` field so
+ * `updateWarningState` can migrate the SAME legacy id this lookup used,
+ * instead of re-deriving one from the record's own `rule`/`tool`/`source`/
+ * `code` fields later. Re-deriving is unsound for LSP-origin records —
+ * `recordFromLspDiagnostic` passes no `rule` into this function (LSP
+ * diagnostics don't have one), then sets `record.rule` afterward to
+ * `${source}:${code}` purely for display. Recomputing from that display
+ * value would silently compute a DIFFERENT legacy id than the one actually
+ * checked here, permanently bifurcating the store: a suppression written
+ * this turn under the current id would never be found again next turn. */
+function suppressionFor(cwd, id, args) {
+    const state = readSuppressionState(cwd);
+    const legacyId = legacyActionableWarningId({ cwd, ...args });
+    const entry = state.warnings?.[id] ??
+        (legacyId !== id ? state.warnings?.[legacyId] : undefined);
     return {
         suppressed: entry?.status === "suppressed",
         reason: entry?.reason,
+        legacyId,
     };
 }
 export function recordFromDispatchDiagnostic(diagnostic, cwd) {
-    if (diagnostic.semantic !== "warning" || diagnostic.severity !== "warning")
+    if (diagnostic.semantic !== "warning")
+        return undefined;
+    // #1777: the old gate demanded `severity === "warning"` exactly, which was
+    // invisible while the ast-grep runner collapsed every non-error tier to
+    // "warning". Now that hint and info survive the dispatch path, admit them:
+    // a fix is a fix, and the tier governs how loudly a finding renders, not
+    // whether its fix is worth offering. `error` still routes to the blocking
+    // path, so it stays out even when a runner leaves `semantic` at "warning".
+    if (diagnostic.severity === "error")
         return undefined;
     if (!diagnostic.fixable && !diagnostic.fixSuggestion)
         return undefined;
     const filePath = path.resolve(cwd, diagnostic.filePath);
-    const id = createActionableWarningId({
-        cwd,
+    const identityArgs = {
         filePath,
         tool: diagnostic.tool,
         code: diagnostic.code,
         rule: diagnostic.rule,
         message: diagnostic.message,
         line: diagnostic.line,
-    });
-    const suppression = suppressionFor(cwd, id);
+    };
+    const id = createActionableWarningId({ cwd, ...identityArgs });
+    const suppression = suppressionFor(cwd, id, identityArgs);
     return {
         id,
         filePath,
         displayPath: toRunnerDisplayPath(cwd, filePath),
         line: diagnostic.line,
         column: diagnostic.column,
-        severity: "warning",
+        severity: diagnostic.severity,
         tool: diagnostic.tool,
         code: diagnostic.code,
         rule: diagnostic.rule,
@@ -155,6 +235,7 @@ export function recordFromDispatchDiagnostic(diagnostic, cwd) {
         actions: [],
         suppressed: suppression.suppressed,
         suppressionReason: suppression.reason,
+        legacyId: suppression.legacyId,
         origin: "dispatch",
     };
 }
@@ -170,16 +251,16 @@ function recordFromLspDiagnostic(diag, filePath, cwd) {
     const column = diag.range.start.character + 1;
     const source = diag.source ?? "lsp";
     const code = diag.code === undefined ? undefined : String(diag.code);
-    const id = createActionableWarningId({
-        cwd,
+    const identityArgs = {
         filePath,
         tool: "lsp",
         source,
         code,
         message: diag.message,
         line,
-    });
-    const suppression = suppressionFor(cwd, id);
+    };
+    const id = createActionableWarningId({ cwd, ...identityArgs });
+    const suppression = suppressionFor(cwd, id, identityArgs);
     return {
         id,
         filePath,
@@ -195,6 +276,7 @@ function recordFromLspDiagnostic(diag, filePath, cwd) {
         actions: [],
         suppressed: suppression.suppressed,
         suppressionReason: suppression.reason,
+        legacyId: suppression.legacyId,
         origin: "lsp",
     };
 }
@@ -329,8 +411,13 @@ export async function buildActionableWarningsReport(args) {
     }
     const merged = mergeWarnings(records);
     updateWarningState(cwd, merged);
+    // legacyId is #1816 migration bookkeeping for updateWarningState above —
+    // strip it before the report leaves this function, so it never lands in
+    // the `.pi-lens/cache/actionable-warnings.json` cache file or any
+    // agent-facing rendering of a warning record.
+    const reportWarnings = merged.map(({ legacyId: _legacyId, ...rest }) => rest);
     const byFile = new Map();
-    for (const warning of merged) {
+    for (const warning of reportWarnings) {
         const arr = byFile.get(warning.filePath) ?? [];
         arr.push(warning);
         byFile.set(warning.filePath, arr);
@@ -342,9 +429,16 @@ export async function buildActionableWarningsReport(args) {
         warnings,
     }));
     const allActions = merged.flatMap((warning) => warning.actions);
+    const unsuppressed = merged.filter((warning) => !warning.suppressed);
+    const countTier = (tier) => unsuppressed.filter((warning) => warning.severity === tier).length;
     const summary = {
         warnings: merged.length,
-        unsuppressed: merged.filter((warning) => !warning.suppressed).length,
+        unsuppressed: unsuppressed.length,
+        byTier: {
+            warning: countTier("warning"),
+            info: countTier("info"),
+            hint: countTier("hint"),
+        },
         suppressed: merged.filter((warning) => warning.suppressed).length,
         files: files.length,
         actions: allActions.length,
@@ -586,8 +680,17 @@ export function formatActionableWarningsAdvisory(report) {
     const safe = report.summary.autoFixEligible > 0
         ? ` ${report.summary.autoFixEligible} appear to have conservative preferred quickfixes.`
         : "";
+    // #1777: hint and info are style opinions, so say how much of the count is
+    // opinion. The line appears only when a quiet tier is actually present —
+    // an all-warning turn already says everything in the count above.
+    const byTier = report.summary.byTier;
+    const quiet = byTier ? byTier.hint + byTier.info : 0;
+    const tierLine = quiet > 0
+        ? `${quiet} of those are hint/info tier — style opinions, worth fixing only while you are already in that code.`
+        : undefined;
     return [
         `🟡 Fixable warnings introduced this turn: ${report.summary.unsuppressed}.${safe}`,
+        tierLine,
         `Details written to .pi-lens/cache/actionable-warnings.json`,
         fileList ? `Files:\n${fileList}${more}` : undefined,
         "If continuing in these files, read that JSON and resolve warnings that are safe and relevant. Do not apply broad refactors unless requested.",