pi-lens 4.1.2 → 4.1.4

package/dist/clients/degradation-ledger.js

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

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

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

package/dist/clients/dependency-checker.js

@@ -11,9 +11,11 @@
 import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { mapWithConcurrency } from "./map-with-concurrency.js";
 import { findNodeToolBinary } from "./package-manager.js";
 import { isFullyQualified } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { compareOrdinal } from "./string-utils.js";
 import { createAvailabilityChecker, discoverManagedTool, getManagedToolEnvironment, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
 import { createAvailabilityLatch, } from "./dispatch/runners/utils/availability-policy.js";
 /**
@@ -137,28 +139,16 @@ async function resolvedCommandIsStale(resolved, spawnableCache) {
 }
 /**
  * Run `mapper` over `items` with at most `concurrency` in flight at once.
+ *
  * Exported (#1810 review F6) so `clients/dispatch/runners/biome-check.ts`'s
  * `resolveBiomeFixKinds` can reuse this exact worker-pool shape for its
- * `biome explain` fan-out instead of carrying a second copy — this file
- * predates that need but is otherwise unrelated to it; a shared home for
- * this one helper wasn't worth a whole new module for two call sites.
+ * `biome explain` fan-out instead of carrying a second copy. #2504 moved the
+ * VALUE to the zero-dependency `map-with-concurrency.js` leaf — a third caller
+ * (`runtime-turn.ts`) needs the pool without pulling this analyzer client into
+ * the eager startup graph — and re-exports it here so every existing importer
+ * keeps its specifier. This stays the helper's documented home.
  */
-export async function mapWithConcurrency(items, concurrency, mapper) {
-    if (items.length === 0)
-        return;
-    let nextIndex = 0;
-    const workerCount = Math.max(1, Math.min(concurrency, items.length));
-    const worker = async () => {
-        while (true) {
-            const index = nextIndex++;
-            if (index >= items.length)
-                return;
-            await mapper(items[index]);
-        }
-    };
-    const workers = Array.from({ length: workerCount }, () => worker());
-    await Promise.all(workers);
-}
+export { mapWithConcurrency };
 // --- Client ---
 export class DependencyChecker {
     madgeAvailability = createAvailabilityChecker("madge", ".cmd", ["--version"], {
@@ -501,8 +491,14 @@ export class DependencyChecker {
         const existing = this.checkInFlight.get(key);
         if (existing)
             return existing;
+        // Identity-guarded release (#1968's pattern): delete only if THIS run is
+        // still the registered one. A bare delete-by-key lets a late-settling run
+        // evict a live successor a second writer registered under the same key
+        // mid-flight, after which the next caller starts a duplicate check.
         const promise = this.runCheckFile(normalized, projectRoot, gen).finally(() => {
-            this.checkInFlight.delete(key);
+            if (this.checkInFlight.get(key) === promise) {
+                this.checkInFlight.delete(key);
+            }
         });
         this.checkInFlight.set(key, promise);
         return promise;
@@ -781,8 +777,14 @@ export class DependencyChecker {
         // does, and the two overlap (runtime-session, fresh-fetch), so it takes a
         // generation too — claimed before the spawn, as late as a scan can.
         const gen = ++this.opGeneration;
+        // Identity-guarded release (#1968's pattern): delete only if THIS run is
+        // still the registered one. A bare delete-by-key lets a late-settling run
+        // evict a live successor a second writer registered under the same key
+        // mid-flight, after which the next caller starts a duplicate scan.
         const promise = this.runScanProject(projectRoot, gen).finally(() => {
-            this.scanInFlight.delete(projectRoot);
+            if (this.scanInFlight.get(projectRoot) === promise) {
+                this.scanInFlight.delete(projectRoot);
+            }
         });
         this.scanInFlight.set(projectRoot, promise);
         return promise;
@@ -830,7 +832,11 @@ export class DependencyChecker {
         const seen = new Set();
         let output = `[Circular Deps] ${circular.length} cycle(s) found:\n`;
         for (const dep of circular) {
-            const cycleKey = dep.path.sort((a, b) => a.localeCompare(b)).join("→");
+            // Copy before sorting: `dep.path` is rendered verbatim below (and by
+            // other CircularDep consumers, e.g. madge.ts's diagnostic renderer),
+            // so the dedupe key must not reorder — let alone mutate in place —
+            // the path a user reads.
+            const cycleKey = [...dep.path].sort(compareOrdinal).join("→");
             if (seen.has(cycleKey))
                 continue;
             seen.add(cycleKey);

package/dist/clients/deps/minimatch.js

@@ -1,4 +1,4 @@
 /**
  * Centralized accessor for `minimatch`. See ./typescript.ts for the rationale.
  */
-export { minimatch } from "minimatch";
+export { minimatch, Minimatch } from "minimatch";

package/dist/clients/diagnostic-line-freshness.js

@@ -62,6 +62,7 @@
  *     healing direction never re-trigger a resync — only the rising edge does.
  */
 import * as fs from "node:fs";
+import { BoundedFifoMap } from "./bounded-cache.js";
 import { logLatency } from "./latency-logger.js";
 import { toProjectRelativePath } from "./path-utils.js";
 import { STALE_LINE_MARKER } from "./stale-marker.js";
@@ -90,16 +91,12 @@ export function createLineCountCache() {
 // mismatched mtime always recomputes (see the module doc comment). Bounded
 // via FIFO eviction (mirrors `READ_GUARD_MAX_FILES`'s precedent) so a long
 // session's file count cannot grow this without limit.
-const MAX_SHARED_CACHE_ENTRIES = 512;
-const sharedLineCountCache = new Map();
+export const MAX_SHARED_CACHE_ENTRIES = 512;
+const sharedLineCountCache = new BoundedFifoMap(MAX_SHARED_CACHE_ENTRIES);
 function rememberInSharedCache(cache, filePath, entry) {
-    if (cache === sharedLineCountCache &&
-        cache.size >= MAX_SHARED_CACHE_ENTRIES &&
-        !cache.has(filePath)) {
-        const oldest = cache.keys().next().value;
-        if (oldest !== undefined)
-            cache.delete(oldest);
-    }
+    // `cache` is either the shared BoundedFifoMap (bounds itself on `set`) or a
+    // test-isolated plain `Map` (unbounded by design) — either way, this is
+    // just a write.
     cache.set(filePath, entry);
 }
 /** Test-only: drop the shared memo between test files/cases. */
@@ -117,6 +114,12 @@ export function _resetSharedLineCountCacheForTests() {
 export function _seedSharedLineCountCacheForTests(filePath, entry) {
     sharedLineCountCache.set(filePath, entry);
 }
+/** #2442 test-only: membership check that bypasses the real-stat requirement
+ *  `getCachedLineCount` imposes on every call — proves capacity eviction
+ *  directly, without needing 513 real files on disk. */
+export function _sharedLineCountCacheHasForTests(filePath) {
+    return sharedLineCountCache.has(filePath);
+}
 /**
  * Count newline bytes in `filePath` via bounded raw reads — never a full
  * `readFileSync`/UTF-8 decode of the whole file. `0x0A` (LF) never appears as

package/dist/clients/diagnostic-logger.js

@@ -5,10 +5,11 @@
  */
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
+import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 function getLogDir() {
-    return path.join(getGlobalPiLensDir(), "logs");
+    return path.join(getGlobalPiLensLogDir(), "logs");
 }
 function getLogFile() {
     const date = new Date().toISOString().split("T")[0];
@@ -24,8 +25,17 @@ export function getDiagnosticLogger() {
 }
 export function createDiagnosticLogger() {
     // Lazy filePath: the log file is keyed on the current date, resolved per
-    // drain so a long-lived logger rolls over at midnight.
-    const writer = createNdjsonLogger({ filePath: () => getLogFile() });
+    // drain so a long-lived logger rolls over at midnight. A daily rollover
+    // is NOT a size bound (#2505): one very busy day, or a long-lived
+    // process that never re-runs the session-start sweep, grows a single
+    // day file without limit. The backup keeps the .jsonl extension so the
+    // retention sweep in log-cleanup.ts (which matches /\.jsonl$/ under
+    // logs/) reaps it like any other daily file.
+    const writer = createNdjsonLogger({
+        filePath: () => getLogFile(),
+        maxBytes: getMaxLogSizeMB() * 1024 * 1024,
+        backupPath: () => getLogFile().replace(/\.jsonl$/, ".rotated.jsonl"),
+    });
     return {
         log(entry) {
             if (isTestMode()) {

package/dist/clients/dispatch/collect-later-tier.js

@@ -0,0 +1,39 @@
+/** Observed-latency classification shared by dispatch and LSP tier seams. */
+import { normalizeMapKey } from "../path-utils.js";
+/** A runner gets this much time before the next run moves off the write path. */
+export const COLLECT_LATER_THRESHOLD_MS = 5_000;
+const slowRunners = new Map();
+function key(projectRoot, runnerId) {
+    return `${normalizeMapKey(projectRoot)}\u0000${runnerId}`;
+}
+/** Read the current observed tier. Missing observations stay inline. */
+export function classifyObservedRunner(projectRoot, runnerId) {
+    return slowRunners.has(key(projectRoot, runnerId))
+        ? "collect-later"
+        : "inline";
+}
+/** Record one completed latency observation and return the resulting tier. */
+export function observeRunnerLatency(options) {
+    const normalizedProjectRoot = normalizeMapKey(options.projectRoot);
+    const runnerKey = key(normalizedProjectRoot, options.runnerId);
+    if (options.timedOut === true ||
+        options.durationMs > COLLECT_LATER_THRESHOLD_MS) {
+        slowRunners.set(runnerKey, {
+            projectRoot: normalizedProjectRoot,
+            runnerId: options.runnerId,
+        });
+        return "collect-later";
+    }
+    // A fast completed run is affirmative recovery, not merely absence of a
+    // failure. This deliberately prevents a process-lifetime latch.
+    slowRunners.delete(runnerKey);
+    return "inline";
+}
+/** Session boundary reset. */
+export function resetObservedRunnerLatency() {
+    slowRunners.clear();
+}
+/** Test-only inspection without exposing mutable state. */
+export function observedRunnerTierForTests(projectRoot, runnerId) {
+    return classifyObservedRunner(projectRoot, runnerId);
+}