@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-lens/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/node_modules/pi-lens/dist/clients/bounded-pid-file-lock.js

@@ -194,7 +194,7 @@ export function acquireBoundedPidFileLock(lockPath, options) {
                     options.logContention();
                     return null;
                 }
-                throw new Error(options.timeoutMessage);
+                throw new Error(options.timeoutMessage, { cause: error });
             }
             Atomics.wait(waitArray, 0, 0, options.retryMs);
         }

package/node_modules/pi-lens/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:
  *
@@ -38,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";
@@ -50,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. */
@@ -92,6 +99,8 @@ export const BOUNDED_TELEMETRY_PHASES = [
      * 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
@@ -115,12 +124,53 @@ export const BOUNDED_TELEMETRY_PHASES = [
      * 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). */
-export function isBoundedTelemetryPhase(phase) {
-    return REGISTERED_PHASES.has(phase);
-}
 /**
  * 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

package/node_modules/pi-lens/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/node_modules/pi-lens/dist/clients/bus-events-logger.js

@@ -22,8 +22,7 @@
  * This module gives bus events the same durable trace every other pi-lens
  * subsystem already has (latency.log, cascade.log, read-guard.log, ...) —
  * see clients/latency-logger.ts for the house pattern this mirrors exactly:
- * one shared `createNdjsonLogger` writer, `isTestMode()` no-op guard,
- * `getBusEventsLogPath()` for testability.
+ * one shared `createNdjsonLogger` writer, `isTestMode()` no-op guard.
  *
  * Logging volume: `emitted` and `emit_failed` are logged on every call —
  * they're the two outcomes an operator actually needs a per-event trace for.
@@ -44,11 +43,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,
@@ -104,10 +103,3 @@ export function emitBusEventRollupAtSessionEnd(cwd) {
     }
     resetBusEventRollupCounts();
 }
-export function getBusEventsLogPath() {
-    return BUS_EVENTS_LOG_FILE;
-}
-/** Resolve once all enqueued bus-event writes are on disk (tests/shutdown). */
-export function flushBusEventsLog() {
-    return writer.flush();
-}

package/node_modules/pi-lens/dist/clients/cache/rule-cache.js

@@ -7,9 +7,10 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { reportBundledResourceDirHealth } from "../bundled-resource-health.js";
 import { getProjectDataDir } from "../file-utils.js";
 import { readJsonCache } from "../json-cache-read.js";
-import { resolvePackagePath } from "../package-root.js";
+import { BUNDLED_QUERIES_ROOT, getBundledQueriesRootHealth, } from "../tree-sitter-query-loader.js";
 import { writeFileAtomic } from "../atomic-write.js";
 import { compareOrdinal } from "../string-utils.js";
 // v4: cache skip_test_files + fix_action — v3 entries silently dropped them,
@@ -48,11 +49,36 @@ export const CACHE_VERSION = "v7";
  * on this prefix mirrors the split `yaml-rule-parser.ts`/`ast-grep-napi.ts`
  * already use for the ast-grep side of the same class (#1105): project-origin
  * trees get a content-hash CONFIRM, bundled trees stay mtime-cheap.
+ *
+ * #2636 review F4: re-exported from `tree-sitter-query-loader.ts`'s
+ * `BUNDLED_QUERIES_ROOT` rather than computed a second time here — the two
+ * modules read the IDENTICAL physical directory, and the "one ledger row"
+ * claim below rests on that being reference equality, not two independently
+ * `resolvePackagePath`-resolved strings that happen to match.
  */
-const BUNDLED_RULES_ROOT = resolvePackagePath(import.meta.url, "rules", "tree-sitter-queries");
+export { BUNDLED_QUERIES_ROOT as BUNDLED_RULES_ROOT } from "../tree-sitter-query-loader.js";
 function isBundledRuleFile(resolvedFile) {
-    return (resolvedFile === BUNDLED_RULES_ROOT ||
-        resolvedFile.startsWith(BUNDLED_RULES_ROOT + path.sep));
+    return (resolvedFile === BUNDLED_QUERIES_ROOT ||
+        resolvedFile.startsWith(BUNDLED_QUERIES_ROOT + path.sep));
+}
+/**
+ * #2636 (the #2626 class sweep's tree-sitter leg): the bundled
+ * tree-sitter-queries root above was used unconditionally with no existence
+ * check — same managed-cache-relocation gap #2626 fixed for `skills/`.
+ * Purely observational (never gates `isBundledRuleFile`'s classification):
+ * records a bounded `tree-sitter-queries-dir-missing` degradation only when
+ * the bundled root is absent, unreadable, or (uncommonly) present but empty.
+ * Shares the exact kind + subject `clients/tree-sitter-query-loader.ts`'s
+ * `ruleFilesForLanguage` reports under — both read the SAME physical
+ * directory (`getBundledQueriesRootHealth`'s process-lifetime memo, #2636
+ * review F6 — this constructor runs per dispatched file, so an unmemoized
+ * `readdirSync` here would be the same unconditional hot-path cost the
+ * class doc comment above forbids for rule-file hashing), so the ledger's
+ * own (kind, subject) dedup collapses whichever call site observes it first
+ * into ONE row rather than two duplicates.
+ */
+function reportBundledRulesRootHealth() {
+    reportBundledResourceDirHealth("tree-sitter-queries-dir-missing", BUNDLED_QUERIES_ROOT, getBundledQueriesRootHealth(), "bundled tree-sitter query rules");
 }
 export class RuleCache {
     cacheFile;
@@ -60,6 +86,7 @@ export class RuleCache {
     language;
     constructor(language, rootDir = process.cwd()) {
         this.language = language;
+        reportBundledRulesRootHealth();
         this.cacheDir = path.join(getProjectDataDir(rootDir), "cache");
         this.cacheFile = path.join(this.cacheDir, `${language}-rules-${CACHE_VERSION}.json`);
     }