@herbertgao/pi-extensions 2026.8.4 → 2026.8.5

package/node_modules/pi-lens/README.md

@@ -28,6 +28,11 @@ pi-lens gives AI coding agents fast, language-aware feedback while they write/ed
 - `/lens-map` — interactive HTML dependency map of the project
 - Read-guard and edit-autopatch support to reduce bad edits
 - Background security/dependency scans for opted-in projects
+- Runtime health telemetry (`/lens-health`) including a bounded degradation
+  ledger for silently-degraded behavior (LSP breakers, formatter
+  skips/failures, idle evictions, timeouts)
+- MCP server (experimental) so Claude Code or any MCP client can drive the
+  same diagnostics/read-substitute tools pi-lens exposes to pi
 
 ## Install
 
@@ -70,6 +75,8 @@ pi install git:github.com/apmantza/pi-lens
   and formatters
 - [Dependencies](docs/dependencies.md) — auto-install policy and external tools
 - [Custom rules](docs/custom-rules.md) — project ast-grep and tree-sitter rules
+- [MCP server](docs/mcp.md) — experimental MCP server for Claude Code and
+  other MCP clients
 
 ## Contributing
 
@@ -206,6 +213,12 @@ Thanks goes to these wonderful people:
     </tr>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/pppobear"><img src="https://avatars.githubusercontent.com/u/21952175?v=4" width="100px;" alt=""/><br /><sub><b>pppobear</b></sub></a><br /><a href="#bug-pppobear" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/3choBoomer"><img src="https://avatars.githubusercontent.com/u/521828?v=4" width="100px;" alt=""/><br /><sub><b>Nathan Cooke</b></sub></a><br /><a href="#code-3choBoomer" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/white-hat"><img src="https://avatars.githubusercontent.com/u/922988?v=4" width="100px;" alt=""/><br /><sub><b>Eli Stark</b></sub></a><br /><a href="#code-white-hat" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/marvtub"><img src="https://avatars.githubusercontent.com/u/33159023?v=4" width="100px;" alt=""/><br /><sub><b>Marvin Aziz</b></sub></a><br /><a href="#code-marvtub" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mjfaga"><img src="https://avatars.githubusercontent.com/u/7584015?v=4" width="100px;" alt=""/><br /><sub><b>Mark Faga</b></sub></a><br /><a href="#code-mjfaga" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aeturnal"><img src="https://avatars.githubusercontent.com/u/219271200?v=4" width="100px;" alt=""/><br /><sub><b>aeturnal</b></sub></a><br /><a href="#code-aeturnal" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/floatGray"><img src="https://avatars.githubusercontent.com/u/44295302?v=4" width="100px;" alt=""/><br /><sub><b>floatGray</b></sub></a><br /><a href="#code-floatGray" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

package/node_modules/pi-lens/dist/clients/actionable-warnings.js

@@ -4,9 +4,16 @@ import * as path from "node:path";
 import { applyWorkspaceEdit } from "./lsp/edits.js";
 import { getLSPService } from "./lsp/index.js";
 import { normalizeMapKey } from "./path-utils.js";
+import { recordLspMutationBatch, } from "./lsp-mutation.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 import { logActionableWarningsEvent } from "./actionable-warnings-logger.js";
 import { getProjectDataDir } from "./file-utils.js";
+import { commitDurableStore } from "./durable-store.js";
+let beforeWarningStateLockForTests = null;
+/** Test seam for a sibling process commit immediately before lock acquisition. */
+export function _setBeforeWarningStateLockForTests(hook) {
+    beforeWarningStateLockForTests = hook;
+}
 function normalizeMessage(message) {
     return message.replace(/\s+/g, " ").trim().toLowerCase();
 }
@@ -53,10 +60,9 @@ function serializeAction(action) {
         skipReason: safety.reason,
     };
 }
-function readSuppressionState(cwd) {
-    const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
+function deserializeSuppressionState(contents) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(statePath, "utf-8"));
+        const parsed = JSON.parse(contents ?? "");
         return parsed && typeof parsed === "object"
             ? parsed
             : {};
@@ -65,23 +71,49 @@ function readSuppressionState(cwd) {
         return {};
     }
 }
-function updateWarningState(cwd, warnings) {
+function readSuppressionState(cwd) {
     const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
-    const now = new Date().toISOString();
-    const state = readSuppressionState(cwd);
-    state.warnings ??= {};
-    for (const warning of warnings) {
-        const existing = state.warnings[warning.id] ?? {};
-        state.warnings[warning.id] = {
-            ...existing,
-            status: existing.status ?? "active",
-            firstSeenAt: existing.firstSeenAt ?? now,
-            lastSeenAt: now,
-            seenCount: (existing.seenCount ?? 0) + 1,
-        };
+    try {
+        return deserializeSuppressionState(fs.readFileSync(statePath, "utf8"));
+    }
+    catch {
+        return {};
     }
+}
+function updateWarningState(cwd, warnings) {
+    const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
     fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    const hook = beforeWarningStateLockForTests;
+    beforeWarningStateLockForTests = null;
+    hook?.();
+    commitDurableStore({
+        path: statePath,
+        deserialize: deserializeSuppressionState,
+        merge: (state) => {
+            const now = new Date().toISOString();
+            state.warnings ??= {};
+            for (const warning of warnings) {
+                const existing = state.warnings[warning.id] ?? {};
+                state.warnings[warning.id] = {
+                    ...existing,
+                    status: existing.status ?? "active",
+                    firstSeenAt: existing.firstSeenAt ?? now,
+                    lastSeenAt: now,
+                    seenCount: (existing.seenCount ?? 0) + 1,
+                };
+            }
+            return state;
+        },
+        serialize: (state) => JSON.stringify(state, null, 2),
+        waitMs: 2_000,
+        retryMs: 10,
+        timeoutMessage: "timed out acquiring actionable warning store lock",
+        onContention: "skip-log",
+        logContention: () => logActionableWarningsEvent({
+            event: "warning_state_write_dropped",
+            metadata: { reason: "lock_contention" },
+        }),
+    });
 }
 function suppressionFor(cwd, id) {
     const entry = readSuppressionState(cwd).warnings?.[id];
@@ -452,6 +484,8 @@ export async function applyConservativeActionableWarningFixes(args) {
         skipped: [],
     };
     const changedFiles = new Set();
+    const appliedResults = [];
+    let failedCount = 0;
     const lspService = getLSPService();
     const maxFixes = Math.max(0, args.maxFixes ?? 5);
     for (const file of args.report.files) {
@@ -504,12 +538,23 @@ export async function applyConservativeActionableWarningFixes(args) {
                     continue;
                 }
                 const edit = selected.edit;
-                const applied = await applyWorkspaceEdit(edit, args.cwd);
+                const applied = await applyWorkspaceEdit(edit, args.cwd, args.mutationContext
+                    ? { mutationContext: { ...args.mutationContext, emitSummary: false } }
+                    : undefined);
+                appliedResults.push(applied);
                 for (const changedFile of applied.files)
                     changedFiles.add(changedFile);
                 summary.applied++;
             }
             catch (err) {
+                failedCount++;
+                const partial = err
+                    .appliedWorkspaceEdit;
+                if (partial) {
+                    appliedResults.push(partial);
+                    for (const changedFile of partial.files)
+                        changedFiles.add(changedFile);
+                }
                 const message = err instanceof Error ? err.message : String(err);
                 args.dbg?.(`actionable_warnings_autofix failed for ${warning.id}: ${message}`);
                 summary.skipped.push({ id: warning.id, reason: "apply_failed" });
@@ -517,6 +562,16 @@ export async function applyConservativeActionableWarningFixes(args) {
         }
     }
     summary.changedFiles = [...changedFiles];
+    if (args.mutationContext && (summary.considered > 0 || appliedResults.length > 0)) {
+        recordLspMutationBatch(args.mutationContext, {
+            results: appliedResults,
+            considered: summary.considered,
+            completed: summary.applied,
+            failedCount,
+            status: failedCount > 0 ? "failed" : appliedResults.length > 0 ? "success" : "skipped",
+            bookkeep: false,
+        });
+    }
     return summary;
 }
 export function formatActionableWarningsAdvisory(report) {

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

@@ -2,7 +2,8 @@
  * AgentBehaviorClient for pi-lens
  *
  * Tracks tool call sequences and flags anti-patterns in real-time:
- * - Blind writes: editing or writing without reading first
+ * - Blind writes: editing or writing without reading first (a same-session
+ *   write/edit of the same path counts as file knowledge)
  * - Thrashing: repeated identical tool calls with no progress
  *
  * No external dependencies — purely tracks tool call history.
@@ -23,6 +24,7 @@ export class AgentBehaviorClient {
     lastToolTimestamp = 0;
     // Per-file tracking
     fileEditCount = new Map();
+    static FILE_EDIT_IDLE_MS = 30 * 60_000;
     /**
      * Record a tool call and return any warnings triggered.
      * Called from tool_result handler.
@@ -63,7 +65,14 @@ export class AgentBehaviorClient {
         // Check for blind writes
         if (WRITE_OPS.has(toolName)) {
             const recentWindow = this.toolHistory.slice(-BLIND_WRITE_WINDOW);
-            const hasRecentRead = recentWindow.some((r) => READ_OPS.has(r.toolName));
+            // 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) &&
+                    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;
@@ -82,7 +91,15 @@ export class AgentBehaviorClient {
             // Track edits per file
             if (filePath) {
                 const key = normalizeMapKey(filePath);
-                this.fileEditCount.set(key, (this.fileEditCount.get(key) ?? 0) + 1);
+                this.fileEditCount.set(key, {
+                    count: (this.fileEditCount.get(key)?.count ?? 0) + 1,
+                    lastUsedAt: now,
+                });
+                for (const [pathKey, entry] of this.fileEditCount) {
+                    if (now - entry.lastUsedAt > AgentBehaviorClient.FILE_EDIT_IDLE_MS) {
+                        this.fileEditCount.delete(pathKey);
+                    }
+                }
             }
         }
         // Add to history (keep last 50 entries)
@@ -104,7 +121,7 @@ export class AgentBehaviorClient {
      * Get edit count for a file in this session.
      */
     getEditCount(filePath) {
-        return this.fileEditCount.get(filePath) ?? 0;
+        return this.fileEditCount.get(normalizeMapKey(filePath))?.count ?? 0;
     }
     /**
      * Reset state (e.g., on session start).

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

@@ -7,12 +7,13 @@
  * Requires: npm install -D @ast-grep/cli
  * Rules: ./rules/ directory
  */
+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 { resolvePackagePath } from "./package-root.js";
-import { SgRunner } from "./sg-runner.js";
+import { SgRunner, } from "./sg-runner.js";
 // --- Client ---
 function extractDebugAst(raw) {
     const lines = raw.split(/\r?\n/);
@@ -53,7 +54,7 @@ const VALIDATION_SNIPPETS = {
     html: { ext: "html", source: "<main>pi-lens</main>\n" },
     java: { ext: "java", source: "class Main { void run() {} }\n" },
     javascript: { ext: "js", source: "const piLensValidate = 1;\n" },
-    json: { ext: "json", source: "{\"piLensValidate\":true}\n" },
+    json: { ext: "json", source: '{"piLensValidate":true}\n' },
     kotlin: { ext: "kt", source: "fun main() {}\n" },
     lua: { ext: "lua", source: "local pi_lens_validate = 1\n" },
     php: { ext: "php", source: "<?php $piLensValidate = 1;\n" },
@@ -66,7 +67,10 @@ const VALIDATION_SNIPPETS = {
 };
 function validationSnippetFor(language) {
     const key = language.toLowerCase().replace(/^"|"$/g, "");
-    return VALIDATION_SNIPPETS[key] ?? { ext: key.replace(/[^a-z0-9_-]/gi, "") || "txt", source: "pi_lens_validate\n" };
+    return (VALIDATION_SNIPPETS[key] ?? {
+        ext: key.replace(/[^a-z0-9_-]/gi, "") || "txt",
+        source: "pi_lens_validate\n",
+    });
 }
 function validateInputShape(value, maxChars, label) {
     if (value.includes("\0"))
@@ -110,7 +114,7 @@ export class AstGrepClient {
                     ? projectRuleDir
                     : resolvePackagePath(import.meta.url, "rules"));
         this.log = verbose
-            ? (msg) => console.error(`[ast-grep] ${msg}`)
+            ? createSubsystemLogger("ast-grep")
             : () => { };
         this.ruleManager = new AstGrepRuleManager(this.ruleDir, this.log);
         this.runner = new SgRunner(verbose);
@@ -129,9 +133,18 @@ export class AstGrepClient {
         const allMatches = [];
         for (const scanPath of paths) {
             if (apply) {
-                // Stale-preview check: dry-run first
-                const preCheck = await this.runner.tempScanAsync(scanPath, "agent-rule", ruleYaml);
-                if (preCheck.length === 0) {
+                // Stale-preview check: dry-run first. Preserve CLI failures instead of
+                // treating an invalid rule as a stale, no-match preview.
+                const preCheck = await this.tempScanDetailed(scanPath, ruleYaml);
+                if (preCheck.failure || preCheck.error) {
+                    return {
+                        matches: allMatches,
+                        totalMatches: allMatches.length,
+                        applied: false,
+                        error: preCheck.error ?? "ast-grep preview failed",
+                    };
+                }
+                if (preCheck.matches.length === 0) {
                     return {
                         matches: [],
                         totalMatches: 0,
@@ -162,12 +175,31 @@ export class AstGrepClient {
      * Routes through sg scan --config rather than sg run -p.
      * Each path is scanned independently; results are merged.
      */
-    async searchWithRule(ruleYaml, paths) {
+    async tempScanDetailed(dir, ruleYaml, options = {}) {
+        // Keep tests and older embedders that replace the runner with the historic
+        // match-only seam working. The production SgRunner always has the detailed
+        // method, so failures cannot be mistaken for an empty result there.
+        const detailed = this.runner.tempScanDetailedAsync;
+        if (detailed) {
+            return detailed.call(this.runner, dir, "agent-rule", ruleYaml, 30_000, options);
+        }
+        const matches = await this.runner.tempScanAsync(dir, "agent-rule", ruleYaml, 30_000, options);
+        return { matches, status: 0 };
+    }
+    async searchWithRule(ruleYaml, paths, options = {}) {
         const allMatches = [];
         for (const scanPath of paths) {
             try {
-                const results = await this.runner.tempScanAsync(scanPath, "agent-rule", ruleYaml);
-                allMatches.push(...results);
+                const results = await this.tempScanDetailed(scanPath, ruleYaml, options);
+                if (results.failure || results.error) {
+                    return {
+                        matches: allMatches,
+                        totalMatches: allMatches.length,
+                        error: results.error ||
+                            `ast-grep scan failed (${results.failure ?? "unknown failure"})`,
+                    };
+                }
+                allMatches.push(...results.matches);
             }
             catch (err) {
                 return {
@@ -227,11 +259,24 @@ export class AstGrepClient {
             if (options?.strictness)
                 args.push("--strictness", options.strictness);
             args.push(tmpFile);
-            const result = await this.runner.execRaw(args);
+            const result = await this.runner.execRaw(args, 10_000, options);
             const stderr = result.stderr.trim();
             const stdout = result.stdout.trim();
             if (result.error)
                 return { valid: false, error: result.error };
+            if (result.status !== 0 && !(result.status === 1 && !stderr)) {
+                return {
+                    valid: false,
+                    error: stderr ||
+                        `ast-grep validation failed with exit code ${result.status}`,
+                };
+            }
+            if (result.outputTruncated) {
+                return {
+                    valid: false,
+                    error: "ast-grep validation output was truncated",
+                };
+            }
             if (stderrHasError(stderr))
                 return { valid: false, error: stderr };
             const warning = stderr || stdout || undefined;
@@ -249,7 +294,7 @@ export class AstGrepClient {
             }
         }
     }
-    async validateRule(ruleYaml) {
+    async validateRule(ruleYaml, options = {}) {
         const shapeError = validateInputShape(ruleYaml, MAX_VALIDATE_RULE_CHARS, "rule");
         if (shapeError)
             return { valid: false, error: shapeError };
@@ -258,7 +303,14 @@ export class AstGrepClient {
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-lens-sg-rule-"));
         try {
             fs.writeFileSync(path.join(tmpDir, `snippet.${snippet.ext}`), snippet.source, "utf-8");
-            await this.runner.tempScanAsync(tmpDir, "agent-rule", ruleYaml, 10000);
+            const result = await this.tempScanDetailed(tmpDir, ruleYaml, options);
+            if (result.failure || result.error) {
+                return {
+                    valid: false,
+                    error: result.error ||
+                        `ast-grep rule validation failed (${result.failure ?? "unknown failure"})`,
+                };
+            }
             return { valid: true };
         }
         catch (err) {
@@ -332,7 +384,7 @@ export class AstGrepClient {
             args.push("--strictness", options.strictness);
         }
         args.push(...paths);
-        const result = await this.runner.exec(args);
+        const result = await this.runner.exec(args, options);
         return {
             matches: result.matches,
             totalMatches: result.totalMatches,
@@ -505,8 +557,8 @@ message: found
         }
         return exports;
     }
-    formatMatches(matches, isDryRun = false, showModeIndicator = false) {
-        return this.runner.formatMatches(matches, isDryRun, 50, showModeIndicator);
+    formatMatches(matches, isDryRun = false, showModeIndicator = false, maxItems = 50) {
+        return this.runner.formatMatches(matches, isDryRun, maxItems, showModeIndicator);
     }
     /**
      * Format diagnostics for LLM consumption

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

@@ -3,7 +3,6 @@
  *
  * Extracted to prevent circular dependencies between:
  * - ast-grep-client.ts
- * - ast-grep-parser.ts
  * - ast-grep-rule-manager.ts
  */
 export {};

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

@@ -21,7 +21,12 @@ const NODE_KIND_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
  * Returns true when at least one structural-intent field is present.
  */
 export function hasStructuralIntent(intent) {
-    return !!(intent.insideKind || intent.hasKind || intent.follows || intent.precedes);
+    return !!(intent.nodeKind ||
+        intent.insideKind ||
+        intent.hasKind ||
+        intent.hasDescendantKind ||
+        intent.follows ||
+        intent.precedes);
 }
 /**
  * Synthesize an ast-grep YAML rule for replace operations.
@@ -33,26 +38,48 @@ export function synthesizeReplaceRule(intent) {
     return `${base}fix: ${JSON.stringify(intent.rewrite)}\n`;
 }
 /**
- * Synthesize an ast-grep YAML rule from a pattern and structural constraints.
+ * Synthesize an ast-grep YAML rule from a pattern (or node kind) and
+ * structural constraints.
  *
- * The generated rule uses `stopBy: end` on `inside` so the search climbs
- * all ancestors, not just the immediate parent.
+ * The generated rule uses `stopBy: end` on `inside` and
+ * `hasDescendantKind`, so those two explicit recursive forms climb all
+ * ancestors/descendants. `hasKind` intentionally retains ast-grep's default
+ * immediate-child semantics for compatibility.
  *
- * @throws if pattern is empty
+ * @throws if neither pattern nor nodeKind is supplied, or both are supplied
  */
 export function synthesizeRule(intent) {
-    assertSafePattern(intent.pattern, "pattern");
+    const hasPattern = !!intent.pattern?.trim();
+    const hasNodeKind = !!intent.nodeKind?.trim();
+    if (hasPattern === hasNodeKind) {
+        throw new Error("provide exactly one of pattern or nodeKind");
+    }
+    const pattern = intent.pattern;
+    if (hasPattern && pattern)
+        assertSafePattern(pattern, "pattern");
+    if (intent.hasKind?.trim() && intent.hasDescendantKind?.trim()) {
+        throw new Error("hasKind and hasDescendantKind are mutually exclusive");
+    }
     // Canonical language name for the YAML header (ast-grep is case-sensitive here).
     const language = canonicalLanguage(intent.lang);
-    const rule = {
-        pattern: intent.pattern,
-    };
+    const rule = hasNodeKind
+        ? { kind: assertSafeNodeKind(intent.nodeKind ?? "", "nodeKind") }
+        : { pattern };
     if (intent.insideKind) {
-        rule.inside = { kind: assertSafeNodeKind(intent.insideKind, "insideKind"), stopBy: "end" };
+        rule.inside = {
+            kind: assertSafeNodeKind(intent.insideKind, "insideKind"),
+            stopBy: "end",
+        };
     }
     if (intent.hasKind) {
         rule.has = { kind: assertSafeNodeKind(intent.hasKind, "hasKind") };
     }
+    if (intent.hasDescendantKind) {
+        rule.has = {
+            kind: assertSafeNodeKind(intent.hasDescendantKind, "hasDescendantKind"),
+            stopBy: "end",
+        };
+    }
     if (intent.follows) {
         assertSafePattern(intent.follows, "follows");
         rule.follows = { pattern: intent.follows };

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

@@ -0,0 +1,63 @@
+/** Owns the generic atomic-write `.tmp-<pid>-<threadId>-<seq>` namespace. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { threadId } from "node:worker_threads";
+let stageSeq = 0;
+export const STAGE_TMP_PATTERN = /\.tmp-(0|[1-9]\d*)-(0|[1-9]\d*)-(0|[1-9]\d*)$/;
+const STAGE_TMP_PID_PATTERN = /\.tmp-(0|[1-9]\d*)-(?:0|[1-9]\d*)-(?:0|[1-9]\d*)$/;
+export function stagePathFor(targetPath) {
+    return `${targetPath}.tmp-${process.pid}-${threadId}-${stageSeq++}`;
+}
+export function stageOwnerPidFromName(name) {
+    if (!STAGE_TMP_PATTERN.test(name))
+        return undefined;
+    const match = STAGE_TMP_PID_PATTERN.exec(name);
+    if (!match)
+        return undefined;
+    const pid = Number(match[1]);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+}
+export async function sweepOwnStagingFiles(directories, options) {
+    const uniqueDirectories = [...new Set(directories)].filter(Boolean);
+    const result = { directories: uniqueDirectories.length, scanned: 0, removed: 0, liveSkipped: 0, truncated: false };
+    for (const directory of uniqueDirectories) {
+        let handle;
+        try {
+            handle = await fs.promises.opendir(directory);
+        }
+        catch {
+            continue;
+        }
+        try {
+            let reachedEntryCap = true;
+            for (let i = 0; i < options.maxEntries; i++) {
+                const entry = await handle.read();
+                if (entry === null) {
+                    reachedEntryCap = false;
+                    break;
+                }
+                result.scanned++;
+                if (!entry.isFile())
+                    continue;
+                const pid = stageOwnerPidFromName(entry.name);
+                if (pid === undefined)
+                    continue;
+                if (pid === process.pid || options.isPidAlive(pid)) {
+                    result.liveSkipped++;
+                    continue;
+                }
+                try {
+                    await fs.promises.rm(path.join(directory, entry.name), { force: true });
+                    result.removed++;
+                }
+                catch { /* leave it for the next bounded sweep */ }
+            }
+            result.truncated ||= reachedEntryCap;
+        }
+        catch { /* best-effort directory scan */ }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
+    return result;
+}