@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/cascade-budget.js

@@ -0,0 +1,196 @@
+/**
+ * Cascade neighbour-budget sizing (#1462).
+ *
+ * The flat neighbour cap (40) and the turn-end settle wait (5000 ms) were set in
+ * two different files with nothing relating them. Dogfood 2026-08-15 measured
+ * what that costs: n=50 cascades, median 30 ms, max 3.88 s at nbr=40 — and with
+ * a `reverse_deps_cache` refresh ahead of the graph build (2046 ms for
+ * `logger.ts`) the run overran the turn_end cap, so `cascade_settle_wait`
+ * returned `settled: 0` and the finding arrived a turn late.
+ *
+ * ## What a slow run actually costs
+ *
+ * It is NOT lost. `RuntimeCoordinator.settleCascadeRuns` re-parks a promise
+ * still in flight at the cap, `agent_settled` gives it a second and more
+ * generous drain (`cascade_carry_over_settle`, `quietWindowWaitMs`, 15 000 ms),
+ * and `beginTurn` deliberately keeps `_pendingCascadeRuns` so anything still
+ * running surfaces at a later turn_end — that is #1443, and pre-#450 these
+ * findings were always awaited. So the real trade is:
+ *
+ *   full neighbour set, one turn late   vs.   a narrowed set, on time,
+ *                                             with the remainder lost for good
+ *
+ * Narrowing is therefore only worth paying for when it genuinely converts a
+ * late run into an on-time one. That gives three zones, and the derivation
+ * below is exactly those three:
+ *
+ *   fits         the full walk still fits the on-time window — nothing to do
+ *   narrowed     the RESCUE BAND: the full walk no longer fits but a shorter
+ *                one does, so trading the tail for on-time delivery buys
+ *                something real
+ *   past-rescue  not even a floor-sized walk fits any more, so narrowing would
+ *                drop neighbours permanently AND still miss the window. Keep
+ *                the full budget and let the carry-over deliver it complete.
+ *                This is the cold-session case: a fresh graph build measures up
+ *                to ~19 s (see `runtime-coordinator.ts`'s carry-over note), and
+ *                a floor-sized stub there is strictly worse than pre-#1462.
+ *
+ * One more guard, for the same reason. If the on-time window could not fit a
+ * full walk even at zero prelude, there is no LATE run to rescue — every
+ * cascade would be permanently downsized because a *wait* was configured small.
+ * That is a budget change wearing a timeout's clothes, so the derivation stands
+ * down entirely (`no-rescue-window`) and the flat cap applies. This is what
+ * keeps `PI_LENS_CASCADE_SETTLE_WAIT_MS` from doubling as a neighbour-count
+ * knob: at the 5000/100/40 defaults the band is a prelude of 1.0–4.5 s, and
+ * shrinking the wait to 1000 ms disables narrowing rather than capping every
+ * cascade at ~10 neighbours.
+ */
+import { recordDegradationOnce } from "./degradation-ledger.js";
+import { toPositiveFinite } from "./env-utils.js";
+// The knobs only, never the scheduler — this module is arithmetic and has no
+// business depending on a task registry to read two numbers (#1462 review N4).
+// Note it buys nothing at load time: `runtime-config.js` below already reaches
+// `pidusage` via `lens-config.js`.
+import { isQuietWindowEnabled, quietWindowWaitMs, } from "./quiet-window-config.js";
+import { RUNTIME_CONFIG } from "./runtime-config.js";
+/**
+ * Bounded wait for the turn's deferred cascade computes (#450) to settle before
+ * they are merged at turn_end. A late compute is carried over, never dropped.
+ *
+ * `0` is a meaningful setting (never block turn_end), so this deliberately does
+ * NOT use `lazyEnvNumber` — that helper treats 0 as "unset" and would silently
+ * restore the 5000 ms default.
+ */
+export function cascadeSettleWaitMs() {
+    const raw = Number(process.env.PI_LENS_CASCADE_SETTLE_WAIT_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : 5000;
+}
+/** The budget floor, and the minimum any env override of the cap can produce. */
+const MIN_NEIGHBOUR_BUDGET = RUNTIME_CONFIG.pipeline.cascadeMaxFiles;
+/**
+ * The flat per-run cap: the most neighbours a cascade walks. Still the ceiling
+ * — the derivation below only ever narrows it, and only inside the rescue band.
+ */
+const DEFAULT_NEIGHBOUR_BUDGET = 40;
+export const CASCADE_NEIGHBOUR_BUDGET = Math.max(MIN_NEIGHBOUR_BUDGET, Number.parseInt(process.env.PI_LENS_CASCADE_NEIGHBOUR_BUDGET ?? "40", 10) ||
+    DEFAULT_NEIGHBOUR_BUDGET);
+/**
+ * True when `PI_LENS_CASCADE_NEIGHBOUR_BUDGET` moved the ceiling away from the
+ * default (#1462 review F-E). Raising it far enough can push
+ * `ceiling * perNeighbourMs` past the settle window, so EVERY cascade reads
+ * `no-rescue-window` — the whole derivation disarmed by a cap change nobody
+ * meant as a timeout change. Read once at load, same lifetime as the constant
+ * it describes.
+ */
+const NEIGHBOUR_BUDGET_OVERRIDDEN = process.env.PI_LENS_CASCADE_NEIGHBOUR_BUDGET !== undefined &&
+    CASCADE_NEIGHBOUR_BUDGET !== DEFAULT_NEIGHBOUR_BUDGET;
+/**
+ * Marginal wall-clock cost of one more neighbour in the walk, in ms. Calibrated
+ * on the 2026-08-15 dogfood tail: 3.88 s at nbr=40 and 3.71 s at nbr=38, both
+ * ~97 ms per neighbour. Touches fan out in parallel, so this is the observed
+ * marginal cost under LSP contention, not one touch's own latency.
+ *
+ * It is an ESTIMATE, and the derivation is sensitive to it: if the true cost is
+ * materially above this, a walk sized against it still overruns (the rescue
+ * fails and the tail was dropped for nothing). `scripts/bench-cascade-budget.mjs
+ * --true-cost-ms=<n>` measures that sensitivity directly. Rounded UP from the
+ * measurement so the estimate errs toward narrowing less.
+ */
+const DEFAULT_NEIGHBOUR_COST_MS = 100;
+/** Read per call — sized once per cascade run, never on a hot path. */
+function neighbourCostMs() {
+    return (toPositiveFinite(process.env.PI_LENS_CASCADE_NEIGHBOUR_COST_MS) ||
+        DEFAULT_NEIGHBOUR_COST_MS);
+}
+function neighbourFloor() {
+    return (toPositiveFinite(process.env.PI_LENS_CASCADE_NEIGHBOUR_FLOOR) ||
+        MIN_NEIGHBOUR_BUDGET);
+}
+/**
+ * Size one run's neighbour walk against the on-time window supplied by its
+ * caller.
+ *
+ * `elapsedMs` is arithmetic input, not an observation made by this function.
+ * The production caller measures it against the active turn_end settle window
+ * and passes that elapsed time here. When that boundary is unavailable, the
+ * caller passes zero to preserve the flat cap. Legacy callers may still pass
+ * deferred run age for compatibility.
+ *
+ * Every override exists so the derivation can be tested and benchmarked as a
+ * pure function; the function itself does not observe a deferred run's age.
+ */
+export function deriveCascadeNeighbourBudget(options) {
+    const ceiling = options.ceiling ?? CASCADE_NEIGHBOUR_BUDGET;
+    // The floor can never exceed the ceiling — a floor above the cap would make
+    // the derived budget LARGER than the flat one it exists to bound.
+    const floor = Math.min(ceiling, options.floor ?? neighbourFloor());
+    const onTimeMs = options.settleWaitMs ?? cascadeSettleWaitMs();
+    const perNeighbourMs = options.perNeighbourMs ?? neighbourCostMs();
+    const elapsedMs = toPositiveFinite(options.elapsedMs);
+    const remainingMs = onTimeMs - elapsedMs;
+    const deliveryWindowMs = onTimeMs +
+        (options.quietDrainMs ??
+            (isQuietWindowEnabled() ? quietWindowWaitMs() : 0));
+    const full = { budget: ceiling, ceiling, remainingMs, deliveryWindowMs };
+    // No on-time window at all, or one too small to ever fit a full walk. There
+    // is no late run to rescue here, only every run to shrink — stand down.
+    //
+    // Boundary, acknowledged rather than special-cased: at exactly
+    // `onTimeMs === ceiling * perNeighbourMs` this does not fire and the `fits`
+    // zone has zero width, so ANY prelude narrows. Not slightly, either — at
+    // 4000/100/40 a 2 s prelude gives 20 and a 3.5 s prelude gives the floor.
+    // Left alone because the narrowing is honest at that setting: with the
+    // window sized to exactly one full walk, a run that has spent any of it
+    // really would miss, so every one of those cuts is a genuine rescue rather
+    // than the `no-rescue-window` case this guard exists to catch. What it does
+    // cost is headroom — see the divisor bands in the bench's `--sweep` text.
+    if (onTimeMs <= 0 || onTimeMs < ceiling * perNeighbourMs) {
+        // #1462 review F-E: name the override, once per session, when it is the
+        // REASON the derivation stood down — not when a caller under test asked
+        // for a specific ceiling, and not on every one of the cascades this
+        // disarms for the rest of the session.
+        if (options.ceiling === undefined && NEIGHBOUR_BUDGET_OVERRIDDEN) {
+            recordDegradationOnce({
+                kind: "cascade-budget-override-disarmed",
+                subject: "cascade-neighbour-budget",
+                reason: `PI_LENS_CASCADE_NEIGHBOUR_BUDGET=${CASCADE_NEIGHBOUR_BUDGET} needs ` +
+                    `${ceiling * perNeighbourMs}ms to walk the full cap, which exceeds ` +
+                    `the ${onTimeMs}ms settle window — the rescue band is disarmed and ` +
+                    `every cascade keeps the flat (overridden) cap`,
+            });
+        }
+        return { ...full, zone: "no-rescue-window" };
+    }
+    // The full walk still fits. Nothing to buy.
+    if (remainingMs >= ceiling * perNeighbourMs) {
+        return { ...full, zone: "fits" };
+    }
+    // Past rescue: not even a floor-sized walk fits, so narrowing would drop the
+    // tail permanently and still miss the window. The carry-over delivers the
+    // whole set one turn later instead.
+    //
+    // #1462 review F-B, kept rather than shrunk: one dogfood log measured this
+    // zone at 0/1090 cascades, and asked whether a 3-zone module earns its keep
+    // at that frequency. It was measured against the WRITE-relative clock this
+    // same round fixed, which charges elapsed time no cascade actually spent
+    // waiting — so it under-counts how often a genuinely slow compute (a cold
+    // graph build, ~19 s) overlaps an already-running settle window, which is
+    // exactly what this zone exists to catch (F3, a real regression the first
+    // review round found: a floor-sized stub on that cold-start case is
+    // strictly worse than pre-#1462). Reachability under the corrected clock
+    // has not been re-measured; shrinking on a stale sample would trade a
+    // cheap, already-tested guard against a proven regression for a paper
+    // simplification. Revisit if a post-fix dogfood window confirms it still
+    // never fires.
+    if (remainingMs < floor * perNeighbourMs) {
+        return { ...full, zone: "past-rescue" };
+    }
+    // The rescue band: a shorter walk lands on time.
+    return {
+        budget: Math.min(ceiling, Math.max(floor, Math.floor(remainingMs / perNeighbourMs))),
+        ceiling,
+        remainingMs,
+        deliveryWindowMs,
+        zone: "narrowed",
+    };
+}

package/node_modules/pi-lens/dist/clients/cascade-format.js

@@ -3,8 +3,18 @@ import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
     const withErrors = neighbors.filter((n) => n.diagnostics.length > 0);
     const inconclusive = neighbors.filter((n) => n.inconclusive === true && n.diagnostics.length === 0);
-    if (withErrors.length === 0 && inconclusive.length === 0)
+    // #1459: a neighbour whose scanner never looked at it is not a clean leaf. It
+    // is also not `inconclusive` — the language server answered — so it gets its
+    // own honest line instead of being folded into either bucket. Only the
+    // zero-diagnostic case needs saying: a neighbour with findings already renders.
+    const uncovered = neighbors.filter((n) => n.diagnostics.length === 0 &&
+        n.inconclusive !== true &&
+        (n.unconfirmedServerIds?.length ?? 0) > 0);
+    if (withErrors.length === 0 &&
+        inconclusive.length === 0 &&
+        uncovered.length === 0) {
         return "";
+    }
     const noun = options.noun ?? "neighbor";
     let out = withErrors.length > 0
         ? `📐 Cascade errors in ${withErrors.length} ${noun} file(s) — fix before finishing turn:`
@@ -29,6 +39,15 @@ export function formatCascadeNeighborDiagnostics(cwd, neighbors, options = {}) {
             out += `\n  ${toRunnerDisplayPath(cwd, neighbor.filePath)}`;
         }
     }
+    if (uncovered.length > 0) {
+        if (out)
+            out += "\n";
+        out += `⚠️ Cascade scanners did not cover ${uncovered.length} ${noun} file(s) — no findings does NOT mean clean here:`;
+        for (const neighbor of uncovered) {
+            const servers = (neighbor.unconfirmedServerIds ?? []).join(", ");
+            out += `\n  ${toRunnerDisplayPath(cwd, neighbor.filePath)} (not scanned by ${servers})`;
+        }
+    }
     return out;
 }
 /**

package/node_modules/pi-lens/dist/clients/cascade-types.js

@@ -1 +1,9 @@
-export {};
+/**
+ * How long a cascade neighbour's diagnostics stay usable (#1816).
+ *
+ * One constant for two consumers that each declared their own `240_000`:
+ * `clients/lsp/index.ts` (the neighbour-diagnostics cache) and
+ * `clients/dispatch/integration.ts` (the cascade turn scope). They must move
+ * together — a split pair reads as two independent policies and drifts.
+ */
+export const CASCADE_DIAGNOSTICS_TTL_MS = 240_000;

package/node_modules/pi-lens/dist/clients/child-unref.js

@@ -60,13 +60,24 @@ export function unrefChildAndPipes(child) {
  * here already has).
  */
 export function spawnCollectStdout(command, args, options) {
+    return spawnCollectStdoutResult(command, args, options).then((result) => result.stdout);
+}
+/**
+ * `spawnCollectStdout` plus the reason the output is what it is. Same spawn,
+ * unref, collect, settle plumbing; the only additions are an optional hard
+ * timeout and a status discriminator. Never rejects.
+ */
+export function spawnCollectStdoutResult(command, args, options, collectOptions = {}) {
     return new Promise((resolve) => {
         let settled = false;
-        const settle = (value) => {
+        let timer;
+        const settle = (result) => {
             if (settled)
                 return;
             settled = true;
-            resolve(value);
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
         };
         try {
             const child = nodeSpawn(command, args, options);
@@ -75,11 +86,48 @@ export function spawnCollectStdout(command, args, options) {
             child.stdout?.on("data", (chunk) => {
                 out += chunk.toString();
             });
-            child.once("error", () => settle(""));
-            child.once("close", () => settle(out));
+            child.once("error", (error) => settle({ stdout: "", status: "spawn-error", error }));
+            child.once("close", (code, signal) => settle(code === 0 && signal === null
+                ? { stdout: out, status: "ok" }
+                : {
+                    stdout: "",
+                    status: "exit-error",
+                    exitCode: code,
+                    exitSignal: signal,
+                }));
+            const timeoutMs = collectOptions.timeoutMs;
+            if (typeof timeoutMs === "number" && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    // Settle only AFTER the child's fate is known. Killing and
+                    // resolving in the same tick bounds the caller and abandons the
+                    // child, which is the leak this timeout exists to prevent.
+                    void terminateTimedOutChild(child, collectOptions.onTimeout).then((timeoutKill) => settle({ stdout: out, status: "timeout", timeoutKill }));
+                }, timeoutMs);
+                timer.unref();
+            }
         }
-        catch {
-            settle("");
+        catch (error) {
+            settle({ stdout: "", status: "spawn-error", error });
         }
     });
 }
+/** Run the caller's termination handler, or the bare-signal default, and
+ *  never let either throw out of the timeout path. */
+async function terminateTimedOutChild(child, onTimeout) {
+    if (onTimeout) {
+        try {
+            return await onTimeout(child);
+        }
+        catch {
+            // A handler that threw did not verify anything.
+            return "unverified";
+        }
+    }
+    try {
+        child.kill();
+    }
+    catch {
+        // best-effort — the child may already be gone
+    }
+    return "unverified";
+}

package/node_modules/pi-lens/dist/clients/code-quality-warnings.js

@@ -1,29 +1,47 @@
-import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 import { getProjectDataDir } from "./file-utils.js";
+import { normalizeMessage, stableFindingId } from "./finding-identity.js";
 import { normalizeMapKey } from "./path-utils.js";
-function normalizeMessage(message) {
-    return message.replace(/\s+/g, " ").trim().toLowerCase();
-}
-function hashText(value, length = 10) {
-    return createHash("sha256").update(value).digest("hex").slice(0, length);
-}
-function relativeFile(filePath, cwd) {
-    const rel = path.relative(cwd, filePath).replace(/\\/g, "/");
-    return rel && !rel.startsWith("..") ? rel : normalizeMapKey(filePath);
-}
+/**
+ * Report-budget precedence (#1777). A hint is an opinion; a warning is a
+ * finding. When the report is capped, warnings must be spent first, or an
+ * alphabetically-early file's hints can push every real warning out of the
+ * agent's view — the exact "hints dominate the stream" failure the hint tier
+ * exists to prevent.
+ */
+const TIER_BUDGET_ORDER = [
+    "warning",
+    "info",
+    "hint",
+];
+/** #1816: was a local `relativeFile|tool|rule|code|normalizedMessage|line`
+ * hash (raw, non-canonicalized `relativeFile`, 10-char hash), independently
+ * hand-rolled from `actionable-warnings.ts`'s twin and
+ * `diagnostic-dispositions.ts`'s canonicalizing original. Now the shared
+ * `finding-identity.js` builder (canonicalizes `cwd`/`filePath` through
+ * `normalizeMapKey`, hashes to 12 chars). No back-compat migration needed
+ * here: `cq:` ids are never a keyed lookup — `buildCodeQualityWarningsReport`
+ * regenerates the whole report fresh every turn, callers only ever cache and
+ * replay the report wholesale (`tools/lens-diagnostics.ts` reads it via
+ * `cacheManager.readCache<CodeQualityWarningsReport>`, never by `id`), and
+ * `appendCodeQualityWarningsHistory` just append-only-logs the id for
+ * observability, never look it back up. Contrast `actionable-warnings.ts`,
+ * whose `actionable-warning-state.json` DOES key a persisted suppression
+ * store on `aw:` — that one migrates. */
 function createCodeQualityWarningId(args) {
-    const parts = [
-        relativeFile(args.filePath, args.cwd),
-        args.tool ?? "",
-        args.rule ?? "",
-        String(args.code ?? ""),
-        normalizeMessage(args.message),
-        String(args.line ?? ""),
-    ];
-    return `cq:${hashText(parts.join("|"))}`;
+    return stableFindingId("cq:", {
+        cwd: args.cwd,
+        filePath: args.filePath,
+        parts: [
+            args.tool,
+            args.rule,
+            args.code,
+            normalizeMessage(args.message),
+            args.line,
+        ],
+    });
 }
 function categorize(diagnostic) {
     const haystack = `${diagnostic.tool} ${diagnostic.rule ?? ""} ${diagnostic.code ?? ""} ${diagnostic.message}`.toLowerCase();
@@ -93,11 +111,22 @@ export function buildCodeQualityWarningsReport(args) {
             continue;
         byId.set(warning.id, warning);
     }
-    const merged = [...byId.values()]
-        .sort((a, b) => a.displayPath.localeCompare(b.displayPath) ||
+    const byDisplayOrder = (a, b) => a.displayPath.localeCompare(b.displayPath) ||
         (a.line ?? 0) - (b.line ?? 0) ||
-        a.message.localeCompare(b.message))
-        .slice(0, maxWarnings);
+        a.message.localeCompare(b.message);
+    // Spend the budget tier by tier (see TIER_BUDGET_ORDER), then restore
+    // display order so the report still reads file by file, line by line.
+    const candidates = [...byId.values()].sort(byDisplayOrder);
+    const merged = [];
+    for (const tier of TIER_BUDGET_ORDER) {
+        for (const warning of candidates) {
+            if (merged.length >= maxWarnings)
+                break;
+            if (warning.severity === tier)
+                merged.push(warning);
+        }
+    }
+    merged.sort(byDisplayOrder);
     const byFile = new Map();
     for (const warning of merged) {
         const arr = byFile.get(warning.filePath) ?? [];
@@ -131,6 +160,11 @@ export function buildCodeQualityWarningsReport(args) {
         summary: {
             warnings: merged.length,
             files: files.length,
+            byTier: {
+                warning: merged.filter((w) => w.severity === "warning").length,
+                info: merged.filter((w) => w.severity === "info").length,
+                hint: merged.filter((w) => w.severity === "hint").length,
+            },
             topRules,
         },
     };
@@ -205,8 +239,26 @@ export function formatCodeQualityWarningsAdvisory(report) {
         .slice(0, 3)
         .map((entry) => `${entry.rule}×${entry.count}`)
         .join(", ");
+    // #1777: name the tiers, in the same descending-loudness order the on-demand
+    // ast-grep surface uses (`formatDiagnostics`, clients/ast-grep-client.ts).
+    // A tier with no findings is omitted rather than printed as zero.
+    const byTier = report.summary.byTier ?? { warning: 0, info: 0, hint: 0 };
+    // The line is worth its space only when a quiet tier is present; an
+    // all-warning turn already says everything in the count above.
+    const tiers = byTier.hint || byTier.info
+        ? [
+            byTier.warning ? `${byTier.warning} warning` : undefined,
+            byTier.info ? `${byTier.info} info` : undefined,
+            byTier.hint ? `${byTier.hint} hint` : undefined,
+        ]
+            .filter(Boolean)
+            .join(", ")
+        : "";
     return [
         `Code-quality warnings introduced/touched this turn: ${report.summary.warnings} across ${report.summary.files} file(s).`,
+        tiers
+            ? `By tier: ${tiers}. Hint and info are style opinions, not defects.`
+            : undefined,
         topRules ? `Top rules: ${topRules}` : undefined,
         "Details written to .pi-lens/cache/code-quality-warnings.json",
         "No action required unless you are already refactoring these areas.",