@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

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;
+}

package/node_modules/pi-lens/dist/clients/path-utils.js

@@ -452,3 +452,163 @@ export function direntsHaveMarkerGlobMatch(entries, pattern) {
     return entries.some((entry) => (entry.isFile() || entry.isSymbolicLink()) &&
         nameMatchesMarkerGlob(entry.name, pattern));
 }
+/**
+ * Narrow no-break space, U+202F. macOS writes it before AM/PM in screenshot
+ * file names; users type an ordinary space.
+ */
+const NARROW_NO_BREAK_SPACE = "\u202F";
+/** Right single quotation mark, U+2019. macOS writes it; users type U+0027. */
+const RIGHT_SINGLE_QUOTE = "\u2019";
+/**
+ * The unicode space class pi folds to U+0020, copied character-for-character
+ * from `@earendil-works/pi-coding-agent/dist/utils/paths.js:6`
+ * (`UNICODE_SPACES`, source `src/utils/paths.ts`). Widening or narrowing this
+ * set makes pi-lens resolve a different file than pi does.
+ */
+const HOST_UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+/**
+ * Mirror pi's `normalizeWindowsShellPath`
+ * (`@earendil-works/pi-coding-agent/dist/utils/paths.js:47-56`): convert Git
+ * Bash, MSYS, Cygwin, and WSL drive paths to a form native Windows APIs
+ * accept.
+ */
+function hostNormalizeWindowsShellPath(filePath) {
+    if (!filePath.startsWith("/") ||
+        filePath.startsWith("//") ||
+        filePath.includes("\\")) {
+        return filePath;
+    }
+    const match = filePath.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+    if (!match)
+        return filePath;
+    const suffix = match[2]?.replaceAll("/", "\\");
+    return `${match[1].toUpperCase()}:\\${suffix ?? ""}`;
+}
+/**
+ * Mirror pi's `normalizePath`
+ * (`@earendil-works/pi-coding-agent/dist/utils/paths.js:57-79`, source
+ * `src/utils/paths.ts`), in pi's order, which is load-bearing: the unicode
+ * fold runs BEFORE the `@` strip, and the tilde expansion before the
+ * `file://` conversion.
+ *
+ * The `win32` step is gated on `process.platform`, exactly as pi gates it.
+ * This is a deliberate exception to the usual probe-the-filesystem rule
+ * (AGENTS.md shape 2): pi-lens runs in pi's own process, so mirroring the
+ * host's own platform branch is what keeps the two resolvers in agreement.
+ * Shape-based parsing here would DIVERGE from the host, not protect against
+ * it.
+ */
+export function normalizeHostToolPath(input, options = {}) {
+    let normalized = input;
+    if (options.normalizeUnicodeSpaces) {
+        normalized = normalized.replace(HOST_UNICODE_SPACES, " ");
+    }
+    if (options.stripAtPrefix && normalized.startsWith("@")) {
+        normalized = normalized.slice(1);
+    }
+    if (process.platform === "win32") {
+        normalized = hostNormalizeWindowsShellPath(normalized);
+    }
+    // `homedir()` is resolved inside the branch, as pi does. This runs on every
+    // tool_call and a `~` path is the rare case.
+    if (normalized === "~")
+        return os.homedir();
+    if (normalized.startsWith("~/") ||
+        (process.platform === "win32" && normalized.startsWith("~\\"))) {
+        return path.join(os.homedir(), normalized.slice(2));
+    }
+    if (/^file:\/\//.test(normalized)) {
+        try {
+            return fileURLToPath(normalized);
+        }
+        catch {
+            // pi lets a malformed file: URL throw out of normalizePath, but pi-lens
+            // is advisory instrumentation on the same event: a URL pi rejects must
+            // degrade to "no path" here, never take down the tool_call handler.
+            return normalized;
+        }
+    }
+    return normalized;
+}
+/**
+ * Mirror pi's `resolveToCwd`
+ * (`@earendil-works/pi-coding-agent/dist/core/tools/path-utils.js:42-44`,
+ * source `src/core/tools/path-utils.ts:~44-46`) \u2014 the BASE resolution every
+ * read/edit/write path goes through before the variant ladder below ever
+ * runs.
+ *
+ * Two details are pi's, not ours, and both matter:
+ *   - the input is normalized with `normalizeUnicodeSpaces` + `stripAtPrefix`;
+ *     the BASE DIR is normalized with neither (`resolvePath`,
+ *     `dist/utils/paths.js:80-84`).
+ *   - an already-absolute input is re-resolved on its own, ignoring the cwd.
+ */
+export function resolveHostToolPath(input, baseDir) {
+    const normalized = normalizeHostToolPath(input, {
+        normalizeUnicodeSpaces: true,
+        stripAtPrefix: true,
+    });
+    const normalizedBaseDir = normalizeHostToolPath(baseDir);
+    return path.isAbsolute(normalized)
+        ? path.resolve(normalized)
+        : path.resolve(normalizedBaseDir, normalized);
+}
+/**
+ * Mirror pi's read-path fallback ladder (#1655 item 5).
+ *
+ * pi does NOT open `resolve(cwd, input.path)`. `resolveReadPath`
+ * (`@earendil-works/pi-coding-agent/dist/core/tools/path-utils.js:45-70`,
+ * source `src/core/tools/path-utils.ts:52-83`) resolves, and when that path
+ * does not exist it silently retries four unicode/spacing variants in this
+ * exact order:
+ *
+ *   1. narrow no-break space before `AM.`/`PM.` (`tryMacOSScreenshotPath`)
+ *   2. NFD normalization (`tryNFDVariant`) — macOS stores names decomposed
+ *   3. U+0027 → U+2019 (`tryCurlyQuoteVariant`)
+ *   4. NFD + curly quote combined
+ *
+ * Each candidate is used only when it DIFFERS from the resolved path and the
+ * file exists; otherwise pi falls back to the resolved path. So the file pi
+ * actually read can differ from what a naive `path.resolve` produces, and
+ * pi-lens keyed its read guard, LSP touch, and dispatch off the naive form —
+ * silently doing nothing for exactly those files.
+ *
+ * Order matters: it is pi's, so pi-lens picks the same file pi did when more
+ * than one variant happens to exist.
+ *
+ * @param resolvedPath an already-resolved absolute path (the naive form)
+ * @param fileExists injectable existence probe; defaults to `existsSync`
+ */
+export function resolveHostPathVariants(resolvedPath, fileExists = existsSync) {
+    if (fileExists(resolvedPath)) {
+        return { path: resolvedPath, unresolved: false, triedVariants: [] };
+    }
+    const nfd = resolvedPath.normalize("NFD");
+    const candidates = [
+        {
+            variant: "narrow-nbsp",
+            candidate: resolvedPath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`),
+        },
+        { variant: "nfd", candidate: nfd },
+        {
+            variant: "curly-quote",
+            candidate: resolvedPath.replaceAll("'", RIGHT_SINGLE_QUOTE),
+        },
+        {
+            variant: "nfd-curly-quote",
+            candidate: nfd.replaceAll("'", RIGHT_SINGLE_QUOTE),
+        },
+    ];
+    const triedVariants = [];
+    for (const { variant, candidate } of candidates) {
+        // pi skips a candidate identical to the resolved path, so pi-lens does
+        // too — otherwise a no-op "variant" would be reported as a match.
+        if (candidate === resolvedPath)
+            continue;
+        triedVariants.push(variant);
+        if (fileExists(candidate)) {
+            return { path: candidate, variant, unresolved: false, triedVariants };
+        }
+    }
+    return { path: resolvedPath, unresolved: true, triedVariants };
+}