pi-lens 4.1.5 → 4.2.0

package/dist/clients/cache-observability.js

@@ -176,9 +176,50 @@ function newAttributionState() {
         injectedCharsSinceLastUsage: 0,
         newTranscriptCharsSinceLastUsage: 0,
         attributionCharsCapped: false,
+        injectedBytes: emptyInjectedBytes(),
+        injectedFindingsRepeated: 0,
+        findingIdentities: new Set(),
+        findingIdentityCapRecorded: false,
+        turnEndAdvisoryBytes: 0,
+        toolResultBytes: 0,
+        toolResultsTruncated: 0,
         summary: newCacheUsageSummary(),
     };
 }
+const MAX_FINDING_IDENTITIES = 2_000;
+function emptyInjectedBytes() {
+    return {
+        sessionGuidance: 0,
+        turnFindings: 0,
+        testFindings: 0,
+        agentNudge: 0,
+        turnEndAdvisory: 0,
+        other: 0,
+    };
+}
+function sourceKey(source) {
+    return {
+        "session-guidance": "sessionGuidance",
+        "turn-findings": "turnFindings",
+        "test-findings": "testFindings",
+        "agent-nudge": "agentNudge",
+    }[source];
+}
+/** Best-effort, language-neutral identity extraction from rendered findings. */
+function findingIdentities(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const location = line.match(/(?:^|\s)([^\s:]+):(\d+)(?::\d+)?/);
+        if (!location)
+            continue;
+        const rule = line.match(/(?:rule|code)\s*[:=]\s*([\w./-]+)/i)?.[1] ??
+            line.match(/\(([\w./-]+)\)\s*$/)?.[1] ??
+            line.match(/:\d+(?::\d+)?\s+([\w./-]+)/)?.[1];
+        if (rule)
+            out.push(`${location[1]}:${location[2]}:${rule}`);
+    }
+    return out;
+}
 /**
  * Fetch (creating if absent) one session's attribution state, refreshing LRU
  * recency and evicting the oldest entries past the cap — same bounding as
@@ -688,10 +729,37 @@ export function observeCacheContext(args) {
                 countsCapped: sliceSize.capped,
             };
         });
+        const state = attributionFor(attributionKey(args.sessionId, args.sessionRole));
+        for (const slice of injectionSlices) {
+            const key = sourceKey(slice.source);
+            const bytes = measureInjectedMessages(slice.messages).bytes;
+            state.injectedBytes[key] += bytes;
+            for (const message of slice.messages) {
+                for (const identity of findingIdentities(typeof message.content === "string" ? message.content : "")) {
+                    if (state.findingIdentities.has(identity)) {
+                        state.injectedFindingsRepeated += 1;
+                        continue;
+                    }
+                    if (state.findingIdentities.size >= MAX_FINDING_IDENTITIES) {
+                        if (!state.findingIdentityCapRecorded) {
+                            state.findingIdentityCapRecorded = true;
+                            logLatency({
+                                type: "phase",
+                                filePath: "<pi-lens>",
+                                phase: "injected_finding_identity_cap",
+                                durationMs: 0,
+                                metadata: { cap: MAX_FINDING_IDENTITIES },
+                            });
+                        }
+                        continue;
+                    }
+                    state.findingIdentities.add(identity);
+                }
+            }
+        }
         const messageCountCapped = existingMessages.length > MAX_REPORTED_MESSAGES ||
             resultMessages.length > MAX_REPORTED_MESSAGES;
         recordContextAttribution(attributionKey(args.sessionId, args.sessionRole), existingMessages, sizes);
-        const state = attributionFor(attributionKey(args.sessionId, args.sessionRole));
         state.sequenceHashTruncatedSinceLastUsage ||=
             beforeSequence.truncated ||
                 beforeSequence.contentTruncated ||
@@ -721,6 +789,10 @@ export function observeCacheContext(args) {
                 injectedMessageCountCapped: injectedMessages.length > MAX_REPORTED_MESSAGES,
                 injectedChars: sizes.chars,
                 injectedBytes: sizes.bytes,
+                injectedBytesBySource: Object.fromEntries(sourceBreakdown.map((entry) => [
+                    sourceKey(entry.source),
+                    entry.bytes,
+                ])),
                 injectedEstimatedTokens: estimateTokens(sizes.chars),
                 injectedTokenBasis: "chars-per-token-4-estimate-not-provider-measured",
                 injectedCountsCapped: sizes.capped,
@@ -881,6 +953,13 @@ export function logCacheUsage(message, dbg, context) {
         const injectedCharsSinceLastTurn = state.injectedCharsSinceLastUsage;
         const newTranscriptCharsSinceLastTurn = state.newTranscriptCharsSinceLastUsage;
         const attributionCharsCapped = state.attributionCharsCapped;
+        const injectedBytes = {
+            ...state.injectedBytes,
+            turnEndAdvisory: state.turnEndAdvisoryBytes + state.injectedBytes.turnEndAdvisory,
+        };
+        const injectedFindingsRepeated = state.injectedFindingsRepeated;
+        const toolResultBytes = state.toolResultBytes;
+        const toolResultsTruncated = state.toolResultsTruncated;
         // This record is the turn boundary: reset the per-turn accumulators and
         // re-arm the prefix-break flag so the next verdict describes the NEXT gap.
         state.lastUsageAtMs = nowMs;
@@ -898,6 +977,11 @@ export function logCacheUsage(message, dbg, context) {
         state.injectedCharsSinceLastUsage = 0;
         state.newTranscriptCharsSinceLastUsage = 0;
         state.attributionCharsCapped = false;
+        state.injectedBytes = emptyInjectedBytes();
+        state.injectedFindingsRepeated = 0;
+        state.turnEndAdvisoryBytes = 0;
+        state.toolResultBytes = 0;
+        state.toolResultsTruncated = 0;
         // Clear the request stamp too: the next turn measures from ITS request, and
         // a turn whose `context` call pi-lens never saw must fall back rather than
         // reuse this one.
@@ -939,6 +1023,13 @@ export function logCacheUsage(message, dbg, context) {
                 injectedCharsSinceLastTurn,
                 newTranscriptCharsSinceLastTurn,
                 attributionCharsCapped,
+                injectedBytes,
+                injectedFindingsRepeated,
+                // Delivered tool-result aggregation over the turn (#2800 item 7):
+                // the sum of each delivered footer's bytes= figure and the count
+                // of results whose bound fired.
+                toolResultBytes,
+                toolResultsTruncated,
                 ...(context
                     ? {
                         // MessageEndEvent has no request/context id in the host API. These
@@ -1126,6 +1217,29 @@ export function clearCachePrefixSession(sessionId, sessionRole) {
     // a stale gap baseline and a stale prefix-break flag.
     attributionBySession.delete(key);
 }
+/** Record the exact quiet-window summary content handed to pi.sendMessage. */
+export function recordTurnEndAdvisoryBytes(sessionId, bytes, sessionRole = "primary") {
+    const state = attributionFor(attributionKey(sessionId, sessionRole));
+    state.turnEndAdvisoryBytes = Math.min(MAX_INJECTED_BYTES, state.turnEndAdvisoryBytes + Math.max(0, bytes));
+}
+/**
+ * Fold one delivered tool result into the per-turn aggregation the
+ * `cache_usage` row reports as `toolResultBytes` / `toolResultsTruncated`
+ * (#2800 item 7). `bytes` is the delivered payload's UTF-8 byte count as
+ * stamped in the result's own footer, and `truncated` is the footer's
+ * truncated flag. Called from each host adapter's delivery seam; the row is
+ * emitted by `logCacheUsage`, which resets both figures at the turn boundary.
+ * The byte sum saturates at the attribution bound so the row stays bounded.
+ */
+export function recordToolResultDelivery(args) {
+    const state = attributionFor(attributionKey(args.sessionId, args.sessionRole));
+    const bytes = Number.isFinite(args.bytes)
+        ? Math.max(0, Math.floor(args.bytes))
+        : 0;
+    state.toolResultBytes = Math.min(MAX_ATTRIBUTION_BYTES, state.toolResultBytes + bytes);
+    if (args.truncated === true)
+        state.toolResultsTruncated += 1;
+}
 /**
  * Emit one bounded session summary and retire its attribution state. The
  * summary contains fixed-key counters only; it never serializes transcript or
@@ -1165,6 +1279,13 @@ export function resetCachePrefixObservation() {
     prefixHashBySession.clear();
     attributionBySession.clear();
 }
+export function resetCacheFindingIdentitiesSession(sessionId, sessionRole) {
+    const state = attributionBySession.get(attributionKey(sessionId, sessionRole));
+    if (!state)
+        return;
+    state.findingIdentities.clear();
+    state.findingIdentityCapRecorded = false;
+}
 export function _attributionBySessionHasForTests(key) {
     return attributionBySession.has(key);
 }

package/dist/clients/cascade-format.js

@@ -1,3 +1,8 @@
+import * as fs from "node:fs";
+import { retagAuxiliaryDiagnostics } from "./dispatch/auxiliary-lsp.js";
+import { applyFindingPolicy, loadProjectRulePolicyMap, renderedRuleIdentities, } from "./dispatch/finding-policy.js";
+import { detectFileRole } from "./file-role.js";
+import { logLatency } from "./latency-logger.js";
 import { convertLspDiagnostics } from "./dispatch/utils/lsp-diagnostics.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
@@ -60,20 +65,64 @@ export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
  * Lives here rather than inline in the quiet-window callback so the delivery
  * path (reconcile → run → turn_end) is testable end to end; index.ts only wires
  * it to `runtime.appendCascadeRun`.
+ *
+ * #3102: the survivors are what the agent READS, so they go through the same
+ * `clients/dispatch/finding-policy.ts` stack — inline `pi-lens-ignore` → stored
+ * dispositions → the project's `.pi-lens.json` rule policy — that the per-edit
+ * dispatcher, `mode=full` and the `source=lsp` probe lane apply. Without it a
+ * cold-neighbour ERROR the agent already marked `false-positive` came back on
+ * every quiet-window reconcile.
  */
 export function buildResolvedFoundCascadeRun(cwd, neighbor) {
     const { filePath } = neighbor;
-    const diagnostics = convertLspDiagnostics(neighbor.diagnostics.filter((d) => d.severity === 1), filePath, { tool: "lsp" });
-    if (diagnostics.length === 0)
+    const errors = neighbor.diagnostics.filter((d) => d.severity === 1);
+    if (errors.length === 0)
         return undefined;
+    const policyStart = Date.now();
+    // This lane's roots are one and the same: index.ts hands `runtime.projectRoot`
+    // in as `cwd`, so the retag's config lookup and the disposition/rule-policy
+    // store read the same directory. The in-lane cascade's do NOT — see
+    // `applyCascadeDisplayPolicy`.
+    const { diagnostics, suppressed, auxSuppressed, total } = applyCascadeDisplayPolicy(errors, {
+        cwd,
+        policyRoot: cwd,
+        filePath,
+    });
+    // One bounded record per RUN, never one per finding (AGENTS.md "bounded
+    // observability"). This is a PUSH surface: silence after a mark is the mark
+    // working, not a clean verdict, so the count is recorded here rather than
+    // re-announced to the agent on every reconcile. `durationMs` covers the
+    // content read too — the latency this fold added to the quiet-window
+    // callback, measurable in the same per-phase record as every other cost.
+    recordCascadeFindingPolicy({
+        filePath,
+        durationMs: Date.now() - policyStart,
+        suppressed,
+        total,
+        auxSuppressed,
+    });
+    // No zero-length early return here: `formatCascadeNeighborDiagnostics`
+    // renders "" for a neighbour with no diagnostics and the `!formatted` guard
+    // below already returns `undefined` for it — a second check was mutation-
+    // inert (M7: deleting it left all 7 cascade cases green).
     const neighbors = [
         { filePath, reason: "references", diagnostics, lspTouched: true },
     ];
-    const formatted = formatCascadeNeighborDiagnostics(cwd, neighbors, {
+    const rendered = formatCascadeNeighborDiagnostics(cwd, neighbors, {
         noun: "cold neighbor",
     });
-    if (!formatted)
+    if (!rendered)
         return undefined;
+    // #1616 / #3102 AC 4, round 2 F2: a delivery that still has something to say
+    // states what it dropped, once per delivery — the same sentence the
+    // late-auxiliary advisory renders (`clients/runtime-turn.ts`). Policy drops
+    // only: an aux drop is the file's own suppression comment, which the
+    // per-edit dispatch path honours silently too, and it stays in the record
+    // above. A delivery with NOTHING left says nothing at all — silence on a
+    // push surface is not a claim that the neighbour is clean.
+    const formatted = suppressed > 0
+        ? `${rendered}\nsuppressed by disposition: ${suppressed} finding(s) (marked false-positive or won't-fix).`
+        : rendered;
     return {
         filePath,
         result: {
@@ -93,3 +142,150 @@ export function buildResolvedFoundCascadeRun(cwd, neighbor) {
         diagnosticCount: diagnostics.length,
     };
 }
+/**
+ * The ONE convert → retag → `applyFindingPolicy` derivation every cascade
+ * DISPLAY lane runs before its diagnostics reach the agent (#3102/#3157).
+ *
+ * Five lanes render `CascadeNeighborResult.diagnostics` through
+ * `formatCascadeNeighborDiagnostics`: the quiet-window builder above, and the
+ * four in-lane sites in `clients/dispatch/integration.ts` (passive cold
+ * snapshot, fresh touch, touch-error fallback, degraded fallback). Each one
+ * used to open-code `convertLspDiagnostics(...)` and render the result raw, so
+ * a neighbour ERROR the agent had marked `false-positive` was hidden by
+ * `mode=delta`/`mode=full`/the per-edit dispatcher/the probe lane and STILL
+ * re-reported by the cascade block on every edit that cascaded to it (#3157).
+ *
+ * TWO ROOTS, deliberately separate (the #1030 rule):
+ *  - `cwd` is the LANGUAGE root, and only `retagAuxiliaryDiagnostics` sees it
+ *    — `profile.allowBlocking(cwd)` looks for a local opengrep/zizmor/typos
+ *    config, exactly as the per-edit runner (`runners/lsp.ts`) passes
+ *    `ctx.cwd`.
+ *  - `policyRoot` is the PROJECT root, and the disposition store and the
+ *    `.pi-lens.json` rule map are read from it — `lens_diagnostic_mark` writes
+ *    under `runtime.projectRoot` (`index.ts`), so reading from a nested
+ *    language root in a monorepo opens a different
+ *    `diagnostic-dispositions.json` and silently no-ops every mark. This is
+ *    what `dispatcher.ts` already does with `ctx.projectRoot ?? ctx.cwd`.
+ *
+ * The auxiliary drop set (native `# nosemgrep`-style comments, `skipTestFiles`)
+ * is KEPT: every caller's diagnostics come straight off a client cache or a
+ * `touchFile` result, so nothing upstream ran `applyAuxiliarySuppressions`
+ * (only the `mode=full` workspace sweep does, `clients/lsp/index.ts`) and this
+ * is the FIRST application, not a double-apply — which is why the probe lane
+ * ignores it and these lanes do not.
+ *
+ * No `range.start.line` pre-partition here, unlike the late-auxiliary drain,
+ * whose own comment gives the alignment reason (`clients/runtime-turn.ts`,
+ * above its `anchored` filter): `convertLspDiagnostics` drops line-less
+ * entries, which would break the 1:1 index pairing `retagAuxiliaryDiagnostics`
+ * needs. That reason holds here too — it is simply already satisfied. Every
+ * caller reads the same `client.getAllDiagnostics()` / `touchFile` map, whose
+ * `mergeDiagnosticLists` (`clients/lsp/client.ts`) dereferences
+ * `diagnostic.range.start.line` unguarded, so a line-less entry throws long
+ * before any builder sees it and `converted` is always 1:1 with `errors`.
+ *
+ * Reads nothing when there is nothing to render, and never logs: the RECORD is
+ * the caller's decision, because the in-lane lane walks up to
+ * `CASCADE_NEIGHBOUR_BUDGET` neighbours per edit and must aggregate one row per
+ * run rather than one per neighbour.
+ */
+export function applyCascadeDisplayPolicy(
+/** ERROR-severity raw diagnostics, already capped by the caller's own
+ * display cap (`MAX_PER_FILE` in-lane; uncapped for the single-neighbour
+ * quiet-window run). */
+errors, options) {
+    if (errors.length === 0) {
+        return { diagnostics: [], suppressed: 0, auxSuppressed: 0, total: 0 };
+    }
+    const { cwd, policyRoot, filePath } = options;
+    // `undefined` → the fail-open empty string: inline suppression becomes a
+    // no-op and a STRICT `false-positive` anchor hashes an empty line, so a
+    // finding is never hidden by an I/O error (AGENTS.md shape 48).
+    const content = options.content ?? readNeighborContent(filePath);
+    const converted = convertLspDiagnostics(errors, filePath);
+    // #692/#3046: identity comes from the ONE shared derivation every other
+    // surface anchors a mark against — never a hardcoded `tool: "lsp"`.
+    const retained = retagAuxiliaryDiagnostics(converted, errors, content ?? "", {
+        cwd,
+        fileRole: detectFileRole(filePath, content),
+    });
+    const { kept } = applyFindingPolicy(retained, {
+        cwd: policyRoot,
+        filePath,
+        content: content ?? "",
+        policyMap: loadProjectRulePolicyMap(policyRoot),
+        identities: renderedRuleIdentities,
+    });
+    return {
+        diagnostics: options.displayCap === undefined
+            ? kept
+            : kept.slice(0, options.displayCap),
+        // Policy drops only, DISJOINT from `auxSuppressed` — the same split the
+        // `late_auxiliary_findings` record uses, so one operator reading both
+        // records does not have to know that one nests and the other does not.
+        suppressed: retained.length - kept.length,
+        auxSuppressed: converted.length - retained.length,
+        total: converted.length,
+    };
+}
+/**
+ * The ONE `cascade_finding_policy` row both cascade display lanes write.
+ *
+ * Gated on EITHER counter (#3102 round 2, F1): gating on the policy count alone
+ * made an aux-only drop — an ERROR master rendered, removed by the profile's own
+ * `# nosemgrep` / `skipTestFiles` rule — vanish with no row at all, the
+ * silent-drop shape this record exists to prevent (AGENTS.md shape 10). The
+ * `late_auxiliary_findings` twin reports both counters every drain.
+ */
+export function recordCascadeFindingPolicy(entry) {
+    const inputTruncated = entry.inputTruncated ?? 0;
+    if (entry.suppressed === 0 &&
+        entry.auxSuppressed === 0 &&
+        inputTruncated === 0)
+        return;
+    logLatency({
+        type: "phase",
+        toolName: "cascade",
+        filePath: entry.filePath,
+        phase: "cascade_finding_policy",
+        durationMs: entry.durationMs,
+        metadata: {
+            suppressed: entry.suppressed,
+            total: entry.total,
+            auxSuppressed: entry.auxSuppressed,
+            ...(inputTruncated > 0 && { inputTruncated }),
+        },
+    });
+}
+/**
+ * The neighbour's current bytes, for the two content-bound halves of the
+ * policy stack (inline `pi-lens-ignore` and the STRICT `false-positive`
+ * anchor). One synchronous read, paid only once a neighbour actually has ERROR
+ * diagnostics to render — the same read `mode=full` pays per flagged file and
+ * the probe lane pays per cache replay.
+ *
+ * SYNC here, while the in-lane cascade's own neighbour read at
+ * `clients/dispatch/integration.ts` (the active touch, under its "A6: async
+ * read to avoid blocking event loop on network-mounted drives" comment) is
+ * ASYNC. The asymmetry is deliberate and measured, not an oversight: that read
+ * happens for EVERY actively-touched neighbour in a parallel fan-out, while
+ * this one is paid at most once per DELIVERING neighbour — 0.0125 ms per
+ * neighbour measured on 40 real 15.6 KiB sources (#3157 AC 3), on loops that
+ * already do synchronous fs work (`nodeFs.existsSync` in the degraded
+ * fallback, and the `boundToCurrentDisk` verify whenever the producer attached
+ * a content hash and its (path, mtime, size) memo misses —
+ * `clients/lsp/diagnostic-binding.ts`). An async read here would force the
+ * quiet-window builder's synchronous callback to become async for no
+ * measurable gain.
+ *
+ * `undefined` on any failure: the caller degrades to the content-free half
+ * rather than hiding a finding it could not identify.
+ */
+function readNeighborContent(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/clients/code-quality-warnings.js

@@ -4,6 +4,7 @@ import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 import { displayProjectDataPath, getProjectDataDir } from "./file-utils.js";
 import { normalizeMessage, stableFindingId } from "./finding-identity.js";
 import { normalizeMapKey } from "./path-utils.js";
+import { resolveLensToolName } from "./tool-config.js";
 /**
  * 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
@@ -239,7 +240,7 @@ export function appendCodeQualityWarningsHistory(cwd, report) {
  * {@link formatActionableWarningsAdvisory} (#2521): this advisory carried the
  * identical hardcoded-legacy-path defect, one cache key over.
  */
-export function formatCodeQualityWarningsAdvisory(report, cwd) {
+export function formatCodeQualityWarningsAdvisory(report, cwd, host = "pi") {
     if (report.summary.warnings === 0)
         return undefined;
     const topRules = report.summary.topRules
@@ -261,6 +262,9 @@ export function formatCodeQualityWarningsAdvisory(report, cwd) {
             .filter(Boolean)
             .join(", ")
         : "";
+    // #2535 F3: a known tool with no mapping on this host resolves to
+    // undefined — omit the instruction rather than naming a dead tool.
+    const diagnosticsTool = resolveLensToolName("lens_diagnostics", host);
     return [
         `Code-quality warnings introduced/touched this turn: ${report.summary.warnings} across ${report.summary.files} file(s).`,
         tiers
@@ -269,7 +273,11 @@ export function formatCodeQualityWarningsAdvisory(report, cwd) {
         topRules ? `Top rules: ${topRules}` : undefined,
         // #2521: tool route first (`mode=delta` covers the code-quality cache
         // as well as the actionable one), resolved path second.
-        "Use lens_diagnostics with mode=delta to inspect these warnings.",
+        // #2535 F3: omit when unmapped on this host, never name a dead tool
+        // (pinned available on both hosts; defensive only).
+        diagnosticsTool
+            ? `Use ${diagnosticsTool} with mode=delta to inspect these warnings.`
+            : undefined,
         "No action required unless you are already refactoring these areas.",
         `Raw report (only if you need the JSON): ${displayProjectDataPath(cwd, "cache", "code-quality-warnings.json")}`,
     ]

package/dist/clients/complexity-client.js

@@ -13,6 +13,7 @@
 import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { calcCyclomaticComplexity } from "./dispatch/facts/function-facts.js";
 import { firstChildOfType, withTreeSitterRoot, isComplexityLanguageId, isComplexitySupportedFile, resolveTreeSitterLanguage, walk, } from "./tree-sitter-shared.js";
 // JS/TS/JSX share one grammar shape.
 const JSTS = {
@@ -190,6 +191,9 @@ function isLogicalOp(node, nodes) {
 }
 /** Cyclomatic contribution of a subtree: decision points + logical operators. */
 function subtreeCyclomatic(root, nodes) {
+    // Dispatch uses 1-based McCabe; this client exposes 0-based contributions (#2697).
+    if (nodes === JSTS)
+        return calcCyclomaticComplexity(root) - 1;
     let cc = 0;
     walk(root, (n) => {
         if (nodes.decision.has(n.type))
@@ -438,6 +442,7 @@ export class ComplexityClient {
             aiCommentPatterns: countAICommentPatterns(content),
             singleUseFunctions: countSingleUseFunctions(functions),
             tryCatchCount: countTryCatch(root, nodes),
+            functions,
         };
     }
     aggregateFunctionStats(functions) {

package/dist/clients/config-diagnostic-codes.js

@@ -171,6 +171,8 @@ export const CONFIG_DIAGNOSTIC_CODES = {
      * suppressed" about a configuration that applied nothing at all.
      */
     PILENS_CFG_0008: "config resolution failed; whole configuration ignored",
+    /** A tool key is unknown or names a required, non-disableable tool. */
+    PILENS_CFG_0009: "unknown or non-disableable tool config key ignored",
 };
 /** The shape every code in the namespace must match. */
 export const CONFIG_DIAGNOSTIC_CODE_PATTERN = /^PILENS_CFG_\d{4}$/;

package/dist/clients/config-resolve.js

@@ -740,8 +740,8 @@ export function reportPiLensConfigRecords(records) {
  */
 export function ignoredRecordCollector(configPath, tier) {
     const noted = [];
-    const note = (reason) => {
-        noted.push({
+    const note = (reason, code = "PILENS_CFG_0001") => {
+        let notedRecord = {
             code: "PILENS_CFG_0001",
             file: configPath,
             key: "",
@@ -752,7 +752,10 @@ export function ignoredRecordCollector(configPath, tier) {
                     sourceText: reason.sourceText,
                 }),
             tier,
-        });
+        };
+        if (code !== "PILENS_CFG_0001")
+            notedRecord.code = code;
+        noted.push(notedRecord);
     };
     return {
         note,

package/dist/clients/config-schema.js

@@ -42,6 +42,7 @@ import { LEGACY_ROOT_LSP_KEYS, LSP_NAMESPACE_KEY } from "./config-locations.js";
 // every config loader's import graph for one type alias.
 import { DENY_KEY, } from "./config-core/schema.js";
 import { flagConfigSectionKeys, GLOBAL_NON_FLAG_CONFIG_SECTIONS, LENS_FLAGS, PROJECT_FOREIGN_CONFIG_NAMESPACES, PROJECT_NON_FLAG_CONFIG_SECTIONS, } from "./lens-flag-registry.js";
+import { LENS_TOOL_NAMES } from "./tool-config.js";
 /** The JSON Schema dialect the published artifact declares. */
 const CONFIG_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
 /**
@@ -154,6 +155,22 @@ function buildConfigSchema() {
     ]) {
         properties[key] = opaque("stable");
     }
+    properties.tools = {
+        type: "object",
+        additionalProperties: true,
+        properties: Object.fromEntries(LENS_TOOL_NAMES.map((name) => [
+            name,
+            {
+                type: "object",
+                additionalProperties: true,
+                properties: {
+                    enabled: { type: "boolean", [STABILITY_TIER_KEY]: "experimental" },
+                },
+                [STABILITY_TIER_KEY]: "experimental",
+            },
+        ])),
+        [STABILITY_TIER_KEY]: "stable",
+    };
     // Namespaces owned by another tool that ride in the same file (`trivy`,
     // `helm`). Reserved so they survive validation, `experimental` because their
     // shape belongs to those runners, not to this schema.

package/dist/clients/config-warn.js

@@ -22,7 +22,7 @@
  * extraction — the prose is not API (the code is), but silently rewording a
  * warning inside a refactor is still not a thing this PR does.
  */
-import { DEPRECATED_CONFIG_SURFACES, } from "./config-diagnostic-codes.js";
+import { DEPRECATED_CONFIG_SURFACES, withConfigDiagnosticCode, } from "./config-diagnostic-codes.js";
 import { recordDegradationOnce } from "./degradation-ledger.js";
 import { errorClassName } from "./error-class.js";
 import { logExtension } from "./extension-log.js";
@@ -378,7 +378,7 @@ export function warnIgnoredConfigOnce(options) {
     logExtension({
         subsystem,
         level: "warn",
-        message,
+        message: withConfigDiagnosticCode(message, code),
         metadata: { configPath: file, reason, code, ...(key ? { key } : {}) },
     });
     // HUMAN-audience too: a config the user wrote is being ignored. Routed

package/dist/clients/dead-code-client.js

@@ -19,6 +19,7 @@ import { findLocalBinsAt, VENV_BIN_DIRS } from "./package-manager.js";
 import { findNearestMarkerRoot } from "./path-utils.js";
 import { getScratchTreeFnmatchPatterns } from "./scratch-tree-policy.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { probeToolAsync } from "./tool-probe.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";
@@ -229,7 +230,7 @@ export class PythonDeadCodeClient {
             let probe;
             let hostStallMs;
             try {
-                probe = await safeSpawnAsync(c.cmd, [...c.prefix, "--version"], {
+                probe = await probeToolAsync(c.cmd, [...c.prefix, "--version"], {
                     timeout: 5000,
                 });
             }
@@ -415,9 +416,13 @@ export class PythonDeadCodeClient {
                     durationMs,
                 };
             }
+            // vulture's verified exit-code table (above): exit 0 with empty
+            // stdout IS the clean-run signal, so this ran over the root
+            // (#2154) — unlike knip, whose clean run always prints JSON.
             return {
                 ...emptyResult(this.language),
                 success: true,
+                analyzed: true,
                 summary: "No dead code found",
                 durationMs,
             };
@@ -430,6 +435,8 @@ export class PythonDeadCodeClient {
         return {
             ...emptyResult(this.language),
             success: true,
+            // #2154: parsed vulture output for this root.
+            analyzed: true,
             unusedExports,
             summary: total === 0
                 ? "No dead code found"

package/dist/clients/degradation-ledger.js

@@ -2,7 +2,7 @@
 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, getSinkWriteFailures, resetSinkRotations, resetSinkWriteFailures, } from "./ndjson-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
@@ -233,6 +233,18 @@ export function getDegradationSummary() {
             })),
         });
     }
+    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.
@@ -310,6 +322,9 @@ const INFORMATIONAL_DEGRADATION_KINDS = new Set([
     // 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))

package/dist/clients/dependency-checker.js

@@ -815,7 +815,11 @@ export class DependencyChecker {
                 }
             }
             this.publishState(gen, circular, circularFiles);
-            return { circular, count: circular.length };
+            // #2154: the one madge site that parsed a graph for this root. Every
+            // other return here (missing root, no top-level source file, madge
+            // unavailable, spawn error, parse throw) is the SAME empty shape and
+            // must not be read as "no cycles in this project".
+            return { circular, count: circular.length, analyzed: true };
         }
         catch (err) {
             this.log(`Scan error: ${err.message}`);