@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/lens-flag-registry.js

@@ -164,6 +164,22 @@ export const LENS_FLAGS = [
         default: false,
         scope: "global",
     },
+    {
+        name: "no-lazy-tools",
+        description: "Keep all pi-lens tools active to avoid tool-list cache changes. Also via tools.lazy=false in ~/.pi-lens/config.json.",
+        configKey: "tools.lazy",
+        negated: true,
+        default: false,
+        scope: "global",
+    },
+    {
+        name: "lens-turn-end-madge",
+        description: "Run the per-turn-end madge circular-dependency check on import-changed files. Off by default: the pass only writes debug output, and user-facing madge diagnostics come from the session-start scan cache + lens_diagnostics. Also via turnEnd.madge.enabled=true in ~/.pi-lens/config.json.",
+        configKey: "turnEnd.madge.enabled",
+        negated: false,
+        default: false,
+        scope: "global",
+    },
 ];
 const byName = new Map(LENS_FLAGS.map((spec) => [spec.name, spec]));
 export function getLensFlagSpec(name) {

package/node_modules/pi-lens/dist/clients/live-bus-emitter.js

@@ -1,4 +1,6 @@
 import { recordDegradation } from "./degradation-ledger.js";
+import { probeCtxActive } from "./session-lifecycle.js";
+import { logBusEvent, } from "./bus-events-logger.js";
 const STALE_CTX_MESSAGE = "This extension ctx is stale after session replacement";
 /** Ledger a dead activation once, at the publisher's occurrence-window guard. */
 export function recordStaleBusFailure(subject, error) {
@@ -19,8 +21,26 @@ export function createLiveBusEmitter() {
             getter = next;
             emit = undefined;
         },
-        get() {
-            return getter?.() ?? emit;
+        resolve() {
+            // Invoke the getter for every delivery so session_start rewiring can
+            // replace a captured pre-await activation with the current primary. When
+            // the current target is nevertheless confirmed stale, never invoke it.
+            const target = getter?.() ?? emit;
+            if (!target)
+                return { outcome: "unwired", ctxSource: "unwired" };
+            if (typeof target === "function") {
+                return { outcome: "ready", emit: target, ctxSource: "global-fallback" };
+            }
+            // Object targets are always "own"-sourced (only `wire(fn)`'s bare
+            // function arm is "global-fallback", and it never reaches this
+            // branch) — compute it once so the ready/stale-session outcomes
+            // below both carry the same value instead of restating the
+            // literal independently.
+            const ctxSource = "own";
+            if (probeCtxActive(target.ctx) === false) {
+                return { outcome: "stale-session", ctxSource };
+            }
+            return { outcome: "ready", emit: target.emit, ctxSource };
         },
         reset() {
             emit = undefined;
@@ -28,3 +48,26 @@ export function createLiveBusEmitter() {
         },
     };
 }
+/**
+ * Resolve through the shared stale-session guard and record a declined
+ * target.
+ *
+ * `entry` is a THUNK, not a value (M1, #1415 review): building the log entry
+ * (every producer's version normalizes `cwd` via `normalizeFilePath`, a sync
+ * `realpathSync.native` call on Windows) is real per-publish cost that used
+ * to be paid on EVERY call regardless of outcome, even though it is only
+ * consumed on the `stale-session` branch. Invoking the thunk only there means
+ * the common `ready` path pays nothing for it.
+ */
+export function resolveLiveBusEmitter(liveEmitter, entry) {
+    const resolution = liveEmitter.resolve();
+    if (resolution.outcome === "stale-session") {
+        logBusEvent({
+            ...entry(),
+            outcome: "skipped_stale_session",
+            level: "info",
+            ctxSource: resolution.ctxSource,
+        });
+    }
+    return resolution;
+}

package/node_modules/pi-lens/dist/clients/lsp/aggregation.js

@@ -26,9 +26,12 @@
  *   receive `options.auxGraceMs` before the race finalises. Aux results within
  *   that window are included; later arrivals are dropped. When no descriptors
  *   carry `role:"auxiliary"` the aux-grace path is never entered.
- * @param options.auxGraceMs - Grace period given to auxiliary promises after all
- *   primary promises have settled. Only relevant when at least one descriptor
- *   carries `role:"auxiliary"`. Defaults to 500ms.
+ * @param options.auxGraceMs - Ceiling on the grace period given to auxiliary
+ *   promises after all primary promises have settled. Only relevant when at
+ *   least one descriptor carries `role:"auxiliary"`. Defaults to 500ms. When a
+ *   still-pending auxiliary's descriptor carries `budgetMs`, the actual window
+ *   is `min(auxGraceMs, max(budgetMs of still-pending auxiliaries))` — see
+ *   `PromiseDescriptor.budgetMs`.
  */
 export async function raceToCompletion(promises, shouldComplete, options = { timeoutMs: 1500 }) {
     const results = new Array(promises.length).fill(undefined);
@@ -76,7 +79,30 @@ export async function raceToCompletion(promises, shouldComplete, options = { tim
             if (auxGraceStarted || completed)
                 return;
             auxGraceStarted = true;
-            const graceMs = options.auxGraceMs ?? 500;
+            const ceilingMs = options.auxGraceMs ?? 500;
+            // #1458 S2: cap the grace window by the still-pending auxiliaries' own
+            // declared budgets, not just the flat ceiling — mirrors touchFile's
+            // per-server `min(declared, ceiling)`.
+            //
+            // This is ONE shared timer, not a deadline per promise, so it grants
+            // every pending auxiliary the window of its slowest pending sibling.
+            // That is safe here only because of an invariant the caller upholds,
+            // not because of anything this function enforces: every promise
+            // `getDiagnostics` passes in is already self-bounded by the same
+            // `strategy.aggregateWaitMs` it declares as `budgetMs`, so a fast
+            // auxiliary resolves on its own deadline long before a slow sibling's
+            // window expires. A caller that passes a promise NOT self-bounded by
+            // its descriptor's `budgetMs` — or one that outlives it, the way
+            // `expectSemanticSecondPush` extends a primary — would get a window
+            // wider than it declared. `PromiseDescriptor` is public, so treat that
+            // as a real constraint on new callers rather than a theoretical one.
+            const pendingAuxBudgets = [...auxIndices]
+                .filter((i) => results[i] === undefined)
+                .map((i) => descriptors[i]?.budgetMs)
+                .filter((b) => typeof b === "number" && b >= 0);
+            const graceMs = pendingAuxBudgets.length > 0
+                ? Math.min(ceilingMs, Math.max(...pendingAuxBudgets))
+                : ceilingMs;
             if (graceMs <= 0) {
                 finalize();
                 return;

package/node_modules/pi-lens/dist/clients/lsp/cascade-tier.js

@@ -32,6 +32,12 @@
  * NOT tier-3 — the caller keeps today's full in-lane wait. Fail-safe is
  * always "wait like before".
  *
+ * Native TS7 is the cascade-only exception. It is not silent on clean, but
+ * its publication does not settle inside the cold-snapshot budget. Cascade
+ * classifies it as `collect-later`, sends the same no-wait touch, and
+ * reconciles its later per-file push or pull publication. The shared server
+ * policy remains `waits`, so main-lane behavior does not change.
+ *
  * #524/#529/#541/#558: a server id can now be backed by more than one actual
  * binary — "typescript" is classic typescript-language-server OR TS7's
  * native `tsc --lsp --stdio` (PR #526). PR #526 originally routed the
@@ -46,18 +52,46 @@
  * confirmed still silent (`cleanPubs=0(v:0)`) in the same run. This is
  * therefore an EVIDENCE-BASED revert, not the original unverified caution:
  * native-ts7's clean-signal behavior IS known, and it is "publishes, not
- * silent". The snapshot's `launchVariant` marker again routes a native-ts7
- * snapshot through "waits" while the shared `silentOnClean` flag stays
- * `true` for classic. `scripts/probe-clean-signal.mjs`'s drift check no
+ * silent". The shared classifier still routes a native-ts7 snapshot through
+ * `waits`. The cascade-only wrapper routes it through `collect-later` because
+ * the measured publication arrives after the in-lane budget. The shared
+ * `silentOnClean` flag stays `true` for classic.
+ * `scripts/probe-clean-signal.mjs`'s drift check no
  * longer compares native-ts7 rows against the shared marker (it now expects
  * `false` for them explicitly) — see that file's header for the regression
  * watch this sets up for a future TS7 build that becomes silent again.
  */
 import { logCascade } from "../cascade-logger.js";
+import { incrementDegradationCount } from "../degradation-ledger.js";
 import { logLatency } from "../latency-logger.js";
 import { normalizeMapKey } from "../path-utils.js";
 import { registerQuietWindowTask } from "../quiet-window.js";
-export { classifyCascadeWaitTier, classifyServerWaitTier, } from "./wait-policy/classification.js";
+import { classifyCascadeWaitTier as classifySharedCascadeWaitTier, classifyServerWaitTier, resolvePrimaryServerForWaitPolicy, } from "./wait-policy/classification.js";
+export { classifyServerWaitTier };
+/**
+ * The cascade lane's wait tier for `filePath`. DELEGATES to the shared
+ * `wait-policy/classification.ts` rule — this wrapper adds exactly one
+ * cascade-only override on top of it (native TS7's push-only snapshot →
+ * `collect-later`) and never re-implements the classification itself.
+ *
+ * #1444 coverage tradeoff: the no-wait touch this tier selects is
+ * `clientScope: "primary"`, and the tier itself is decided from the PRIMARY
+ * (non-auxiliary) server alone. That tradeoff already existed for
+ * `tier3-silent`; the override enlarges the population it applies to — every
+ * native-TS7 TypeScript neighbour now takes the no-wait path too, so an
+ * auxiliary server configured for those files no longer gets touched in-lane
+ * for them (its findings arrive via the next per-edit dispatch, as they
+ * already did for classic tier-3 files).
+ */
+export function classifyCascadeWaitTier(lspService, filePath, snapshots) {
+    const primary = resolvePrimaryServerForWaitPolicy(filePath, snapshots);
+    if (primary?.serverId === "typescript" &&
+        primary.snapshot?.launchVariant === "native-ts7" &&
+        primary.snapshot.workspaceDiagnosticsSupport?.mode === "push-only") {
+        return "collect-later";
+    }
+    return classifySharedCascadeWaitTier(lspService, filePath, snapshots);
+}
 // --- Kill switch (lazy, memoized — house style per clients/runtime-config.ts /
 // clients/quiet-window.ts's isQuietWindowEnabled) ---
 let _enabledCache;
@@ -78,20 +112,88 @@ export function _resetTierAwareCascadeEnabledForTests() {
 // replaces the earlier entry (only the most recent touch matters — an
 // older touch's diagnostics, if they ever arrive, are still a strict superset
 // concern the newer touch already re-supersedes via didOpen/didChange).
+//
+// #1899: the registry is drained in full by every reconcile sweep, but nothing
+// bounded it BETWEEN sweeps. The sweep runs on pi's `agent_settled` quiet
+// window, and a session can go a long time without one — dogfood logs show
+// sweeps up to 52 minutes apart. So the two bounds below are the registry's
+// own, independent of when a sweep arrives:
+//
+//   - `MAX_OUTSTANDING_TOUCHES` caps the entry count. Entries are held in
+//     touch order (see `recordOutstandingCascadeTouch`), so eviction takes the
+//     oldest touch at O(1).
+//   - `OUTSTANDING_TOUCH_MAX_AGE_MS` caps how long a touch stays reconcilable.
+//     Past it, the touch is discarded rather than answered: re-injecting a
+//     neighbour error, or clearing a footer entry, from a touch fired that
+//     long ago reports a state the agent has already moved past.
+//
+// Both constants are sized from the 2026-08-09..20 dogfood window (cascade.log,
+// 67 sweeps / 756 entries): the largest single sweep held 53 entries, and a
+// 15-minute age bound retains 72 of the 80 outcomes that ever resolved (90%)
+// while discarding the tail that resolved after ~26-52 minutes.
+const MAX_OUTSTANDING_TOUCHES = 256;
+const OUTSTANDING_TOUCH_MAX_AGE_MS = 15 * 60_000;
 const _outstandingTouches = new Map();
+/** Entries dropped by the age bound since the last sweep reported. */
+let _expiredSinceLastSweep = 0;
+/** Entries dropped by the size cap since the last sweep reported. */
+let _evictedSinceLastSweep = 0;
+/**
+ * Drop every entry older than `OUTSTANDING_TOUCH_MAX_AGE_MS`. The map is held
+ * in touch order, so the expired entries are a prefix and the walk stops at
+ * the first live one.
+ */
+function pruneExpiredOutstandingTouches(now) {
+    for (const [key, touch] of _outstandingTouches) {
+        if (now - touch.touchedAt <= OUTSTANDING_TOUCH_MAX_AGE_MS)
+            break;
+        _outstandingTouches.delete(key);
+        _expiredSinceLastSweep++;
+    }
+}
 /**
  * Record a Tier-3 cascade touch that skipped its in-lane wait. Called right
  * after the (still-performed) didOpen/didChange notify, before returning
  * without waiting. `touchedAt` must be sampled BEFORE the notify (see the
  * field doc) so the reconcile comparison can never misread a publish that
  * raced the record as pre-touch.
+ *
+ * #1899: also enforces the registry's two bounds. The `delete` before the
+ * `set` is load-bearing — `Map.set` on an existing key keeps the key's
+ * ORIGINAL insertion position, so without it a re-touched file would keep a
+ * stale position and both the age prefix walk and the oldest-first eviction
+ * would pick the wrong entry.
  */
 export function recordOutstandingCascadeTouch(entry) {
-    _outstandingTouches.set(normalizeMapKey(entry.filePath), entry);
+    const key = normalizeMapKey(entry.filePath);
+    _outstandingTouches.delete(key);
+    // `Date.now()`, not `entry.touchedAt`: the caller samples `touchedAt` before
+    // its notify, so it trails real time, and the age bound is a statement about
+    // the clock rather than about the newest touch's own stamp.
+    pruneExpiredOutstandingTouches(Date.now());
+    _outstandingTouches.set(key, entry);
+    while (_outstandingTouches.size > MAX_OUTSTANDING_TOUCHES) {
+        const oldest = _outstandingTouches.keys().next();
+        if (oldest.done)
+            break;
+        _outstandingTouches.delete(oldest.value);
+        _evictedSinceLastSweep++;
+        // Bounded by construction: one ledger tally per session, not per
+        // eviction event. The subject is the cap itself rather than the evicted
+        // path — the discriminating fact is "this session overflowed the tier-3
+        // backlog", and per-path subjects would unbound the ledger group.
+        incrementDegradationCount({
+            kind: "cascade-tier3-backlog-evicted",
+            subject: `cap=${MAX_OUTSTANDING_TOUCHES}`,
+            reason: "tier-3 outstanding-touch registry hit its cap before a quiet-window reconcile drained it; the oldest touch was dropped unanswered",
+        });
+    }
 }
 /** Test-only: clear the outstanding-touch registry between test cases. */
 export function _resetOutstandingCascadeTouchesForTests() {
     _outstandingTouches.clear();
+    _expiredSinceLastSweep = 0;
+    _evictedSinceLastSweep = 0;
 }
 /** Test-only: peek at the registry without mutating it. */
 export function _getOutstandingCascadeTouchesForTests() {
@@ -122,6 +224,10 @@ export function _getOutstandingCascadeTouchesForTests() {
  */
 export async function reconcileOutstandingCascadeTouches(lspService) {
     const outcomes = [];
+    // #1899: the age bound applies at sweep time too, not only at record time —
+    // a registry that received no further touches would otherwise hand the sweep
+    // entries of unbounded age.
+    pruneExpiredOutstandingTouches(Date.now());
     const entries = [..._outstandingTouches.entries()];
     _outstandingTouches.clear();
     for (const [key, touch] of entries) {
@@ -133,6 +239,7 @@ export async function reconcileOutstandingCascadeTouches(lspService) {
                     filePath: touch.filePath,
                     serverId: touch.serverId,
                     outcome: "unresolved",
+                    unresolvedReason: spawned ? "server-mismatch" : "warm-miss",
                     ageMs,
                 });
                 continue;
@@ -147,6 +254,7 @@ export async function reconcileOutstandingCascadeTouches(lspService) {
                     filePath: touch.filePath,
                     serverId: touch.serverId,
                     outcome: "unresolved",
+                    unresolvedReason: entry ? "no-publish-since-touch" : "no-publish",
                     ageMs,
                 });
                 continue;
@@ -158,6 +266,7 @@ export async function reconcileOutstandingCascadeTouches(lspService) {
                 outcome: found ? "resolved-found" : "resolved-clean",
                 ageMs,
                 diagnosticCount: entry.diags.length,
+                publishedAt: entry.ts,
                 // #1023: carry the diagnostics so the task can re-surface them.
                 ...(found && { diagnostics: entry.diags }),
             });
@@ -167,6 +276,7 @@ export async function reconcileOutstandingCascadeTouches(lspService) {
                 filePath: touch.filePath,
                 serverId: touch.serverId,
                 outcome: "unresolved",
+                unresolvedReason: "error",
                 ageMs,
             });
             logLatency({
@@ -193,23 +303,30 @@ export function registerCascadeTierReconcileTask(getLspService, options = {}) {
     registerQuietWindowTask("cascade_tier3_reconcile", async () => {
         if (!isTierAwareCascadeEnabled())
             return;
-        if (_outstandingTouches.size === 0)
-            return;
         const outcomes = await reconcileOutstandingCascadeTouches(getLspService());
-        if (outcomes.length === 0)
-            return;
         // #1023: re-inject each resolved-found neighbor error so it reaches the
-        // agent (previously logs-only). Isolated per-outcome — a throwing callback
-        // must not drop the log line or the sibling re-injections.
+        // agent (previously logs-only). #1444: hand each resolved-CLEAN outcome to
+        // the footer reconcile for the mirror-image case. Isolated per-outcome — a
+        // throwing callback must not drop the log line or the sibling deliveries.
         for (const o of outcomes) {
-            if (o.outcome !== "resolved-found" || !o.diagnostics?.length)
-                continue;
             try {
-                options.onResolvedFound?.({
-                    filePath: o.filePath,
-                    serverId: o.serverId,
-                    diagnostics: o.diagnostics,
-                });
+                if (o.outcome === "resolved-found" && o.diagnostics?.length) {
+                    options.onResolvedFound?.({
+                        filePath: o.filePath,
+                        serverId: o.serverId,
+                        diagnostics: o.diagnostics,
+                    });
+                }
+                else if (o.outcome === "resolved-clean" && o.publishedAt != null) {
+                    // #1444: the stale-footer half of the same honesty problem — the
+                    // neighbour proved clean, but only after the in-lane wait was
+                    // skipped, so nothing has cleared its earlier error entries.
+                    options.onResolvedClean?.({
+                        filePath: o.filePath,
+                        serverId: o.serverId,
+                        publishedAt: o.publishedAt,
+                    });
+                }
             }
             catch {
                 // best-effort surfacing; the log below is the durable record.
@@ -219,16 +336,31 @@ export function registerCascadeTierReconcileTask(getLspService, options = {}) {
         let resolvedClean = 0;
         let unresolved = 0;
         let ageSumMs = 0;
+        let maxAgeMs = 0;
+        const unresolvedByReason = {};
         for (const o of outcomes) {
             if (o.outcome === "resolved-found")
                 resolvedFound++;
             else if (o.outcome === "resolved-clean")
                 resolvedClean++;
-            else
+            else {
                 unresolved++;
+                const reason = o.unresolvedReason ?? "no-publish";
+                unresolvedByReason[reason] = (unresolvedByReason[reason] ?? 0) + 1;
+            }
             ageSumMs += o.ageMs;
+            if (o.ageMs > maxAgeMs)
+                maxAgeMs = o.ageMs;
         }
-        const avgAgeMs = Math.round(ageSumMs / outcomes.length);
+        const avgAgeMs = outcomes.length
+            ? Math.round(ageSumMs / outcomes.length)
+            : 0;
+        // #1899: emitted on EVERY sweep, including the empty one. The backlog's
+        // size was previously observable only when it was non-empty, so "the
+        // queue is drained" and "the sweep never ran" read identically in
+        // cascade.log. This record is the backlog gauge: what the sweep drained,
+        // what the two bounds dropped since the last sweep, and what the bounds
+        // are, so a reader never has to know the constants to judge the numbers.
         logCascade({
             phase: "cascade_tier3_reconcile",
             filePath: "<quiet-window>",
@@ -237,10 +369,18 @@ export function registerCascadeTierReconcileTask(getLspService, options = {}) {
                 resolvedFound,
                 resolvedClean,
                 unresolved,
+                unresolvedByReason,
                 avgAgeMs,
+                maxAgeMs,
+                expired: _expiredSinceLastSweep,
+                evicted: _evictedSinceLastSweep,
+                capacity: MAX_OUTSTANDING_TOUCHES,
+                maxAgeCapMs: OUTSTANDING_TOUCH_MAX_AGE_MS,
                 outcomes,
             },
         });
+        _expiredSinceLastSweep = 0;
+        _evictedSinceLastSweep = 0;
     });
 }
 /** Test-only: undo registerCascadeTierReconcileTask's idempotency guard. */