@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-lens/dist/clients/advisory-provenance.js

@@ -223,7 +223,7 @@ export function validateAdvisoryProvenance(record, cwd, runtime) {
 //     of which any #1461 slice writes yet, so nothing here currently touches
 //     it.
 /** Stat budget: one per unique cited path, sharing the envelope's own cap. */
-export const MAX_FINDING_PATH_STATS = MAX_ADVISORY_AFFECTED_FILES;
+const MAX_FINDING_PATH_STATS = MAX_ADVISORY_AFFECTED_FILES;
 /** How many dead paths a single drop record names before it stops. */
 const MAX_LOGGED_DEAD_PATHS = 3;
 /**

package/node_modules/pi-lens/dist/clients/agent-behavior-client.js

@@ -8,9 +8,18 @@
  *
  * No external dependencies — purely tracks tool call history.
  */
+import { isMutatingToolName } from "./mutating-tool.js";
 import { normalizeMapKey } from "./path-utils.js";
 // --- Constants ---
-const WRITE_OPS = new Set(["edit", "write", "multiedit"]);
+// #2423: mutating-tool membership comes from the seam
+// (`clients/mutating-tool.ts`), the single source of truth for the built-in
+// table. The hand-maintained set this replaced also carried a dead
+// `"multiedit"` entry that no host emits.
+//
+// Known gap, stated rather than hidden: this client is handed a tool NAME and a
+// path, never the event, so it cannot see a third-party mutating tool the way
+// the shape adapters can. Blind-write and thrash detection covers pi's
+// built-ins only.
 const READ_OPS = new Set(["read", "bash", "grep", "glob", "find", "rg"]);
 const BLIND_WRITE_WINDOW = 5; // Check last N tool calls for a read
 const THRASH_THRESHOLD = 3; // Flag after N consecutive identical tool+file pairs
@@ -63,19 +72,19 @@ export class AgentBehaviorClient {
             });
         }
         // Check for blind writes
-        if (WRITE_OPS.has(toolName)) {
+        if (isMutatingToolName(toolName)) {
             const recentWindow = this.toolHistory.slice(-BLIND_WRITE_WINDOW);
             // A read in the window proves file knowledge; so does a same-session
             // write/edit of THIS path — the agent authored the content, so the
             // write-then-edit loop on a self-authored file is not a blind write.
             const hasRecentRead = recentWindow.some((r) => READ_OPS.has(r.toolName) ||
-                (WRITE_OPS.has(r.toolName) &&
+                (isMutatingToolName(r.toolName) &&
                     r.filePath !== undefined &&
                     normalizedPath !== null &&
                     normalizeMapKey(r.filePath) === normalizedPath));
             if (!hasRecentRead && recentWindow.length > 0) {
                 // Count how many writes in the window without reads
-                const writesWithoutRead = recentWindow.filter((r) => WRITE_OPS.has(r.toolName)).length;
+                const writesWithoutRead = recentWindow.filter((r) => isMutatingToolName(r.toolName)).length;
                 if (writesWithoutRead >= 2) {
                     warnings.push({
                         type: "blind-write",

package/node_modules/pi-lens/dist/clients/ast-grep-client.js

@@ -11,10 +11,79 @@ import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { AstGrepRuleManager } from "./ast-grep-rule-manager.js";
+import { AstGrepRuleManager, checkAstGrepRulesHealth, } from "./ast-grep-rule-manager.js";
+import { reportBundledResourceDirHealth } from "./bundled-resource-health.js";
+import { getDegradationLedgerGeneration } from "./degradation-ledger.js";
+import { logLatency } from "./latency-logger.js";
+import { getMutationBridge } from "./mutation-bridge.js";
 import { resolvePackagePath } from "./package-root.js";
 import { truncatedByOutputCap } from "./spawn-output-cap.js";
 import { SgRunner, } from "./sg-runner.js";
+/**
+ * #2636: `AstGrepClient`'s constructor falls back to the bundled `rules/`
+ * (`resolvePackagePath(import.meta.url, "rules")`) with no existence check
+ * when the project has none of its own — same managed-cache-relocation gap
+ * #2626 fixed for `skills/`. Purely observational: logs a `phase` record
+ * naming the resolved path + rule-description count on EVERY call that uses
+ * the bundled fallback (healthy or not, so an empty ledger is distinguishable
+ * from this never having run at all — #2626 review F5), and records a
+ * bounded `ast-grep-rules-dir-missing` degradation only when the bundled dir
+ * itself turns out absent, unreadable, or holds no `.yml` rule description.
+ * Called only when using the bundled fallback — never when the project
+ * provides its own `rules/` (a broken PROJECT override is a user config
+ * concern, not this bug's shape) — from `ensureRulesHealthReported` below,
+ * both at construction and again on the ledger's next generation (#2636
+ * review F3).
+ */
+function reportAstGrepRulesHealth(bundledRuleDir) {
+    const health = checkAstGrepRulesHealth(bundledRuleDir);
+    logLatency({
+        type: "phase",
+        phase: "ast_grep_rules_resolved",
+        filePath: bundledRuleDir,
+        durationMs: 0,
+        metadata: {
+            status: health.status,
+            entryCount: health.status === "healthy" ? health.entryCount : 0,
+        },
+    });
+    reportBundledResourceDirHealth("ast-grep-rules-dir-missing", bundledRuleDir, health, "ast-grep rule descriptions");
+}
+/**
+ * Record an applied `ast_grep_replace` rewrite through the mutation bridge
+ * (#2423, acceptance criterion 3).
+ *
+ * ast-grep reports 0-based line numbers; the guard and the change log are
+ * 1-based, so every range is shifted by one. One record per FILE carries every
+ * range that file's matches covered, because the bridge's contract is
+ * per-file — the same shape a multi-hunk edit produces.
+ *
+ * Exported for tests: they drive it against a registered bridge instead of
+ * spawning ast-grep.
+ */
+function recordAstGrepApply(matches) {
+    const bridge = getMutationBridge();
+    if (!bridge || matches.length === 0)
+        return;
+    const rangesByFile = new Map();
+    for (const match of matches) {
+        const start = (match.range?.start?.line ?? 0) + 1;
+        const end = Math.max(start, (match.range?.end?.line ?? 0) + 1);
+        const existing = rangesByFile.get(match.file);
+        if (existing)
+            existing.push([start, end]);
+        else
+            rangesByFile.set(match.file, [[start, end]]);
+    }
+    for (const [filePath, editRanges] of rangesByFile) {
+        bridge.recordMutation({
+            filePath,
+            kind: "edit",
+            editRanges,
+            consumer: "ast_grep_replace",
+        });
+    }
+}
 // --- Client ---
 function extractDebugAst(raw) {
     const lines = raw.split(/\r?\n/);
@@ -107,21 +176,65 @@ export class AstGrepClient {
     log;
     ruleManager;
     runner;
+    // #2636 review F3/F7:
+    usingBundledRuleDirFallback;
+    rulesHealthReportedGeneration;
     constructor(ruleDir, verbose = false) {
         const projectRuleDir = path.join(process.cwd(), "rules");
+        // F7: ONE existsSync call, reused for both the fallback decision and the
+        // ruleDir choice — two separate calls let the directory appear (or a
+        // concurrent watcher/installer create it) between them, making
+        // `usingBundledRuleDirFallback` true while `this.ruleDir` ends up being
+        // the now-existing PROJECT dir: the health check would then classify a
+        // project override's own directory against `reportAstGrepRulesHealth`'s
+        // bundled-fallback doc contract.
+        const hasProjectRuleDir = fs.existsSync(projectRuleDir);
+        this.usingBundledRuleDirFallback = !ruleDir && !hasProjectRuleDir;
         this.ruleDir =
             ruleDir ||
-                (fs.existsSync(projectRuleDir)
+                (hasProjectRuleDir
                     ? projectRuleDir
                     : resolvePackagePath(import.meta.url, "rules"));
         this.log = verbose ? createSubsystemLogger("ast-grep") : () => { };
+        this.ensureRulesHealthReported();
         this.ruleManager = new AstGrepRuleManager(this.ruleDir, this.log);
         this.runner = new SgRunner(verbose);
     }
+    /**
+     * #2636 review F3: `AstGrepClient` is a per-PROCESS singleton
+     * (`index.ts`/`mcp/server.ts`/`clients/mcp/session.ts` each construct it
+     * exactly once), but `resetDegradationLedger()` wipes the ledger's
+     * once-per-subject latch on EVERY `session_start`
+     * (`runtime-session.ts`'s `handleSessionStart`). A report that only ever
+     * fires at construction is therefore invisible after the first session
+     * boundary — `pilens_health` shows nothing for a bug that is still there
+     * (shape 17's inverse: `resolveSkillPaths`/`ruleFilesForLanguage` avoid
+     * this because pi calls them fresh per request, but `AstGrepClient` has
+     * no such per-request re-entry).
+     *
+     * Re-checked against the ledger's own generation counter at the START of
+     * every real scan entry point (`ensureAvailable`, called by every
+     * `tools/ast-grep-*`/`ast-dump` handler before doing any work) — the same
+     * pattern `clients/tree-sitter-client.ts`'s `refreshGrammarSessionLatches`
+     * uses for its own per-instance session latches, adapted here: the
+     * degradation ledger already re-arms its OWN once-per-subject dedup on
+     * reset, so this method only has to decide WHETHER to call
+     * `reportAstGrepRulesHealth` again, never re-implement the dedup itself.
+     */
+    ensureRulesHealthReported() {
+        const generation = getDegradationLedgerGeneration();
+        if (this.rulesHealthReportedGeneration === generation)
+            return;
+        this.rulesHealthReportedGeneration = generation;
+        if (this.usingBundledRuleDirFallback) {
+            reportAstGrepRulesHealth(this.ruleDir);
+        }
+    }
     /**
      * Check if ast-grep CLI is available, auto-install if not
      */
     ensureAvailable() {
+        this.ensureRulesHealthReported();
         return this.runner.ensureAvailable();
     }
     /**
@@ -468,6 +581,13 @@ export class AstGrepClient {
                 error: applyResult.error,
             };
         }
+        // #2423: `--update-all` just rewrote these files, and no `tool_result`
+        // describes it — pi-lens's own tool was as invisible to the mutation
+        // bookkeeping as any third-party one. Record each rewritten file through
+        // the same seam an extension would use. Fire-and-forget: the bridge never
+        // throws, and a missing bridge (pi-lens not activated, guard disabled) is
+        // a silent no-op.
+        recordAstGrepApply(preCheck.matches);
         return {
             matches: preCheck.matches,
             totalMatches: preCheck.totalMatches,
@@ -514,7 +634,7 @@ message: found
             grouped.set(signature, group);
         }
         return Array.from(grouped.entries())
-            .filter(([_, functions]) => functions.length > 1)
+            .filter(([, functions]) => functions.length > 1)
             .map(([pattern, functions]) => ({ pattern, functions }));
     }
     /**

package/node_modules/pi-lens/dist/clients/ast-grep-rule-manager.js

@@ -1,5 +1,64 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+/**
+ * The candidate sub-paths under `ruleDir` that hold ast-grep rule
+ * descriptions — SINGLE source of truth shared by `loadRuleDescriptions`
+ * (the real read) and `checkAstGrepRulesHealth` (the #2636 observational
+ * probe), so the two can never drift apart on "where do rules live".
+ */
+export function candidateAstGrepRulesPaths(ruleDir) {
+    return [
+        path.join(ruleDir, "ast-grep-rules", "rules"),
+        path.join(ruleDir, "rules"),
+        ruleDir,
+    ];
+}
+/**
+ * Classify whether `ruleDir` (the resolved ast-grep rules root, `rules/`
+ * inside the bundled package or the project override) yields any loadable
+ * `.yml` rule description — mirroring `loadRuleDescriptions`'s OWN
+ * resolution EXACTLY (first existing candidate wins, then its `.yml`
+ * files), so this never reports a status `loadRuleDescriptions` itself
+ * would disagree with. Purely observational: never throws, and does not
+ * gate what `ruleDir` `AstGrepClient` uses (#2636, following #2626 review
+ * F1 — the acceptance criteria ask for a RECORD, never a changed resolution).
+ */
+export function checkAstGrepRulesHealth(ruleDir) {
+    const possiblePaths = candidateAstGrepRulesPaths(ruleDir);
+    let rulesPath;
+    for (const candidate of possiblePaths) {
+        if (fs.existsSync(candidate)) {
+            rulesPath = candidate;
+            break;
+        }
+    }
+    if (!rulesPath) {
+        // None of the three candidates exist — distinguish `ruleDir` itself
+        // being unreadable (EACCES and friends) from it simply being absent
+        // (ENOENT), matching #2626 review F4's ENOENT/EACCES split.
+        try {
+            fs.readdirSync(ruleDir);
+        }
+        catch (error) {
+            const fsErrorCode = error?.code;
+            if (fsErrorCode && fsErrorCode !== "ENOENT") {
+                return { status: "unreadable", fsErrorCode };
+            }
+        }
+        return { status: "absent" };
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(rulesPath).filter((f) => f.endsWith(".yml"));
+    }
+    catch (error) {
+        const fsErrorCode = error?.code ?? "UNKNOWN";
+        return { status: "unreadable", fsErrorCode };
+    }
+    return entries.length > 0
+        ? { status: "healthy", entryCount: entries.length }
+        : { status: "empty" };
+}
 export class AstGrepRuleManager {
     ruleDir;
     log;
@@ -12,11 +71,7 @@ export class AstGrepRuleManager {
         if (this.ruleDescriptions !== null)
             return this.ruleDescriptions;
         const descriptions = new Map();
-        const possiblePaths = [
-            path.join(this.ruleDir, "ast-grep-rules", "rules"),
-            path.join(this.ruleDir, "rules"),
-            this.ruleDir,
-        ];
+        const possiblePaths = candidateAstGrepRulesPaths(this.ruleDir);
         const rulesPath = possiblePaths.find((p) => fs.existsSync(p));
         if (!rulesPath) {
             this.log(`Rule descriptions: no rules directory found in ${possiblePaths.join(", ")}`);

package/node_modules/pi-lens/dist/clients/ast-grep-tool-logger.js

@@ -11,9 +11,9 @@
  */
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
-const AG_LOG_DIR = getGlobalPiLensDir();
+const AG_LOG_DIR = getGlobalPiLensLogDir();
 const AG_LOG_FILE = path.join(AG_LOG_DIR, "ast-grep-tools.log");
 const AG_LOG_BACKUP_FILE = path.join(AG_LOG_DIR, "ast-grep-tools.log.1");
 const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_AST_GREP_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);
@@ -115,11 +115,4 @@ export function logAstGrepToolEvent(event) {
     };
     writer.log({ ts: new Date().toISOString(), ...payload });
 }
-export function getAstGrepToolLogPath() {
-    return AG_LOG_FILE;
-}
-/** Resolve once all enqueued ast-grep-tool writes are on disk. */
-export function flushAstGrepToolLog() {
-    return writer.flush();
-}
 export { countLines as _countLinesForTest };

package/node_modules/pi-lens/dist/clients/ast-grep-types.js

@@ -6,3 +6,5 @@
  * - ast-grep-rule-manager.ts
  */
 export {};
+// =============================================================================
+// JSON FORMAT (ast-grep CLI output)

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

@@ -18,6 +18,7 @@ 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";
+import { stripAnsi } from "./sanitize.js";
 function stripQuotes(token) {
     if (token.length >= 2) {
         const first = token[0];
@@ -28,11 +29,121 @@ function stripQuotes(token) {
     }
     return token;
 }
-function stripAnsi(value) {
-    return value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
+function parseHeredocDelimiter(command, start) {
+    let i = start;
+    const stripTabs = command[i] === "-";
+    if (stripTabs)
+        i += 1;
+    while (/\s/.test(command[i] ?? ""))
+        i += 1;
+    let delimiter = "";
+    let quoted = false;
+    while (i < command.length && !/[\s;&|<>]/.test(command[i] ?? "")) {
+        const ch = command[i];
+        if (ch === "'" || ch === '"') {
+            quoted = true;
+            const quote = ch;
+            i += 1;
+            while (i < command.length && command[i] !== quote) {
+                delimiter += command[i++];
+            }
+            if (command[i] !== quote)
+                return undefined;
+            i += 1;
+            continue;
+        }
+        if (ch === "\\") {
+            quoted = true;
+            i += 1;
+            if (i >= command.length)
+                return undefined;
+            delimiter += command[i++];
+            continue;
+        }
+        delimiter += ch;
+        i += 1;
+    }
+    if (!delimiter)
+        return undefined;
+    return { heredoc: { delimiter, stripTabs, quoted }, end: i - 1 };
+}
+function heredocSubstitutionBodies(body) {
+    const substitutions = [];
+    for (let i = 0; i < body.length; i += 1) {
+        if (body.startsWith("$(", i)) {
+            let depth = 1;
+            let quote;
+            for (let end = i + 2; end < body.length; end += 1) {
+                const ch = body[end];
+                if (quote === "single") {
+                    if (ch === "'")
+                        quote = undefined;
+                    continue;
+                }
+                if (quote === "double") {
+                    if (ch === '"' && body[end - 1] !== "\\")
+                        quote = undefined;
+                    continue;
+                }
+                if (ch === "'" || ch === '"') {
+                    quote = ch === "'" ? "single" : "double";
+                }
+                else if (body.startsWith("$(", end)) {
+                    depth += 1;
+                    end += 1;
+                }
+                else if (ch === ")") {
+                    depth -= 1;
+                    if (depth === 0) {
+                        substitutions.push(body.slice(i + 2, end));
+                        i = end;
+                        break;
+                    }
+                }
+            }
+        }
+        else if (body[i] === "`" && body[i - 1] !== "\\") {
+            const end = body.indexOf("`", i + 1);
+            if (end >= 0) {
+                substitutions.push(body.slice(i + 1, end));
+                i = end;
+            }
+        }
+    }
+    return substitutions;
+}
+function consumeHeredocBodies(command, start, heredocs) {
+    let cursor = start;
+    const substitutions = [];
+    for (const heredoc of heredocs) {
+        const bodyStart = cursor;
+        let found = false;
+        while (cursor < command.length) {
+            const lineEnd = command.indexOf("\n", cursor);
+            const end = lineEnd < 0 ? command.length : lineEnd;
+            let line = command.slice(cursor, end);
+            if (heredoc.stripTabs)
+                line = line.replace(/^\t+/, "");
+            if (line.replace(/\r$/, "") === heredoc.delimiter) {
+                if (!heredoc.quoted)
+                    substitutions.push(...heredocSubstitutionBodies(command.slice(bodyStart, cursor)));
+                cursor = lineEnd < 0 ? end : end + 1;
+                found = true;
+                break;
+            }
+            cursor = lineEnd < 0 ? end : end + 1;
+        }
+        if (!found) {
+            if (!heredoc.quoted)
+                substitutions.push(...heredocSubstitutionBodies(command.slice(bodyStart)));
+            return { end: command.length - 1, substitutions };
+        }
+    }
+    return { end: cursor - 1, substitutions };
 }
 export function tokenizeShellCommand(command) {
     const segments = [];
+    const pendingHeredocs = [];
     let tokens = [];
     let word = "";
     let quote;
@@ -116,12 +227,21 @@ export function tokenizeShellCommand(command) {
                 i++;
             continue;
         }
-        if (/\s/.test(ch)) {
+        if (/\s/.test(ch) && ch !== "\n") {
             flushWord();
             continue;
         }
         if (ch === ";" || ch === "\n" || ch === "|" || ch === "&") {
             flushWord();
+            if (ch === "\n" && pendingHeredocs.length > 0) {
+                const heredocs = pendingHeredocs.splice(0);
+                flushSegment();
+                const consumed = consumeHeredocBodies(command, i + 1, heredocs);
+                for (const substitution of consumed.substitutions)
+                    segments.push(...tokenizeShellCommand(substitution));
+                i = consumed.end;
+                continue;
+            }
             let terminator;
             if (ch === "|" && next === "|")
                 i++;
@@ -138,6 +258,16 @@ export function tokenizeShellCommand(command) {
         }
         if (ch === "<" || ch === ">") {
             flushWord();
+            if (ch === "<" &&
+                next === "<" &&
+                command[i - 1] !== "<" &&
+                command[i + 2] !== "<") {
+                const parsed = parseHeredocDelimiter(command, i + 2);
+                if (parsed) {
+                    pendingHeredocs.push(parsed.heredoc);
+                    i = parsed.end;
+                }
+            }
             unsupported = true;
             continue;
         }

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

@@ -75,8 +75,15 @@ export class BiomeClient {
         const cached = this.localBinaryByCwd.get(resolveCwd);
         if (cached)
             return { cmd: cached, args: [] };
-        // Walk up from cwd looking for node_modules/.bin/biome BEFORE trusting
-        // `autoInstalledBinaryPath` (#1731). That field is set once, the first
+        // Check `<cwd>/node_modules/.bin/biome` BEFORE trusting
+        // `autoInstalledBinaryPath` (#1731). NOT a walk, despite what this
+        // comment claimed until #2544 review F1 — the candidates below are
+        // joined onto `resolveCwd` and nothing climbs. Callers pass the edited
+        // file's own project/sub-package root (see above), which is where an
+        // npm-workspace install puts the shim; converting this to the shared
+        // ancestor walk is a behaviour change with no reported defect behind
+        // it, so it is deliberately NOT part of #2514's ceiling fold. That
+        // field is set once, the first
         // time `ensureAvailable()` auto-installs for ANY cwd this session, and
         // every later call for every OTHER cwd short-circuited on it — so a
         // project that ships its own biome never won once the session's first

package/node_modules/pi-lens/dist/clients/blocker-freshness.js

@@ -61,6 +61,20 @@
  * reads distinctly from #1944's "retired, unrecoverable" — a capped record
  * COULD still resolve a fresh dispatch; it just stopped being handed one for
  * free.
+ *
+ * Widget-footer sibling (#2275). The turn-end blocker channel above is not
+ * the only surface that demotes on dependency drift — `widget-state.ts`'s
+ * own `files` map carries the identical demotion shape
+ * (`markWidgetFileBlockersStale`) through a completely separate store, with
+ * its own `WidgetDiagnostic.staleDeliveryCount` and its own retire helpers
+ * (`incrementWidgetDependencyDriftDelivery`,
+ * `retireWidgetDependencyDriftBlockers`). It counts RENDERS rather than
+ * turn ends — the footer draws one record per pass, so `renderWidget` marks
+ * what it served and the turn-end step drains those marks — and it retires
+ * by HIDING the row from the footer rather than dropping the record, since
+ * the widget store also backs `lens_diagnostics mode=all`. What it shares
+ * with this module is the one number both caps retire against,
+ * `DEPENDENCY_DRIFT_MAX_DELIVERIES`, rather than inventing a second one.
  */
 import * as fs from "node:fs";
 import { normalizeEphemeralMapKey } from "./path-utils.js";
@@ -153,12 +167,6 @@ async function resolveForwardImportsMemoized(cwd, filePath, resolveForwardImport
     });
     return imports;
 }
-/** Test-only: clear the extractor and import-resolution memos. */
-export function _resetBlockerFreshnessForTests() {
-    extractorCache.clear();
-    importResolutionMemo.clear();
-    importResolutionMemoTurnIndex = undefined;
-}
 /**
  * Production forward-import resolver. Parses `filePath` with its tree-sitter grammar
  * and resolves every extracted import source to in-project files. Degrades to an