pi-lens 4.1.2 → 4.1.4

package/dist/clients/bounded-cache.js

@@ -1,30 +1,73 @@
-/** Small insertion-ordered LRU used for process-lifetime memo tables. */
-export class BoundedLruCache {
-    maxEntries;
+/**
+ * Small insertion-ordered FIFO map used for process-lifetime memo tables
+ * whose eviction order must not be perturbed by reads: `get` never
+ * re-inserts, and `set` never reorders an already-present key — it behaves
+ * exactly like native `Map#set` on an existing key. A caller that wants a
+ * WRITE (not a read) to refresh recency does its own `delete` + `set` around
+ * this map, exactly as it would against a raw `Map` (#2442).
+ *
+ * {@link BoundedLruCache} extends this class and overrides exactly the two
+ * methods that differ (`get` re-inserts; `set` deletes first so a write moves
+ * the key to most-recently-used). Eviction, capacity and the whole `Map`-ish
+ * surface live here once — the two classes shipped as near-identical copies
+ * until #2442's review round flagged the duplication.
+ */
+export class BoundedFifoMap {
     entries = new Map();
+    maxEntries;
     constructor(maxEntries) {
         this.maxEntries = maxEntries;
     }
     get(key) {
-        const value = this.entries.get(key);
-        if (value !== undefined) {
-            this.entries.delete(key);
-            this.entries.set(key, value);
-        }
-        return value;
+        return this.entries.get(key);
     }
     has(key) {
         return this.entries.has(key);
     }
+    /**
+     * Insert or update `key` without reordering. Evicts the oldest
+     * (insertion-order) entries once the map exceeds capacity.
+     *
+     * Returns the evicted `[key, value]` pairs, oldest first — callers with
+     * eviction-side bookkeeping use the return value instead of hand-rolling
+     * `keys().next().value` (#2442). The VALUE is returned, not just the key,
+     * because the eviction-coupled sites need it: `tree-sitter-cache.ts` has to
+     * retire the dropped entry's WASM-heap tree (#417/#890) and
+     * `tree-sitter-client.ts` has to `delete()` the dropped compiled query.
+     * Handing back only the key would force those sites to read the value out
+     * of the map before eviction — i.e. to hand-roll the block this class
+     * exists to delete.
+     */
     set(key, value) {
-        this.entries.delete(key);
         this.entries.set(key, value);
+        return this.evictOverflow();
+    }
+    /**
+     * Change the capacity ceiling, evicting down to it immediately when it
+     * shrinks. Returns the evicted `[key, value]` pairs, oldest first, on the
+     * same contract as {@link set} — a caller with a DYNAMIC cap (an env-read
+     * ceiling, `TreeCache.setMaxSize`) needs the shrink to free the same
+     * resources an ordinary overflow frees.
+     */
+    setMaxEntries(maxEntries) {
+        this.maxEntries = maxEntries;
+        return this.evictOverflow();
+    }
+    /** Current capacity ceiling. */
+    getMaxEntries() {
+        return this.maxEntries;
+    }
+    /** Drop oldest-first until within capacity. The one eviction block. */
+    evictOverflow() {
+        const evicted = [];
         while (this.entries.size > this.maxEntries) {
-            const oldest = this.entries.keys().next().value;
+            const oldest = this.entries.entries().next().value;
             if (oldest === undefined)
                 break;
-            this.entries.delete(oldest);
+            this.entries.delete(oldest[0]);
+            evicted.push(oldest);
         }
+        return evicted;
     }
     delete(key) {
         return this.entries.delete(key);
@@ -48,3 +91,100 @@ export class BoundedLruCache {
         return this.entries[Symbol.iterator]();
     }
 }
+/**
+ * Small insertion-ordered FIFO SET used for process-lifetime membership-only
+ * caps — "is this key known", with no associated value.
+ *
+ * A thin wrapper over `BoundedFifoMap<T, true>` (#2460 review T1): eviction,
+ * capacity and the whole Map-ish surface already live in `BoundedFifoMap`
+ * exactly once, and this class's earlier standalone `Set`-backed
+ * implementation was a byte-for-byte copy of that eviction block one layer
+ * down — the exact duplication `BoundedFifoMap`'s own header describes
+ * `BoundedLruCache` existing to delete (#2442). The `true` dummy value never
+ * escapes this wrapper: it is not a cost paid by call sites, only by this
+ * file, so the earlier objection to building membership on top of the K,V
+ * map (#2460's first review, about `clients/observed-mutation.ts`'s
+ * `handled` set) does not apply here — that objection was about a caller
+ * storing a dummy value itself, not about a wrapper hiding one.
+ *
+ * Same eviction contract as {@link BoundedFifoMap}: `add` never reorders an
+ * already-present member (matches native `Set#add`), and both `add` and
+ * {@link setMaxEntries} return the evicted values, oldest first, so a call
+ * site with an eviction side effect (naming the dropped identity in a bounded
+ * telemetry record) consumes the return value instead of hand-rolling
+ * `values().next().value` or a `for (... of set) { …; break }` walk (#2442).
+ */
+export class BoundedSet {
+    entries;
+    constructor(maxEntries) {
+        this.entries = new BoundedFifoMap(maxEntries);
+    }
+    has(value) {
+        return this.entries.has(value);
+    }
+    /**
+     * Insert `value` without reordering an already-present member. Evicts the
+     * oldest (insertion-order) members once the set exceeds capacity.
+     *
+     * Returns the evicted values, oldest first — see the class doc for why a
+     * call site consumes this instead of hand-rolling the drop.
+     */
+    add(value) {
+        return this.entries.set(value, true).map(([evicted]) => evicted);
+    }
+    /**
+     * Change the capacity ceiling, evicting down to it immediately when it
+     * shrinks. Returns the evicted values, oldest first, on the same contract
+     * as {@link add}.
+     */
+    setMaxEntries(maxEntries) {
+        return this.entries.setMaxEntries(maxEntries).map(([evicted]) => evicted);
+    }
+    /** Current capacity ceiling. */
+    getMaxEntries() {
+        return this.entries.getMaxEntries();
+    }
+    delete(value) {
+        return this.entries.delete(value);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+    values() {
+        return this.entries.keys();
+    }
+    [Symbol.iterator]() {
+        return this.entries.keys();
+    }
+}
+/**
+ * Small insertion-ordered LRU used for process-lifetime memo tables. Same
+ * bounded-`Map` surface as {@link BoundedFifoMap}; the only two differences
+ * are overridden below.
+ */
+export class BoundedLruCache extends BoundedFifoMap {
+    /**
+     * Read and promote to most-recently-used.
+     *
+     * A stored `undefined` value is NOT promoted — the hit is indistinguishable
+     * from a miss on this signature, and pre-#2442 `BoundedLruCache` behaved
+     * the same way. No caller stores `undefined`; the note exists so a future
+     * one does not assume otherwise.
+     */
+    get(key) {
+        const value = this.entries.get(key);
+        if (value !== undefined) {
+            this.entries.delete(key);
+            this.entries.set(key, value);
+        }
+        return value;
+    }
+    /** Insert or update `key`, moving it to the most-recently-used position. */
+    set(key, value) {
+        this.entries.delete(key);
+        return super.set(key, value);
+    }
+}

package/dist/clients/bounded-telemetry.js

@@ -10,9 +10,9 @@
  * get the bounding right. This module is the intersection of those four, not
  * a speculative framework. Three of its four options come straight from those
  * sites. The fourth, `capPerTurn`, expresses #1733's per-turn bound
- * structurally but has no caller yet: that site's bound is its call cadence,
- * and pinning a cap there would red its own wiring tests. It ships tested and
- * mutation-proofed, awaiting its first site.
+ * structurally and now caps re-raised auxiliary coverage-gap detail rows
+ * (#2356), while the aggregate count and ledger retain bounded latest
+ * identities plus the dropped count.
  *
  * Three rules the helper makes structural instead of prose:
  *
@@ -24,10 +24,9 @@
  *    that must re-arm at `session_start` and will eventually be forgotten
  *    (the #1266–#1625 defect class).
  * 2. **A per-turn cap names its turn.** `capPerTurn` carries the caller's
- *    `turnIndex` in the same object as the limit, so there is no separate
- *    reset to wire and forget: the counters clear when the observed turn
- *    changes. This is the same lazy clear-on-transition shape as
- *    `noteImportResolutionMemoTurn` (`clients/blocker-freshness.ts`).
+ *    `turnIndex` in the same object as the limit. A bounded 64-turn window
+ *    keeps overlapping async turns independent; results older than that window
+ *    fail closed. Session start clears the window when numbering restarts.
  * 3. **Identity always survives.** Every emitted record carries the
  *    discriminating identity in `filePath` and in `metadata.identity`, so
  *    aggregation can still answer "which file, which method, which record is
@@ -39,7 +38,7 @@
  * stated reason for staying raw.
  *
  * Nothing here ever throws. Telemetry must not perturb the path it observes —
- * every one of the four migrated sites had already decided its outcome before
+ * each caller has already decided its outcome before
  * calling in.
  */
 import { incrementDegradationCount } from "./degradation-ledger.js";
@@ -51,6 +50,13 @@ import { logLatency } from "./latency-logger.js";
  * must not also be written by a raw `logLatency` call somewhere else.
  */
 export const BOUNDED_TELEMETRY_PHASES = [
+    /**
+     * #2467: a demand for the analyzer bootstrap clients was not served and
+     * the caller proceeded without them. Rising-edge per demand reason, with
+     * the ledger holding the exact count — a wedged or missing analyzer graph
+     * must not turn every tool call into a log line.
+     */
+    "bootstrap_clients_unavailable",
     /** #1705: a deferred-format record whose origin worktree never claimed it. */
     "agent_end_deferred_format_orphan_origin_mismatch",
     /** #1713: a `textDocument`/`workspace` diagnostic pull abandoned at budget. */
@@ -85,6 +91,16 @@ export const BOUNDED_TELEMETRY_PHASES = [
      * exact count.
      */
     "lsp_warm_client_missing",
+    /** #2052: a file's nearest LSP root is outside the session ceiling. */
+    "lsp_capability_skip",
+    /**
+     * #2044: failed-first test state was retired after a confirmed missing path,
+     * retained because the filesystem verdict was indeterminate, or evicted at
+     * the state cap. Selection checks and detailed rows are both capped per turn.
+     */
+    "test_runner_failed_target_state",
+    /** #2366: bounded lifecycle records for automatic test-result delivery. */
+    "test_runner_delivery",
     /**
      * #1723: an event-loop block at or above the floor. Not a degradation, so
      * no ledger kind; bounded by call cadence (one `turn_end` runs it once per
@@ -97,6 +113,63 @@ export const BOUNDED_TELEMETRY_PHASES = [
      * queue of them, so it is rising-edge per event name.
      */
     "session_event_stale_ctx_skip",
+    /**
+     * #2007: a worktree-mutating git command declined because another live
+     * session shares this dirty checkout. Rising edge per checkout root; the
+     * ledger keeps the exact repeat count.
+     */
+    "shared_checkout_switch_blocked",
+    /**
+     * #2007: `git status` could not report the working-tree state, so the same
+     * command was declined on an UNKNOWN rather than assumed clean.
+     */
+    "shared_checkout_probe_failed",
+    /** #2356: a notify-stall auxiliary remained uncovered after its bounded
+     * replacement window. Detailed rows are capped per turn; the ledger and
+     * aggregate turn-end row retain the complete count and identity. */
+    "lsp_scanner_coverage_gap",
+    /** #2358: a busy CPU discriminator deferred notify-stall teardown. */
+    "lsp_notify_stall_cpu_busy",
+    /**
+     * #2430: an observational pre/post snapshot was declined or cut short — the
+     * per-turn budget was already spent, the capture timed out, or the turn was
+     * aborted. Every unclassified tool call in a busy turn can reach this, so
+     * it is capped per turn with the ledger holding the exact count.
+     */
+    "observed_mutation_budget_exhausted",
+    /**
+     * #2430: the `agent_settled` tracked-file sweep could not complete within
+     * its bound. Once per settle at most, capped for the same reason.
+     */
+    "observed_sweep_skipped_budget",
+    /**
+     * #2430: a tracked file's size/mtime moved but no hashed baseline could
+     * confirm the bytes actually changed — too large for the sweep's read
+     * budget, or never hashed. Named rather than replayed, because a `touch`
+     * moves mtime without moving a byte (#2449 review round 2, F7). Bounded
+     * per turn: one settle can find many such files at once.
+     */
+    "observed_sweep_unverifiable",
+    /**
+     * #2430: an armed observation's universe was TRUNCATED because the tool
+     * named a directory with more entries than the net may watch. Bounded per
+     * turn with the ledger holding the exact count, and the identity is the
+     * tool name so the record answers WHICH tool is being watched partially
+     * (#2449 review round 3).
+     */
+    "observed_target_dir_capped",
+    /**
+     * #2430: the "pi-lens wrote these bytes itself" set hit
+     * `OBSERVED_HANDLED_MAX` and dropped its oldest entry. The dropped file is
+     * NAMED, because the eviction silently reintroduces the exact defect
+     * #2449 round 3 (S5) fixed: the ledger still holds the pre-drain bytes
+     * while the only record that those bytes were ours is gone, so the next
+     * settled sweep replays pi-lens's own formatter output as third-party
+     * drift. A cap that drops a mark has to say which one (catalog shape 10);
+     * capped per turn because a turn that overflows the set overflows it many
+     * times (#2449 review round 4, S2).
+     */
+    "observed_handled_evicted",
 ];
 const REGISTERED_PHASES = new Set(BOUNDED_TELEMETRY_PHASES);
 /** Report whether a phase name is in the registry (used by the sweep). */
@@ -104,14 +177,15 @@ export function isBoundedTelemetryPhase(phase) {
     return REGISTERED_PHASES.has(phase);
 }
 /**
- * Per-turn admission counters, keyed by phase. Cleared lazily when a call
- * observes a turn index different from the one the counters were built for,
- * and eagerly by `resetBoundedTelemetry` at `session_start` (a new session
- * restarts turn numbering at 0, so the lazy check alone could carry a stale
- * count across a session boundary that happened to land on the same index).
+ * Per-turn admission counters, keyed by turn and phase. Multiple turns remain
+ * live because async work can finish T1 after T2 has already emitted. The map
+ * retains a bounded recent window; work older than that window fails closed
+ * rather than reopening an exhausted budget. Session start clears all state.
  */
+const MAX_TRACKED_TURN_CAPS = 64;
 let turnCounts = new Map();
-let countedTurnIndex;
+let latestCountedTurnIndex;
+let retiredThroughTurnIndex = Number.NEGATIVE_INFINITY;
 /**
  * Decide whether this occurrence earns a detailed record, and count it in the
  * ledger either way. Returns `true` when the caller should write the record.
@@ -180,14 +254,25 @@ export function emitBounded(phase, identity, payload, options = {}) {
 function admitAgainstTurnCap(phase, cap) {
     if (cap === undefined)
         return true;
-    if (countedTurnIndex !== cap.turnIndex) {
-        turnCounts = new Map();
-        countedTurnIndex = cap.turnIndex;
+    if (cap.turnIndex <= retiredThroughTurnIndex)
+        return false;
+    let counts = turnCounts.get(cap.turnIndex);
+    if (!counts) {
+        if (turnCounts.size >= MAX_TRACKED_TURN_CAPS) {
+            const oldestTrackedTurn = Math.min(...turnCounts.keys());
+            if (cap.turnIndex < oldestTrackedTurn)
+                return false;
+            turnCounts.delete(oldestTrackedTurn);
+            retiredThroughTurnIndex = Math.max(retiredThroughTurnIndex, oldestTrackedTurn);
+        }
+        counts = new Map();
+        turnCounts.set(cap.turnIndex, counts);
     }
-    const used = turnCounts.get(phase) ?? 0;
+    latestCountedTurnIndex = Math.max(latestCountedTurnIndex ?? cap.turnIndex, cap.turnIndex);
+    const used = counts.get(phase) ?? 0;
     if (used >= cap.limit)
         return false;
-    turnCounts.set(phase, used + 1);
+    counts.set(phase, used + 1);
     return true;
 }
 /**
@@ -198,9 +283,16 @@ function admitAgainstTurnCap(phase, cap) {
  */
 export function resetBoundedTelemetry() {
     turnCounts = new Map();
-    countedTurnIndex = undefined;
+    latestCountedTurnIndex = undefined;
+    retiredThroughTurnIndex = Number.NEGATIVE_INFINITY;
+}
+/** Test-only: one turn's live admission count for a phase. */
+export function _boundedTurnCountForTest(phase, turnIndex = latestCountedTurnIndex) {
+    if (turnIndex === undefined)
+        return 0;
+    return turnCounts.get(turnIndex)?.get(phase) ?? 0;
 }
-/** Test-only: the live per-turn admission count for a phase. */
-export function _boundedTurnCountForTest(phase) {
-    return turnCounts.get(phase) ?? 0;
+/** Test-only: number of turn buckets retained by the bounded counter. */
+export function _boundedTrackedTurnsForTest() {
+    return turnCounts.size;
 }

package/dist/clients/build-identity.js

@@ -0,0 +1,95 @@
+/**
+ * #1775: `sessionstart.log` recorded no build identity — no commit hash, no
+ * build timestamp. Dogfood forensics ("does this session include PR #1727?")
+ * had to reconstruct that by hand: run `git merge-base --is-ancestor` in the
+ * serving checkout and compare `dist/` mtimes against the session-start time.
+ *
+ * The running extension can be a different checkout than the repo an
+ * investigator is looking at, so identity is derived from the RUNNING
+ * build's own files — `getPackageRoot` (already used by grammar-source.ts to
+ * find pi-lens's own assets under both the unbundled dev layout and a
+ * packaged install) plus the mtime of the very entry file that is executing
+ * right now — never from `process.cwd()` and never assumed to be a git
+ * checkout.
+ *
+ * Commit resolution reuses `review-graph/git-identity.ts`'s
+ * `resolveGitIdentity` — a PURE filesystem read, no `git` subprocess. This
+ * runs inside the `session_start` handler, ahead of the #473
+ * concurrent-secondary classification, so every in-process subagent pays
+ * whatever this costs; a synchronous `git rev-parse`/`git status` spawn pair
+ * (fix round 1's approach, reverted here) measured 150-300ms typical and up
+ * to ~10s worst case on two 5s timeouts. `resolveGitIdentity` is a handful of
+ * `fs.readFileSync` calls, LRU-cached per process, so this path never spawns.
+ *
+ * The dirty working-tree flag genuinely needs `git status`, which has no
+ * spawn-free equivalent — so it is dropped from this record rather than
+ * reintroducing a spawn on the session-start hot path (refs #1775 followup
+ * comment: dirty flag deferred, commit + entryMtime + version shipped).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isTestMode } from "./env-utils.js";
+import { getPackageRoot } from "./package-root.js";
+import { normalizeFilePath } from "./path-utils.js";
+import { resolveGitIdentity } from "./review-graph/git-identity.js";
+/**
+ * A `.git` found by walking up from `root` only counts as owning `root` when
+ * its resolved worktree top-level IS `root` — not merely an ancestor of it.
+ * Without this check, a packaged install nested anywhere under an unrelated
+ * repo (a dotfiles checkout in $HOME is the common case) would confidently
+ * report that repo's HEAD as the running build's identity.
+ */
+function resolveOwnedCommit(root) {
+    const identity = resolveGitIdentity(root);
+    if (!identity)
+        return "unknown";
+    const normalizedRoot = normalizeFilePath(path.resolve(root));
+    if (identity.worktreeRoot !== normalizedRoot)
+        return "unknown";
+    return identity.headCommit.slice(0, 8);
+}
+function readPackageVersion(root) {
+    try {
+        const raw = fs.readFileSync(path.join(root, "package.json"), "utf-8");
+        const pkg = JSON.parse(raw);
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function statEntryMtime(entryImportMetaUrl) {
+    try {
+        return fs.statSync(fileURLToPath(entryImportMetaUrl)).mtime.toISOString();
+    }
+    catch {
+        // Entry path unresolvable (e.g. a non-file:// URL) — "unknown" rather
+        // than throw out of a session-start observability line.
+        return "unknown";
+    }
+}
+/**
+ * Resolve the identity of the build currently running — pure filesystem
+ * reads, no subprocess. `entryImportMetaUrl` must be the ENTRY module's own
+ * `import.meta.url` (index.ts) — passing a different module's URL would
+ * report that module's mtime instead of the running build's.
+ *
+ * Returns `undefined` inside the test runner: nothing computed, nothing
+ * logged (`sessionstart-logger`'s writer is a no-op there too), so a caller
+ * on the session-start hot path never pays this cost during tests.
+ */
+export function getBuildIdentity(entryImportMetaUrl) {
+    if (isTestMode())
+        return undefined;
+    const root = getPackageRoot(entryImportMetaUrl);
+    return {
+        commit: resolveOwnedCommit(root),
+        entryMtime: statEntryMtime(entryImportMetaUrl),
+        version: readPackageVersion(root),
+    };
+}
+/** One bounded, human-readable line for sessionstart.log's free-text writer. */
+export function formatBuildIdentity(identity) {
+    return `session_start: build identity — commit=${identity.commit} entryMtime=${identity.entryMtime} version=${identity.version}`;
+}

package/dist/clients/bundled-resource-health.js

@@ -0,0 +1,113 @@
+/**
+ * Shared health classification + degradation reporting for a bundled
+ * resource directory read DIRECTLY by pi-lens (never handed to an external
+ * spawned tool as a `--config`/`--rule-dir` argument — that class already
+ * fails loudly through the tool's own spawn-failure path).
+ *
+ * #2626 fixed this shape for `clients/skills-resolver.ts`'s `skills/`
+ * directory: `resolvePackagePath(import.meta.url, …)` walks up from the
+ * loaded entry file to the nearest `package.json`, which is correct for both
+ * the source and compiled `dist/` layouts, but goes wrong SILENTLY, not
+ * loudly, when that walk lands somewhere with no resource dir beside it —
+ * the bundled dir missing from an installed package, or the entry file
+ * copied out of the package tree by a managed extension cache so the
+ * nearest `package.json` is the cache's own. #2636 is the class sweep:
+ * `clients/ast-grep-client.ts`'s `rules` fallback and the bundled
+ * tree-sitter-queries root (read identically by `clients/cache/rule-cache.ts`
+ * and `clients/tree-sitter-query-loader.ts`) have the exact same gap.
+ *
+ * Both callers reuse this ONE classify+report pair rather than each
+ * hand-rolling the ENOENT/EACCES distinction (#2626 review F4) a second and
+ * third time.
+ */
+import * as fs from "node:fs";
+import { incrementDegradationCount, } from "./degradation-ledger.js";
+import { notifyUserDegradation } from "./user-notify.js";
+/**
+ * Classify `dir`: does it exist, is it readable, and does it hold anything?
+ * Fail-closed and never throws. Distinguishes `ENOENT` (the common
+ * managed-cache-relocation case) from any OTHER `readdirSync` error
+ * (`EACCES` and friends) — an unreadable directory might genuinely hold a
+ * real resource pi-lens simply cannot read, so the honest report is "cannot
+ * read it", never "nothing is there" (#2626 review F4).
+ *
+ * `countEntries` lets a caller supply its OWN notion of "found" — e.g.
+ * `skills-resolver.ts` counts pi-loadable skill entry points via
+ * `scanEntriesForSkills`, not a bare directory listing — while still sharing
+ * this function's ENOENT/EACCES/empty classification shell (#2636 review F4:
+ * that shell was duplicated character-for-character between the two modules
+ * before this parameter existed). The default counts plain directory
+ * entries, which is what every OTHER caller (ast-grep's rules dir, the
+ * bundled tree-sitter-queries root) actually wants.
+ */
+export function classifyBundledResourceDir(dir, countEntries = (d) => fs.readdirSync(d).length) {
+    let entryCount;
+    try {
+        entryCount = countEntries(dir);
+    }
+    catch (error) {
+        const fsErrorCode = error?.code ?? "UNKNOWN";
+        if (fsErrorCode === "ENOENT")
+            return { status: "absent" };
+        return { status: "unreadable", fsErrorCode };
+    }
+    return entryCount > 0
+        ? { status: "healthy", entryCount }
+        : { status: "empty" };
+}
+/**
+ * Render `health` as a reason string. `emptyDescription` lets a caller name
+ * what "nothing found" actually means for its own resource (skills' loader
+ * cares about `SKILL.md`, not bare directory entries); every other status's
+ * prose is shared verbatim, since ENOENT/EACCES mean the exact same thing
+ * regardless of which resource directory hit them.
+ */
+export function describeBundledResourceHealth(health, dir, emptyDescription = `${dir} exists but holds nothing`) {
+    switch (health.status) {
+        case "absent":
+            return `no such directory: ${dir}`;
+        case "unreadable":
+            return `cannot read ${dir} (${health.fsErrorCode})`;
+        case "empty":
+            return emptyDescription;
+        default:
+            // unreachable for the "healthy" case — callers only report unhealthy ones.
+            return `${dir}: unexpected health status`;
+    }
+}
+/**
+ * Record ONE bounded `kind` degradation plus one `notifyUserDegradation`
+ * warning per (kind, dir) per session, when `health` is not healthy.
+ * Pure no-op when healthy. `incrementDegradationCount`'s own return value
+ * (not a hand-rolled Set) gates the notify to the rising edge, so a caller
+ * invoked on every dispatch (e.g. `RuleCache`'s constructor) can call this
+ * unconditionally without spamming the notify surface.
+ *
+ * `reasonOverride` lets a caller build a richer reason (skills-resolver.ts
+ * appends the entry file's directory) while still sharing the
+ * increment/notify mechanics below; the default is this module's own
+ * `describeBundledResourceHealth`.
+ *
+ * `notifyMessage` lets a caller replace the DEFAULT `pi-lens: <label>
+ * unavailable — <reason>.` sentence with its own finished wording (#2636
+ * review round 2, F1): `skills-resolver.ts`'s shipped notify text ("registers
+ * zero skills") is user-visible product text #2626 chose deliberately — the
+ * SYMPTOM the notification exists to surface — and folding onto this shared
+ * helper must never silently reword a string a maintainer already tuned.
+ */
+export function reportBundledResourceDirHealth(kind, dir, health, label, reasonOverride, notifyMessage) {
+    if (health.status === "healthy")
+        return;
+    const reason = reasonOverride ?? describeBundledResourceHealth(health, dir);
+    const isFirstOccurrence = incrementDegradationCount({
+        kind,
+        subject: dir,
+        reason,
+        metadata: health.status === "unreadable"
+            ? { fsErrorCode: health.fsErrorCode }
+            : undefined,
+    });
+    if (isFirstOccurrence) {
+        notifyUserDegradation(notifyMessage ?? `pi-lens: ${label} unavailable — ${reason}.`, "warning");
+    }
+}

package/dist/clients/bus-events-logger.js

@@ -44,11 +44,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 { createNdjsonLogger } from "./ndjson-logger.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { logLatency } from "./latency-logger.js";
-const BUS_EVENTS_LOG_FILE = path.join(getGlobalPiLensDir(), "bus-events.log");
+const BUS_EVENTS_LOG_FILE = path.join(getGlobalPiLensLogDir(), "bus-events.log");
 const writer = createNdjsonLogger({
     filePath: BUS_EVENTS_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,

package/dist/clients/bus-publish.js

@@ -23,6 +23,7 @@ import { appendRecentTouches } from "./recent-touches.js";
 import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const BUS_FILES_TOUCHED_EVENT = "pilens:files:touched";
 export const BUS_FILES_TOUCHED_VERSION = 1;
+const BUS_LOG_PATH_CAP = 64;
 const liveEmitter = createLiveBusEmitter();
 let hasLoggedFailure = false;
 // Log-once-per-process guards for the two structural-no-op outcomes below
@@ -148,6 +149,8 @@ export function publishFilesTouched(args) {
             cwd: payload.cwd,
             reason: args.reason,
             fileCount: payload.paths.length,
+            writer: "pi-lens",
+            paths: payload.paths.slice(0, BUS_LOG_PATH_CAP),
         });
     }
     catch (err) {