@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/lsp/workspace-sweep-hold.js

@@ -0,0 +1,175 @@
+/**
+ * #1618: a full workspace sweep (`LSPService.runWorkspaceDiagnostics`, the
+ * engine behind `lens_diagnostics mode=full`) grants itself a wall-clock
+ * ceiling (`FULL_SCAN_WALL_CLOCK_MS`, see {@link getFullScanWallClockMs})
+ * that can outlive the detached LSP idle-reset timer armed by
+ * `clients/runtime-turn.ts`'s `handleTurnEnd` on a file-less turn. Nothing
+ * previously stopped that timer from firing mid-sweep and destroying the
+ * very service the sweep was actively touching — every file the sweep had
+ * not yet reached then failed with zero trace and got mislabeled as budget
+ * exhaustion.
+ *
+ * This module is the shared hold: `runWorkspaceDiagnostics` acquires it for
+ * its own lifetime (try/finally, so a throw or an aborted sweep still
+ * releases it) and the idle-reset timer consults it before firing. Holds are
+ * tracked as TOKENS (acquire-time-stamped), not a bare counter — two
+ * overlapping `lens_diagnostics mode=full` calls (or a sweep started while
+ * another is still finishing) must each be free to release independently
+ * without the other's hold being dropped early.
+ *
+ * A leaked hold that never re-arms idle reset is the inverse defect (state
+ * that must re-arm cannot hide behind a stuck guard), so this module screens
+ * against it on TWO axes, matching the repo's own session-boundary +
+ * bounded-lifetime conventions:
+ *   1. `clearWorkspaceSweepHoldForSessionStart` — `resetLSPService({reason:
+ *      "session_start"})` clears every held token unconditionally. A session
+ *      boundary means no in-flight sweep from a PRIOR generation is still
+ *      meaningful to wait on.
+ *   2. `reapStaleHolds` (internal, called from every liveness check) —
+ *      force-releases any token older than {@link getWorkspaceSweepMaxHoldAgeMs},
+ *      derived from the sweep's own wall-clock ceiling plus a safety margin.
+ *      A real sweep is either done or self-aborted well within that window
+ *      (`tools/lens-diagnostics.ts` races `FULL_SCAN_WALL_CLOCK_MS`), so a
+ *      token still held past it can only be a bug — never a legitimate long
+ *      sweep — and gets force-released with its own distinct log record.
+ *
+ * `getFullScanWallClockMs` also lives here (rather than duplicated between
+ * `tools/lens-diagnostics.ts` and `clients/runtime-turn.ts`) so the idle-reset
+ * delay on every path (base AND the subagent/budget-shortened paths) can be
+ * DERIVED from the sweep's own ceiling instead of the constants drifting
+ * apart again (#1618 acceptance criterion 6).
+ */
+import { logLatency } from "../latency-logger.js";
+/** Extra headroom beyond the sweep's own wall-clock ceiling before an
+ *  idle-reset delay (or the max-hold-age failsafe) trusts that a real sweep
+ *  must be done. Single source for both derivations below AND for every
+ *  idle-reset path `clients/runtime-turn.ts` derives (base, subagent, and
+ *  budget-shortened) — never a second independently-tunable literal. */
+export const SWEEP_IDLE_SAFETY_MARGIN_MS = 60_000;
+let holds = new Map(); // holdId -> acquiredAt (Date.now())
+let nextHoldId = 1;
+let idleWaiters = [];
+function flushIdleWaitersIfEmpty() {
+    if (holds.size > 0)
+        return;
+    if (idleWaiters.length === 0)
+        return;
+    const waiters = idleWaiters;
+    idleWaiters = [];
+    for (const waiter of waiters) {
+        try {
+            waiter();
+        }
+        catch {
+            // Best-effort — a waiter failure must never propagate into the
+            // releasing/reaping call stack.
+        }
+    }
+}
+/**
+ * A held token past this age can only be a bug (leaked release, a sweep that
+ * hung outside its own abort signal, …) — a legitimate sweep is done or
+ * self-aborted well before it. Derived, not a separate literal, so it can't
+ * drift out of sync with `getFullScanWallClockMs` the way the idle-reset
+ * timer and the sweep's own ceiling once did.
+ */
+export function getWorkspaceSweepMaxHoldAgeMs() {
+    return getFullScanWallClockMs() + SWEEP_IDLE_SAFETY_MARGIN_MS;
+}
+function reapStaleHolds() {
+    if (holds.size === 0)
+        return;
+    const maxAgeMs = getWorkspaceSweepMaxHoldAgeMs();
+    const now = Date.now();
+    for (const [holdId, acquiredAt] of holds) {
+        const ageMs = now - acquiredAt;
+        if (ageMs <= maxAgeMs)
+            continue;
+        holds.delete(holdId);
+        logLatency({
+            type: "phase",
+            phase: "lsp_workspace_sweep_hold_force_released",
+            filePath: "",
+            durationMs: ageMs,
+            metadata: { holdId, maxHoldAgeMs: maxAgeMs },
+        });
+    }
+    flushIdleWaitersIfEmpty();
+}
+/**
+ * Acquire the hold for one `runWorkspaceDiagnostics` call. Returns a release
+ * function; callers MUST call it from a `finally` block so an overlapping or
+ * throwing sweep still releases its hold. Idempotent — calling the returned
+ * function more than once past the first call, or after the hold was already
+ * force-released (session reset / max-age reap), is a no-op.
+ */
+export function acquireWorkspaceSweepHold() {
+    const holdId = nextHoldId++;
+    holds.set(holdId, Date.now());
+    return () => {
+        if (!holds.delete(holdId))
+            return;
+        flushIdleWaitersIfEmpty();
+    };
+}
+/** True while at least one `runWorkspaceDiagnostics` sweep is in flight.
+ *  Reaps stale holds first, so a leaked/hung hold can't permanently read as
+ *  "active" past its own max age. */
+export function isWorkspaceSweepActive() {
+    reapStaleHolds();
+    return holds.size > 0;
+}
+/**
+ * Run `cb` once the hold count next returns to zero. Runs synchronously and
+ * immediately when no sweep is active right now — the common case, and the
+ * one every non-sweep idle-reset arm/fire takes.
+ */
+export function runWhenWorkspaceSweepIdle(cb) {
+    reapStaleHolds();
+    if (holds.size === 0) {
+        cb();
+        return;
+    }
+    idleWaiters.push(cb);
+}
+/**
+ * `resetLSPService({reason: "session_start"})` calls this: a session
+ * boundary means no hold from a PRIOR generation is still meaningful to wait
+ * on, so every held token is cleared unconditionally (state that must
+ * re-arm at session_start cannot hide behind a leaked/stuck guard from the
+ * generation before it). Only logs when there was actually something to
+ * clear — the common case (no sweep in flight at session boundary) stays
+ * silent.
+ */
+export function clearWorkspaceSweepHoldForSessionStart() {
+    if (holds.size === 0)
+        return;
+    logLatency({
+        type: "phase",
+        phase: "lsp_workspace_sweep_hold_session_reset",
+        filePath: "",
+        durationMs: 0,
+        metadata: { clearedHolds: holds.size },
+    });
+    holds.clear();
+    flushIdleWaitersIfEmpty();
+}
+/** Test-only: reset the module-scope hold state between tests. */
+export function _resetWorkspaceSweepHoldForTests() {
+    holds = new Map();
+    idleWaiters = [];
+    nextHoldId = 1;
+}
+/**
+ * Wall-clock ceiling for one `lens_diagnostics mode=full` scan
+ * (`runWorkspaceDiagnostics` plus its concurrent project-runner/analyzer
+ * work). Single source for `tools/lens-diagnostics.ts` (the sweep caller),
+ * `clients/runtime-turn.ts` (every idle-reset path, whose delay must outlive
+ * it), and this module's own max-hold-age failsafe — lazy env read, never
+ * memoized, matching this codebase's house style so a test can flip the
+ * override mid-run.
+ */
+export function getFullScanWallClockMs() {
+    const raw = Number(process.env.PI_LENS_LENS_DIAGNOSTICS_FULL_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : 300_000; // 5 min default
+}

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

@@ -1,7 +1,8 @@
 /** Shared lazy LSP service seam (#1394). */
-let lspPromise;
+import { createLazyImport } from "./lazy-import.js";
+const lazyLsp = createLazyImport(() => import("./lsp/index.js"));
 export function warmLspService() {
-    return (lspPromise ??= import("./lsp/index.js"));
+    return lazyLsp.get();
 }
 export function loadLspService() {
     return warmLspService();

package/node_modules/pi-lens/dist/clients/mcp/session.js

@@ -32,7 +32,12 @@ import { handleTurnEnd } from "../runtime-turn.js";
 import { createMcpHost } from "./host-shim.js";
 let contextPromise;
 let resolvedRuntime;
-/** Lazily build (once) the persistent session context shared across MCP calls. */
+/**
+ * Lazily build (once) the persistent session context shared across MCP
+ * calls. A rejected build (e.g. `loadBootstrapClients` hitting a transient
+ * fs error) must not poison every later MCP call for the rest of the
+ * process — evict the memo on rejection so the next call retries (#1570).
+ */
 export function getMcpSessionContext() {
     contextPromise ??= (async () => {
         const context = {
@@ -43,7 +48,10 @@ export function getMcpSessionContext() {
         };
         resolvedRuntime = context.runtime;
         return context;
-    })();
+    })().catch((err) => {
+        contextPromise = undefined;
+        throw err;
+    });
     return contextPromise;
 }
 /** Synchronous peek at the session runtime, for construction sites that cannot

package/node_modules/pi-lens/dist/clients/module-report.js

@@ -162,6 +162,14 @@ async function extractFile(absPath, languageId, content) {
             let callbacks = [];
             let callbackError;
             try {
+                // SAFETY: `ModuleReportNode` is this module's own structural
+                // subset of a tree-sitter node: `type`, `text`, `children`,
+                // `parent`, `isNamed`, and the two positions. A real node
+                // implements all of it, but the two types are declared in
+                // unrelated packages so TypeScript sees no relation. The cast
+                // asserts only that structural subset; widen
+                // `ModuleReportNode` past what tree-sitter nodes provide and
+                // it stops holding.
                 callbacks = extractCallbacks(tree.rootNode, owners, languageId, warnings);
             }
             catch (error) {

package/node_modules/pi-lens/dist/clients/opengrep-client.js

@@ -42,13 +42,19 @@
  * So `opengrepResultToProjectDiagnostics` deliberately applies NO suppression
  * filtering of its own — doing so would be redundant at best.
  *
- * Refs: #584, #111 (opengrep adoption), #387 (workspace-sweep serialization)
+ * Scope note (#1562 class fix): the CLI scan is handed `--exclude` per shared
+ * scratch/cache tree (`scratch-tree-policy.ts`) so a directory that isn't
+ * gitignored (opengrep's own default exclusion) still doesn't reach the
+ * agent as a finding — same `EXCLUDED_DIRS`-derived list gitleaks/trivy use.
+ *
+ * Refs: #584, #111 (opengrep adoption), #387 (workspace-sweep serialization), #1562
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { mkdtempSync } from "node:fs";
 import { resolveOpengrepConfig } from "./opengrep-config.js";
+import { getScratchTreeDirNames } from "./scratch-tree-policy.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { SecurityScanClient } from "./security-scan-client.js";
 const EMPTY_RESULT = {
@@ -116,6 +122,14 @@ export class OpengrepClient extends SecurityScanClient {
                 "--no-error",
                 "--quiet",
                 "--disable-version-check",
+                // #1562 class fix: opengrep's own `.gitignore` respect covers the
+                // common case (scratch trees are usually gitignored), but not a
+                // scratch/cache tree that ISN'T (e.g. an un-gitignored worktree
+                // cache) — `--exclude` is semgrep-compatible, so a slash-free
+                // pattern matches that directory name anywhere in the tree,
+                // independent of gitignore. Same `EXCLUDED_DIRS`-derived list
+                // gitleaks/trivy use, so the three scanners can't drift apart.
+                ...getScratchTreeDirNames().flatMap((name) => ["--exclude", name]),
                 cwd,
             ], { cwd, timeout: SCAN_TIMEOUT_MS });
             if (result.error) {

package/node_modules/pi-lens/dist/clients/package-manager.js

@@ -16,7 +16,8 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { isCommandAvailableAsync, safeSpawnAsync } from "./safe-spawn.js";
+import { classifyProbeFailure, createAvailabilityLatch, isTransientDecision, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { safeSpawnAsync } from "./safe-spawn.js";
 /**
  * Fallback preference when nothing is declared (or the declared manager is
  * missing). npm first for maximum compatibility; bun last. A project lockfile
@@ -72,18 +73,142 @@ function readPackageManagerField(targetPath) {
 // ============================================================================
 // AVAILABILITY (cached per process; reset in tests)
 // ============================================================================
-const availabilityCache = new Map();
-function isAvailable(pm) {
-    let cached = availabilityCache.get(pm);
-    if (!cached) {
-        cached = isCommandAvailableAsync(pm);
-        availabilityCache.set(pm, cached);
+/**
+ * Budget for the `where`/`which <pm>` probe. Matches the previous
+ * `isCommandAvailableAsync` default so the observable timing is unchanged.
+ */
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * A timed-out probe used to be memoized as a permanent `false` — the process
+ * would silently downgrade a declared pnpm/yarn manager to npm for its whole
+ * life. The blast radius was internal: this resolver only serves installs
+ * into pi-lens's own managed tools directory and `pilens_rebuild` on a
+ * pi-lens source checkout, never a user project's lockfile (#1496). Each
+ * manager now sits behind the shared transient-aware latch (#1467/#1476):
+ * only a genuine absence (`where`/`which` exits non-zero, or ENOENT) latches;
+ * a timeout, abort or host stall expires on a cooldown and is re-probed.
+ */
+const availabilityLatches = new Map();
+const inFlightProbes = new Map();
+function getLatch(pm) {
+    let latch = availabilityLatches.get(pm);
+    if (!latch) {
+        latch = createAvailabilityLatch();
+        availabilityLatches.set(pm, latch);
+    }
+    return latch;
+}
+async function probeAvailability(pm) {
+    const latch = getLatch(pm);
+    const startedAt = Date.now();
+    const finder = onWindows() ? "where" : "which";
+    const sampler = startHostStallSampler();
+    let result;
+    let hostStallMs;
+    try {
+        result = await safeSpawnAsync(finder, [pm], { timeout: PROBE_TIMEOUT_MS });
     }
-    return cached;
+    finally {
+        hostStallMs = sampler.stop();
+    }
+    const elapsedMs = Date.now() - startedAt;
+    if (result.status === 0 && !result.error) {
+        latch.noteAvailable();
+        logAvailabilityDecision({
+            tool: pm,
+            verdict: "available",
+            outcome: "success",
+            cause: "ok",
+            elapsedMs,
+            latched: true,
+            hostStallMs,
+            budgetMs: PROBE_TIMEOUT_MS,
+        });
+        return true;
+    }
+    const { outcome, cause, evidence } = classifyProbeFailure(result, {
+        hostStallMs,
+        // Preserve pre-#1496 meaning for anything the classifier can't place: a
+        // present manager that rejects its probe is durable, same as before.
+        unclassifiedFailureOutcome: "missing",
+    });
+    const retryAfterMs = latch.noteUnavailable(outcome, cause);
+    logAvailabilityDecision({
+        tool: pm,
+        verdict: "unavailable",
+        outcome,
+        cause,
+        elapsedMs,
+        latched: outcome !== "transient",
+        hostStallMs,
+        ...(retryAfterMs > 0 && { retryAfterMs }),
+        budgetMs: PROBE_TIMEOUT_MS,
+        classifiedBy: "probe",
+        evidence,
+    });
+    return false;
+}
+/**
+ * Resolve whether `pm` is available. `onTransient`, when given, fires
+ * whenever the resolved `false` came from a probe that never got a fair
+ * hearing (a stall, an abort, a host-level failure classified `transient` by
+ * `classifyProbeFailure`) rather than a genuine absence — including when that
+ * verdict is served from the latch's own cooldown-bounded memo, not just on a
+ * fresh probe (#1585).
+ *
+ * Before this, the return type was a bare boolean: a caller like
+ * `allAvailableGlobalBinDirs` could not tell "pnpm isn't installed" from
+ * "the `where pnpm` probe stalled", so a transient miss silently dropped
+ * pnpm's global bin dir with no way to flag the result as provisional —
+ * exactly the boolean-collapse `getToolPath`'s `onTransient` plumbing (#1569)
+ * was built to avoid, one layer up.
+ */
+function isAvailable(pm, onTransient) {
+    const latch = getLatch(pm);
+    const reportIfTransient = (result) => {
+        if (!result && isTransientDecision({ outcome: latch.getOutcome() })) {
+            onTransient?.();
+        }
+        return result;
+    };
+    const memo = latch.read();
+    if (memo !== null)
+        return Promise.resolve(reportIfTransient(memo));
+    // A verdict can now expire, so concurrent callers arriving just after a
+    // cooldown must share ONE probe rather than each spawning their own.
+    const inFlight = inFlightProbes.get(pm);
+    if (inFlight)
+        return inFlight.then(reportIfTransient);
+    // #1653 review F1: a probe started before a session reset can settle AFTER
+    // a later session's own probe for the same manager is already in flight.
+    // An unconditional delete-by-key would evict that NEWER entry out from
+    // under it, so a third caller in the gap finds nothing in-flight and
+    // spawns a duplicate. Only remove the entry if it is still THIS call's
+    // promise — the same identity guard `resolveMadge` uses in
+    // dependency-checker.ts for the equivalent race.
+    const probe = probeAvailability(pm).finally(() => {
+        if (inFlightProbes.get(pm) === probe)
+            inFlightProbes.delete(pm);
+    });
+    inFlightProbes.set(pm, probe);
+    return probe.then(reportIfTransient);
 }
-/** Clear the process-wide availability cache. Intended for tests. */
+/**
+ * Clear the process-wide availability cache: pnpm/yarn/bun/npm each sit
+ * behind their own module-local `AvailabilityLatch` in `availabilityLatches`,
+ * so `resetDispatchAvailabilityState`'s generation counter (the mechanism
+ * most dispatch runners inherit) never reaches them — the same shape as
+ * psscriptanalyzer's (#1490) and zizmor's (#1535) module-local latches.
+ * Without this wired into `session_start`, a genuine "pnpm is missing"
+ * verdict from one session stayed latched into the next: install pnpm mid
+ * day, start a fresh session, pi-lens still reports it missing until a
+ * process restart (#1653). Called from `handleSessionStart`'s per-session
+ * reset block beside `resetZizmorTokenAvailability()` /
+ * `resetPsScriptAnalyzerAvailability()`; also used directly by tests.
+ */
 export function _resetPackageManagerCache() {
-    availabilityCache.clear();
+    availabilityLatches.clear();
+    inFlightProbes.clear();
 }
 // ============================================================================
 // RESOLUTION
@@ -134,6 +259,24 @@ export function installArgs(pm, pkg, options = {}) {
     args.push(pkg);
     return args;
 }
+/**
+ * Args to re-resolve an already-declared dependency to the newest version its
+ * recorded range still permits. npm/pnpm/bun spell this `update`; yarn classic
+ * spells it `upgrade`.
+ *
+ * This is the command that repairs a dependency frozen by its own lockfile.
+ * `installArgs` re-runs the install, and a lockfile entry that already
+ * satisfies the range makes that a no-op: pi-lens's managed tools tree stayed
+ * on the version written at first install for the life of the machine even
+ * though the declared caret range permitted 28 newer minors (#1730).
+ */
+export function updateArgs(pm, pkg, options = {}) {
+    const args = [pm === "yarn" ? "upgrade" : "update"];
+    if (options.ignoreScripts)
+        args.push("--ignore-scripts");
+    args.push(pkg);
+    return args;
+}
 /**
  * Args to install a single package **globally** (`-g`). npm/pnpm/bun spell this
  * `install -g` / `add -g`; yarn uses `global add` (yarn classic — Berry removed
@@ -204,12 +347,18 @@ async function globalBinDirsFor(pm) {
  * Global bin directories for every installed manager, deduped. Used to locate a
  * globally-installed tool binary when PATH is stale (e.g. right after an
  * `install -g`) or when the tool was installed via a non-npm manager.
+ *
+ * `onTransient`, when given, fires once per manager whose `isAvailable` probe
+ * was transient (stalled/unspawnable, not a genuine absence) — the boolean
+ * `allAvailableGlobalBinDirs` returns can't itself distinguish "not
+ * installed" from "couldn't tell", so a caller that persists this result
+ * needs the callback to know the answer may be incomplete (#1585).
  */
-export async function allAvailableGlobalBinDirs() {
+export async function allAvailableGlobalBinDirs(onTransient) {
     const dirs = [];
     const seen = new Set();
     for (const pm of PREFERENCE) {
-        if (!(await isAvailable(pm)))
+        if (!(await isAvailable(pm, onTransient)))
             continue;
         for (const dir of await globalBinDirsFor(pm)) {
             const normalized = path.resolve(dir);
@@ -251,8 +400,15 @@ export async function findGlobalBinary(command, windowsExt = ".cmd") {
     }
     return undefined;
 }
-/** Local `node_modules/.bin/<tool>` walking up from `startDir` to the fs root. */
-function findLocalBinUpwards(tool, startDir, windowsExt) {
+/**
+ * Local `node_modules/.bin/<tool>` walking up from `startDir` to the fs root.
+ *
+ * Exported so callers that must NOT pay for global-bin discovery can reuse this
+ * walk instead of copying it. `findNodeToolBinary` below adds `findGlobalBinary`,
+ * which spawns a probe per package manager; a caller resolving a command on
+ * every run (knip, #1721) needs the filesystem half only.
+ */
+export function findLocalBinUpwards(tool, startDir, windowsExt = ".cmd") {
     const names = onWindows() ? [`${tool}${windowsExt}`, tool] : [tool];
     let dir = path.resolve(startDir);
     const root = path.parse(dir).root;

package/node_modules/pi-lens/dist/clients/path-attribution-telemetry.js

@@ -0,0 +1,27 @@
+import { logLatency } from "./latency-logger.js";
+// Verified guesses are expected host behavior, not degradations. Keep their
+// exact session count in memory and publish one bounded row at session end.
+// This tally is intentionally memory-only: a process crash loses its count.
+// The rollup is best-effort session telemetry, not durable accounting.
+let verifiedGuessCount = 0;
+export function recordVerifiedPathAttributionGuess() {
+    verifiedGuessCount += 1;
+}
+export function getVerifiedPathAttributionGuessCount() {
+    return verifiedGuessCount;
+}
+export function emitVerifiedPathAttributionRollup(filePath) {
+    if (verifiedGuessCount === 0)
+        return;
+    logLatency({
+        type: "phase",
+        phase: "path_attribution_verified_rollup",
+        filePath,
+        durationMs: 0,
+        metadata: { count: verifiedGuessCount },
+    });
+    verifiedGuessCount = 0;
+}
+export function resetVerifiedPathAttributionGuessCount() {
+    verifiedGuessCount = 0;
+}