@herbertgao/pi-extensions 2026.8.4 → 2026.8.5

package/node_modules/pi-lens/dist/clients/atomic-write.js

@@ -1,16 +1,62 @@
 /**
  * Shared atomic tmp+rename file writer (closes #762).
  *
- * The `${target}.tmp-${process.pid}` + `renameSync` shape was independently
- * hand-rolled in five places (`instance-registry.ts`, `session-state-store.ts`,
+ * The `${target}.tmp-…` + `renameSync` shape was independently hand-rolled in
+ * five places (`instance-registry.ts`, `session-state-store.ts`,
  * `recent-touches.ts`, `review-graph/builder.ts`, `diagnostic-dispositions.ts`)
- * as each one picked up the need for a cross-process reader to never observe a
- * partially-written file: `rename()` replaces the destination atomically on
- * both POSIX and Windows (libuv uses `MOVEFILE_REPLACE_EXISTING`), so a
- * concurrent reader always sees either the fully-old or fully-new file, never
- * a torn write. Five independent copies of the same shape invite drift (e.g.
- * forgetting the tmp-file cleanup on the failure path) — this module is the
- * single implementation the rest re-use.
+ * as each one picked up the need for a reader to never observe a
+ * partially-written file. Five independent copies of the same shape invite
+ * drift (e.g. forgetting the tmp-file cleanup on the failure path) — this
+ * module is the single implementation the rest re-use.
+ *
+ * ## What this guarantees (#1205)
+ *
+ * Data is written in full to a staging file that no other writer can name,
+ * then `rename()`d over the target. On POSIX, `rename()` replaces the
+ * destination atomically by construction. On Windows, libuv uses
+ * `MoveFileEx` with `MOVEFILE_REPLACE_EXISTING`, which is atomic in practice
+ * on a same-volume NTFS replace but — unlike POSIX `rename()` — is not a
+ * formally guaranteed atomic primitive (`ReplaceFile` /
+ * `SetFileInformationByHandle` are the stronger APIs). Therefore, modulo that
+ * caveat:
+ *
+ *   - **Crash-safe replacement.** A crash mid-write leaves the target holding
+ *     its previous complete contents plus an orphan staging file; it never
+ *     leaves the target half-written.
+ *   - **Tear-free publication.** Any reader — same process or not — observes
+ *     either the fully-old or the fully-new file at the target path. Because
+ *     the staging name is unique *per call* (pid + thread id + a monotonic
+ *     per-thread counter), this now holds for concurrent writes from the same
+ *     process too, on any thread. Before #1205 the staging name was only
+ *     `.tmp-${pid}`, so two in-flight same-process writes to one target
+ *     shared a staging inode; the first `rename` published it while the
+ *     second writer was still writing into it, publishing a torn hybrid file.
+ *
+ * ## What this explicitly does NOT provide
+ *
+ *   - **No read-modify-write isolation.** Concurrent read → mutate → write
+ *     cycles still lose updates: each writer publishes the state it computed
+ *     from the snapshot it read, and last-rename-wins silently discards the
+ *     other's mutation. Callers needing this must serialize themselves (see
+ *     `lspChildRemovalTail` in `instance-registry.ts`).
+ *   - **No ordering.** Nothing sequences concurrent writers, within or across
+ *     processes. The winner is whichever `rename` lands last, which is not
+ *     necessarily the write that started or finished last.
+ *   - **No mutual exclusion.** This is not a lock. Overlapping writes are
+ *     permitted and expected; only *torn* output is prevented.
+ *   - **No fsync/durability guarantee.** Neither the staging file nor the
+ *     parent directory is fsync'd, so a power loss (as opposed to a process
+ *     crash) may lose the rename.
+ *   - **No self-reaping.** A process killed between the staging write and the
+ *     rename leaves an orphan staging file. The next session_start performs a
+ *     bounded, liveness-checked sweep through the instance-reaper lifecycle
+ *     seam (#1228); this writer never watches or reaps its own files.
+ *   - **Windows-specific loss under `bestEffort: true`.** `MoveFileEx` with
+ *     `MOVEFILE_REPLACE_EXISTING` fails if a reader holds the destination
+ *     open without `FILE_SHARE_DELETE`. On Windows this silently drops the
+ *     write (swallowed like any other `bestEffort: true` failure); the
+ *     identical code path succeeds on POSIX, where `rename()` does not care
+ *     whether a reader has the destination open.
  *
  * Per-write-site error policy varies and is NOT a detail this helper should
  * paper over:
@@ -29,8 +75,62 @@
  *     it swallowed. See the #757 CHANGELOG entry for the full reasoning.
  */
 import * as fs from "node:fs";
+export { STAGE_TMP_PATTERN, stageOwnerPidFromName, stagePathFor, } from "./atomic-write-staging.js";
+import { stagePathFor } from "./atomic-write-staging.js";
+/**
+ * Monotonic counter that makes each staging path unique per CALL, not merely
+ * per process (#1205).
+ *
+ * A counter is used rather than `randomBytes`: it is allocation-free and
+ * synchronous on what are hot per-turn/per-touch write paths, and it is
+ * *exactly* as unique as needed — collisions only matter between two writes
+ * live at the same instant, and a monotonic counter makes those impossible by
+ * construction rather than merely improbable.
+ *
+ * The counter alone is per-THREAD, not per-process: a worker gets its own
+ * module instance and so its own `_stageSeq` starting at 0, while sharing
+ * `process.pid` with the main thread and every sibling worker. Two threads
+ * would therefore each mint `${target}.tmp-<samepid>-0` — the exact collision
+ * the counter exists to prevent. `threadId` (0 on the main thread, distinct
+ * per worker) closes that axis, so the three parts cover the three ways two
+ * writes can be concurrent: `process.pid` across processes, `threadId` across
+ * threads, `_stageSeq` within one thread (#1217).
+ */
+/**
+ * Staging path for one write call: `${targetPath}.tmp-<pid>-<threadId>-<seq>`.
+ *
+ * Exported so that callers which cannot use {@link writeFileAtomic} wholesale
+ * — `gzip-stage-write.ts` needs its own streaming pipeline — still source the
+ * *name* here rather than re-deriving the scheme, and so that sweepers of
+ * orphaned staging files stay in lockstep with it (see
+ * {@link STAGE_TMP_PATTERN}).
+ */
+/**
+ * Matches the trailing staging-file marker produced by {@link stagePathFor},
+ * for the session-start sweeper that garbage-collects staging files orphaned
+ * by a crashed process (#1228). The writer itself does not reap or watch files.
+ *
+ * Only the current four-component shape is matched:
+ * `.tmp-<pid>-<threadId>-<seq>` (#1217). Older one- and two-number suffixes
+ * are deliberately left alone: their shape is indistinguishable from
+ * legitimate user filenames, so deletion safety outweighs reclaiming the
+ * handful of pre-#1208 leftovers.
+ *
+ * CAUTION for any sweeper adopting this pattern: it matches staging files by
+ * shape, not by writer identity, so it also matches this process's own
+ * still-being-written staging files. A safe sweeper must separately protect
+ * `process.pid` and use the shared conservative liveness check for foreign
+ * pids. The review-graph builder's narrower stage sweep intentionally remains
+ * separate because it owns a different `.stage-<pid>-<generation>` namespace.
+ *
+ * Anchoring is correct for both consumer styles in this repo today
+ * (matching against a full path or a bare basename), but this is confined to
+ * pi-lens's own cache directories — a consumer sweeping a directory it does
+ * not fully control should not assume every match is one of this module's
+ * staging files.
+ */
 /**
- * Synchronous atomic write of text or binary data to `${targetPath}.tmp-${pid}`,
+ * Synchronous atomic write of text or binary data to a per-call staging file,
  * then `fs.renameSync` over `targetPath`. On any failure (from either step),
  * attempts a best-effort `fs.rmSync(tmp, { force: true })` cleanup, then
  * either swallows (default) or rethrows per `options.bestEffort`.
@@ -41,7 +141,7 @@ import * as fs from "node:fs";
  */
 export function writeFileAtomic(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
-    const tmpPath = `${targetPath}.tmp-${process.pid}`;
+    const tmpPath = stagePathFor(targetPath);
     try {
         fs.writeFileSync(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
         fs.renameSync(tmpPath, targetPath);
@@ -60,12 +160,12 @@ export function writeFileAtomic(targetPath, data, options) {
 /**
  * Async counterpart of {@link writeFileAtomic}, built on `fs.promises` instead
  * of the sync `fs` API — for call sites that must not block the event loop
- * (e.g. writes on a hot per-turn/per-touch path). Same tmp-naming, cleanup,
- * and `bestEffort` semantics.
+ * (e.g. writes on a hot per-turn/per-touch path). Same per-call tmp-naming,
+ * cleanup, and `bestEffort` semantics.
  */
 export async function writeFileAtomicAsync(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
-    const tmpPath = `${targetPath}.tmp-${process.pid}`;
+    const tmpPath = stagePathFor(targetPath);
     try {
         await fs.promises.writeFile(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
         await fs.promises.rename(tmpPath, targetPath);

package/node_modules/pi-lens/dist/clients/bash-file-access.js

@@ -15,10 +15,8 @@
  */
 import * as nodeFs from "node:fs";
 import * as path from "node:path";
+import { isReadableSourceFile } from "./file-kinds.js";
 import { countFileLines } from "./read-guard-tool-lines.js";
-// Source-ish extensions worth registering. Anchored end-check → linear (no
-// catastrophic backtracking).
-const READABLE_EXT_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|py|sh|rs|go|cs|java|kt|rb|php|c|cpp|cc|h|hpp|json|jsonc|yaml|yml|toml|md|txt|env|cfg|conf|ini|html|css|scss|less|xml|sql|vue|svelte)$/i;
 function stripQuotes(token) {
     if (token.length >= 2) {
         const first = token[0];
@@ -32,14 +30,123 @@ function stripQuotes(token) {
 function stripAnsi(value) {
     return value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
 }
-function tokenizeSegment(segment) {
-    const matches = segment.match(/'[^']*'|"(?:[^"\\]|\\.)*"|\S+/g);
-    return matches ?? [];
+export function tokenizeShellCommand(command) {
+    const segments = [];
+    let tokens = [];
+    let word = "";
+    let quote;
+    let escaped = false;
+    let unsupported = false;
+    let atTokenStart = true;
+    const flushWord = () => {
+        if (word)
+            tokens.push(word);
+        word = "";
+        atTokenStart = true;
+    };
+    const flushSegment = () => {
+        flushWord();
+        if (tokens.length > 0 || unsupported)
+            segments.push({ tokens, unsupported });
+        tokens = [];
+        unsupported = false;
+        atTokenStart = true;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const next = command[i + 1];
+        if (quote === "single") {
+            if (ch === "'")
+                quote = undefined;
+            else
+                word += ch;
+            continue;
+        }
+        if (quote === "double") {
+            if (escaped) {
+                word += ch;
+                escaped = false;
+            }
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                quote = undefined;
+            else
+                word += ch;
+            continue;
+        }
+        if (escaped) {
+            // A backslash-newline is a shell line continuation, not part of the
+            // command argument. Keeping the newline here makes a continued git command
+            // visible to command guards.
+            if (ch !== "\n")
+                word += ch;
+            escaped = false;
+            atTokenStart = false;
+            continue;
+        }
+        if (ch === "\\") {
+            // Bash uses backslash as a general escape, but command inputs on
+            // Windows routinely contain native paths (C:\\src\\file.ts). Preserve
+            // backslashes before ordinary path characters while still honoring
+            // shell escapes and line continuations.
+            if (next === "\n" || /[\s\\'\";$|&<>]/.test(next ?? "")) {
+                escaped = true;
+            }
+            else {
+                word += ch;
+                atTokenStart = false;
+            }
+            atTokenStart = false;
+            continue;
+        }
+        if (ch === "'") {
+            quote = "single";
+            atTokenStart = false;
+            continue;
+        }
+        if (ch === '"') {
+            quote = "double";
+            atTokenStart = false;
+            continue;
+        }
+        if (ch === "#" && atTokenStart) {
+            while (i + 1 < command.length && command[i + 1] !== "\n")
+                i++;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            flushWord();
+            continue;
+        }
+        if (ch === ";" || ch === "\n" || ch === "|" || ch === "&") {
+            flushWord();
+            if (ch === "|" && next === "|")
+                i++;
+            else if (ch === "&" && next === "&")
+                i++;
+            else if (ch === "|" || ch === "&")
+                unsupported = true;
+            flushSegment();
+            continue;
+        }
+        if (ch === "<" || ch === ">") {
+            flushWord();
+            unsupported = true;
+            continue;
+        }
+        word += ch;
+        atTokenStart = false;
+    }
+    if (quote || escaped)
+        unsupported = true;
+    flushSegment();
+    return segments;
 }
 /** Resolve a token to an absolute path if it looks like a source file. */
 function resolveCandidate(token, cwd) {
     const cleaned = stripQuotes(token);
-    if (!cleaned || cleaned.startsWith("-") || !READABLE_EXT_RE.test(cleaned)) {
+    if (!cleaned || cleaned.startsWith("-") || !isReadableSourceFile(cleaned)) {
         return null;
     }
     return path.isAbsolute(cleaned) ? cleaned : path.resolve(cwd, cleaned);
@@ -52,8 +159,67 @@ function parseCountFlag(token) {
     const n = Number.parseInt(digits, 10);
     return Number.isFinite(n) && n > 0 ? n : undefined;
 }
-function splitSegments(command) {
-    return command.split(/&&|\|\||[;|\n]/);
+function commandSegments(command) {
+    return tokenizeShellCommand(command).map((segment) => segment.tokens);
+}
+/** Find redirect targets without treating quoted `>` characters as syntax. */
+function extractRedirectTargets(command) {
+    const targets = [];
+    let quote;
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (quote === "single") {
+            if (ch === "'")
+                quote = undefined;
+            continue;
+        }
+        if (quote === "double") {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                quote = undefined;
+            continue;
+        }
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (ch === "'") {
+            quote = "single";
+            continue;
+        }
+        if (ch === '"') {
+            quote = "double";
+            continue;
+        }
+        if (ch !== ">")
+            continue;
+        while (i + 1 < command.length && /\s/.test(command[i + 1]))
+            i += 1;
+        if (command[i + 1] === ">")
+            i += 1;
+        while (i + 1 < command.length && /\s/.test(command[i + 1]))
+            i += 1;
+        let target = "";
+        for (i += 1; i < command.length; i += 1) {
+            const next = command[i];
+            if (/\s/.test(next) || next === ";" || next === "|" || next === "&") {
+                i -= 1;
+                break;
+            }
+            target += next;
+        }
+        if (target)
+            targets.push(target);
+    }
+    return targets;
 }
 /**
  * Extract the line ranges a bash command explicitly showed the agent.
@@ -93,11 +259,9 @@ export function extractReadPathsFromCommand(command, cwd) {
         seen.add(key);
         spans.push({ filePath: file.abs, offset, limit });
     };
-    for (const rawSegment of splitSegments(command)) {
-        const segment = rawSegment.trim();
-        if (!segment)
+    for (const tokens of commandSegments(command)) {
+        if (tokens.length === 0)
             continue;
-        const tokens = segment.split(/\s+/);
         const verb = path.basename(tokens[0] ?? "");
         const args = tokens.slice(1);
         if (["cat", "bat", "less", "more", "nl"].includes(verb)) {
@@ -247,8 +411,7 @@ function parseGrepLineWithoutFile(line, file) {
 function collectGrepCommandFiles(command, cwd) {
     const files = new Set();
     let hasLineNumberGrep = false;
-    for (const rawSegment of splitSegments(command)) {
-        const tokens = tokenizeSegment(rawSegment.trim());
+    for (const tokens of commandSegments(command)) {
         const verb = path.basename(stripQuotes(tokens[0] ?? ""));
         if (verb !== "grep" && verb !== "egrep" && verb !== "fgrep")
             continue;
@@ -311,15 +474,22 @@ export function extractWrittenPathsFromCommand(command, cwd) {
         if (abs)
             out.add(abs);
     };
-    for (const rawSegment of splitSegments(command)) {
-        const segment = rawSegment.trim();
-        if (!segment)
+    for (const tokens of commandSegments(command)) {
+        if (tokens.length === 0)
+            continue;
+        // Redirect targets are collected by a quote-aware scanner. The shared
+        // tokenizer supplies the normalized command arguments; it deliberately
+        // does not expose shell redirection operators as arguments.
+        for (const target of extractRedirectTargets(command))
+            add(target);
+        // A command may contain multiple segments; only the first pass should
+        // attach redirects, otherwise targets would be duplicated harmlessly but
+        // needlessly rescanned.
+        break;
+    }
+    for (const tokens of commandSegments(command)) {
+        if (tokens.length === 0)
             continue;
-        // Redirect targets: the token after `>` / `>>` (optionally prefixed by a
-        // file descriptor like `2>` or `&>`, with or without a space).
-        for (const m of segment.matchAll(/>>?\s*([^\s>|&]+)/g))
-            add(m[1]);
-        const tokens = segment.split(/\s+/);
         const verb = path.basename(tokens[0] ?? "");
         const args = tokens.slice(1);
         if (verb === "tee" || verb === "touch") {

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

@@ -7,12 +7,15 @@
  * Requires: npm install @biomejs/biome (or npx @biomejs/biome)
  * Docs: https://biomejs.dev/
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isFileKind } from "./file-kinds.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { biomeConfigArgs } from "./tool-policy.js";
+import { resolveManagedToolClient } from "./dispatch/runners/utils/runner-helpers.js";
 // --- Client ---
 export class BiomeClient {
     biomeAvailable = null;
@@ -29,7 +32,7 @@ export class BiomeClient {
     log;
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[biome] ${msg}`)
+            ? createSubsystemLogger("biome")
             : () => { };
     }
     /**
@@ -87,7 +90,7 @@ export class BiomeClient {
     }
     async spawnBiomeAsync(args, timeout = 15000, cwd) {
         const { cmd, args: prefix } = await this.getBiomeBinary(cwd);
-        return safeSpawnAsync(cmd, [...prefix, ...args], { timeout });
+        return safeSpawnAsync(cmd, [...prefix, ...args], { timeout, cwd });
     }
     /**
      * Ensure Biome is available, auto-installing if necessary.
@@ -112,27 +115,22 @@ export class BiomeClient {
         }
     }
     async doEnsureAvailable() {
-        // Check if already available
-        const result = await this.spawnBiomeAsync(["--version"], 10000);
-        if (!result.error && result.status === 0) {
-            this.biomeAvailable = true;
-            return true;
-        }
-        // Auto-install via pi-lens installer
-        this.log("Biome not found, attempting auto-install...");
-        const { ensureTool } = await import("./installer/index.js");
-        const installedPath = await ensureTool("biome");
-        if (installedPath) {
-            this.log(`Biome auto-installed: ${installedPath}`);
-            // Set the installed path as the global fallback so every cwd
-            // reaches it after its own per-package lookup misses.
-            this.autoInstalledBinaryPath = installedPath;
-            this.biomeAvailable = true;
-            return true;
-        }
-        this.log("Biome auto-install failed");
-        this.biomeAvailable = false;
-        return false;
+        const outcome = await resolveManagedToolClient({
+            toolId: "biome",
+            cwd: process.cwd(),
+            probe: async () => {
+                const result = await this.spawnBiomeAsync(["--version"], 10000);
+                return !result.error && result.status === 0
+                    ? { outcome: "success", value: true }
+                    : { outcome: "missing" };
+            },
+            acceptInstalled: (installedPath) => {
+                this.autoInstalledBinaryPath = installedPath;
+                return true;
+            },
+        });
+        this.biomeAvailable = outcome.outcome === "success";
+        return this.biomeAvailable;
     }
     /**
      * Check if a file is supported by Biome
@@ -142,8 +140,10 @@ export class BiomeClient {
     }
     /**
      * Async auto-fix variant for pipeline use (non-blocking spawn).
+     * `cwd` is the dispatch language root (used for config discovery); when
+     * omitted it defaults to the file's directory.
      */
-    async fixFileAsync(filePath) {
+    async fixFileAsync(filePath, cwd) {
         if (!(await this.ensureAvailable())) {
             return {
                 success: false,
@@ -163,7 +163,11 @@ export class BiomeClient {
         }
         try {
             const before = await fs.promises.readFile(absolutePath, "utf-8");
-            const result = await this.spawnBiomeAsync(["lint", "--write", absolutePath], 15000, path.dirname(absolutePath));
+            const configCwd = cwd ?? path.dirname(absolutePath);
+            // Shared config-args seam (#1247): the lint runner consumes the same
+            // builder, so `lint --write` can never drift to biome's default
+            // config when a user config or the package fallback exists.
+            const result = await this.spawnBiomeAsync(["lint", "--write", ...biomeConfigArgs(configCwd), absolutePath], 15000, configCwd);
             if (result.error) {
                 return {
                     success: false,

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

@@ -1,3 +1,4 @@
+import { logExtension } from "./extension-log.js";
 let bootstrapPromise = null;
 /**
  * A stand-in for an analysis client whose module failed to load (an unresolved
@@ -28,11 +29,19 @@ export function degradedClient() {
  */
 async function logBootstrapFailures(failures) {
     for (const { name, err } of failures) {
-        console.error(`[pi-lens] analyzer "${name}" disabled (degraded mode): ${err?.message ?? String(err)}`);
+        logExtension({
+            subsystem: "bootstrap",
+            message: `analyzer "${name}" disabled (degraded mode): ${err?.message ?? String(err)}`,
+            metadata: { analyzer: name },
+        });
     }
     try {
         const { collectInstallDiagnostics, formatInstallDiagnostics } = await import("./install-diagnostics.js");
-        console.error(formatInstallDiagnostics(collectInstallDiagnostics(), failures[0]?.err));
+        logExtension({
+            subsystem: "bootstrap",
+            message: formatInstallDiagnostics(collectInstallDiagnostics(), failures[0]?.err),
+            metadata: { kind: "install_diagnostics" },
+        });
     }
     catch {
         // the per-analyzer lines above already named the failures

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

@@ -0,0 +1,34 @@
+/** Small insertion-ordered LRU used for process-lifetime memo tables. */
+export class BoundedLruCache {
+    maxEntries;
+    entries = new Map();
+    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;
+    }
+    has(key) { return this.entries.has(key); }
+    set(key, value) {
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+    delete(key) { return this.entries.delete(key); }
+    clear() { this.entries.clear(); }
+    get size() { return this.entries.size; }
+    keys() { return this.entries.keys(); }
+    values() { return this.entries.values(); }
+    entriesArray() { return [...this.entries.entries()]; }
+    [Symbol.iterator]() { return this.entries[Symbol.iterator](); }
+}