@llblab/pi-actors 0.43.0 → 0.43.1

package/README.md

@@ -53,8 +53,10 @@ Send one exact Control:
 Run targets accept only actions declared by the captured Recipe. Runtime targets accept only reserved review actions:
 
 ```text
-message target=runtime action=review.retry
-message target=runtime action=review.reset
+message target=runtime action=review.retry input={"scope":"draft"}
+message target=runtime action=review.retry input={"scope":"tool"}
+message target=runtime action=review.reset input={"scope":"draft"}
+message target=runtime action=review.reset input={"scope":"tool"}
 ```
 
 Lifecycle `kill` remains runtime-owned rather than Recipe-declared.
@@ -67,9 +69,9 @@ Inspect one exact management target:
 inspect target=run:test view=recipe
 inspect target=run:test view=trace source=lifecycle lines=40
 inspect target=run:test view=control
-inspect target=runtime
-inspect target=recipes
-inspect target=tool:my_tool
+inspect target=runtime view=status
+inspect target=recipes view=status
+inspect target=tool:my_tool view=status
 ```
 
 A Run exposes exactly `recipe`, `trace`, and `control` views.
@@ -119,7 +121,7 @@ String command-template leaves execute directly without shell interpretation. Us
 }
 ```
 
-Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation.
+Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation. The canonical append authority validates and size-checks under a cross-process mutation lock before one append-only JSONL write; first-party scripts never append this file directly.
 
 Use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context. Store large evidence in artifacts or bounded execution captures.
 
@@ -138,7 +140,7 @@ Long-lived services publish `control-endpoint.json` only when ready:
 }
 ```
 
-Supported transports are Unix FIFO and Windows named pipe. FIFO wire documents must fit the portable 512-byte atomic-write bound; larger Control input remains available to named-pipe services. Delivery revalidates owner, generation, state, and process identity under the canonical lifecycle lock.
+Supported transports are Unix FIFO and Windows named pipe. Every actor-local Control uses the same portable envelope: action is at most 64 lowercase ASCII characters, serialized JSON input is at most 380 bytes, and the newline-terminated wire record is at most 512 bytes. Put larger data in a declared artifact/path and send only its bounded reference or instruction through Control. Delivery revalidates owner, generation, state, and process identity under the canonical lifecycle lock.
 
 ## Run State
 

package/dist/index.js

@@ -106,7 +106,7 @@ export default function toolRegistryExtension(pi) {
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         getActiveTools: () => pi.getActiveTools(),
         getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
-        handleRuntimeMessage: automaticReview.handleMessage,
+        handleRuntimeControl: automaticReview.handleControl,
         registryRuntime: runtime,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     }).map(withCurrentThinkingContext));

package/dist/lib/async-runs.d.ts

@@ -7,6 +7,7 @@ import { type CurrentPolicyProvenance } from "./model-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
 import { type RunProcessIdentity } from "./runs-process.ts";
+import * as RuntimeIdentity from "./runtime-identity.ts";
 import * as RunsIndex from "./runs-index.ts";
 import * as RunsParentTeardown from "./runs-parent-teardown.ts";
 import { type DeliverRunControlOptions, type DeliverRunControlRequest } from "./runs-control-delivery.ts";
@@ -77,7 +78,7 @@ export interface AsyncRunMeta {
     run: string;
     run_instance_id: string;
     state_dir: string;
-    state_schema: "run-kernel-v1";
+    state_schema: typeof RuntimeIdentity.RUN_STATE_SCHEMA;
     status: AsyncRunStatus;
     tool?: string;
     template: CommandTemplateValue;

package/dist/lib/async-runs.js

@@ -18,6 +18,7 @@ import { buildTerminalProgress, markTerminalHandled, signalOwnedRunProcess, } fr
 import { claimRunStateDirectory } from "./runs-ownership.js";
 import { appendRunRetentionEvidence, archiveTerminalRun, pruneTerminalRun, } from "./runs-retention.js";
 import { captureRunProcessIdentity, verifyRunProcessIdentity, } from "./runs-process.js";
+import * as RuntimeIdentity from "./runtime-identity.js";
 import * as RunsStart from "./runs-start.js";
 import { appendRunTraceEvent } from "./runs-trace.js";
 import * as RunsIndex from "./runs-index.js";
@@ -236,7 +237,21 @@ export function startRun(params, cwd) {
     const resolved = resolveRunTemplate(startParams);
     const run = safeRunId(startParams.run_id);
     const stateDir = resolveStateDir(startParams, run);
+    const recipeFile = startParams.file
+        ? resolveRecipeFile(startParams.file)
+        : undefined;
+    const packagedRecipeRoot = resolve(Paths.getPackagedRecipeRoot());
+    const recipeRelation = recipeFile
+        ? relative(packagedRecipeRoot, recipeFile)
+        : undefined;
+    const packagedRepo = startParams.defaults?.repo === "~/.pi/agent/extensions/pi-actors" &&
+        recipeRelation &&
+        !recipeRelation.startsWith("..") &&
+        !isAbsolute(recipeRelation)
+        ? dirname(packagedRecipeRoot)
+        : undefined;
     const values = {
+        ...(packagedRepo ? { repo: packagedRepo } : {}),
         ...(startParams.values || {}),
         run_id: run,
         state_dir: stateDir,
@@ -259,9 +274,6 @@ export function startRun(params, cwd) {
         prepareStateDirForStart(stateDir);
         const stdout = join(stateDir, "stdout.log");
         const stderr = join(stateDir, "stderr.log");
-        const recipeFile = startParams.file
-            ? resolveRecipeFile(startParams.file)
-            : undefined;
         const recipe = startParams.name || getRunIdFromFile(recipeFile);
         const includeActorRecipeContext = startParams.actor_context !== false &&
             startParams.actor_context !== "off";
@@ -298,7 +310,7 @@ export function startRun(params, cwd) {
             run,
             run_instance_id: randomUUID(),
             state_dir: stateDir,
-            state_schema: "run-kernel-v1",
+            state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
             status: "running",
             ...(startParams.tool ? { tool: startParams.tool } : {}),
             template: resolved.template,

package/dist/lib/automatic-review-runtime.d.ts

@@ -6,7 +6,7 @@
 import type * as Pi from "./pi.ts";
 export interface AutomaticReviewRuntime {
     close(): void;
-    handleMessage(type: string, body: unknown): Record<string, unknown>;
+    handleControl(action: string, input: unknown): Record<string, unknown>;
     schedule(): void;
     start(ctx: Pi.ExtensionContext): void;
 }

package/dist/lib/automatic-review-runtime.js

@@ -26,14 +26,14 @@ export function createAutomaticReviewRuntime(deps) {
     });
     return {
         close,
-        handleMessage(type, body) {
-            if (type !== "review.retry" && type !== "review.reset") {
-                throw new Error("tool:pi-actors accepts review.retry or review.reset messages.");
+        handleControl(action, input) {
+            if (action !== "review.retry" && action !== "review.reset") {
+                throw new Error("runtime accepts review.retry or review.reset Controls.");
             }
-            if (type === "review.retry" && !Paths.isAutomaticRecipeReviewEnabled()) {
+            if (action === "review.retry" && !Paths.isAutomaticRecipeReviewEnabled()) {
                 throw new Error("Automatic recipe review is disabled by PI_ACTORS_AUTOMATIC_REVIEW.");
             }
-            return ReviewControl.controlAutomaticReview(type, ReviewControl.parseAutomaticReviewScope(body), {
+            return ReviewControl.controlAutomaticReview(action, ReviewControl.parseAutomaticReviewScope(input), {
                 scheduleDraft: () => draftScheduler?.schedule(),
                 scheduleTool: () => toolScheduler?.schedule(),
             });

package/dist/lib/command-templates.d.ts

@@ -74,6 +74,8 @@ export declare function getCommandTemplateRiskLabels(config: CommandTemplateConf
 export declare function getCommandTemplateDefaults(config: CommandTemplateConfig | undefined): Record<string, string>;
 export declare function splitCommandTemplate(input: string): string[];
 export declare function expandCommandTemplateExecutable(command: string, cwd: string): string;
+export type CommandTemplateExecutableResolver = (name: string) => string | undefined;
+export declare function resolveCommandTemplateScriptInvocation(invocation: CommandTemplateInvocation, resolveExecutable?: CommandTemplateExecutableResolver): CommandTemplateInvocation;
 export declare function shouldRunCommandTemplateNode(value: boolean | string | undefined, values: Record<string, unknown>): boolean;
 export declare function substituteCommandTemplateToken(token: string, values: Record<string, unknown>, missingLabel?: string, depth?: number): string;
 export declare function execCommandTemplate(command: string, args: string[], options?: CommandTemplateExecOptions): Promise<CommandTemplateExecResult>;

package/dist/lib/command-templates.js

@@ -4,9 +4,9 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 import { spawn } from "node:child_process";
-import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { accessSync, appendFileSync, constants, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import { basename, delimiter, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
 const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
 const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
     "risk.shell",
@@ -135,7 +135,7 @@ function getLeafCommandTemplateRiskLabels(config) {
     const command = getExecutableName(parts[0]);
     const args = parts.slice(1);
     const labels = new Set();
-    if (["bash", "sh", "zsh", "fish"].includes(command)) {
+    if (["bash", "sh", "zsh", "fish"].includes(command) || command.endsWith(".sh")) {
         labels.add("risk.shell");
         if (hasAnyFlag(args, ["-c"]))
             labels.add("risk.eval");
@@ -393,6 +393,40 @@ export function expandCommandTemplateExecutable(command, cwd) {
         return resolvePath(cwd, command);
     return command;
 }
+function resolveExecutableOnPath(name) {
+    if (name === "node" && /^node(?:\.exe)?$/i.test(basename(process.execPath)))
+        return process.execPath;
+    const pathValue = Object.entries(process.env)
+        .find(([key]) => key.toLowerCase() === "path")?.[1] ?? "";
+    const suffixes = process.platform === "win32" ? [".exe", ".com"] : [""];
+    for (const entry of pathValue.split(delimiter).filter(Boolean)) {
+        const directory = entry.replace(/^"|"$/g, "");
+        for (const suffix of suffixes) {
+            const candidate = join(directory, `${name}${suffix}`);
+            try {
+                accessSync(candidate, constants.X_OK);
+                if (statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch { }
+        }
+    }
+    return undefined;
+}
+export function resolveCommandTemplateScriptInvocation(invocation, resolveExecutable = resolveExecutableOnPath) {
+    const extension = extname(invocation.command).toLowerCase();
+    const interpreters = extension === ".js" || extension === ".mjs"
+        ? [["node"], ["bun"], ["deno", "run"]]
+        : extension === ".sh" ? [["bash"]] : [];
+    if (interpreters.length === 0)
+        return invocation;
+    for (const [name, ...prefix] of interpreters) {
+        const executable = resolveExecutable(name);
+        if (executable)
+            return { command: executable, args: [...prefix, invocation.command, ...invocation.args] };
+    }
+    throw new Error(`No interpreter available for command-template ${extension} script; tried ${interpreters.map(([name]) => name).join(", ")}.`);
+}
 function evaluateCommandTemplateExpression(expression, values) {
     let index = 0;
     const source = expression.replace(/\s+/g, "");
@@ -766,5 +800,5 @@ export function buildCommandTemplateInvocation(config, values, cwd, options = {}
         .slice(1)
         .map((part) => substituteCommandTemplateToken(part, resolvedValues, options.missingLabel))
         .filter((part) => part !== "");
-    return { command, args };
+    return resolveCommandTemplateScriptInvocation({ command, args });
 }

package/dist/lib/control-projection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+export interface ProjectedRunControl {
+    action: string;
+    claimed_at?: string;
+    delivered_at?: string;
+    error?: string;
+    failed_at?: string;
+    handled_at?: string;
+    id: string;
+    input?: unknown;
+    queued_at: string;
+    run_instance_id: string;
+    status: RunControlStatus;
+}
+export declare function projectRunControl(control: RunControlRecord): ProjectedRunControl;

package/dist/lib/control-projection.js

@@ -0,0 +1,66 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import * as Limits from "./limits.js";
+import * as SessionEvidence from "./session-evidence.js";
+const OPTIONAL_TIMESTAMP_FIELDS = [
+    "claimed_at",
+    "delivered_at",
+    "failed_at",
+    "handled_at",
+];
+function boundedRedactedString(value, maxChars) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, maxChars);
+    return typeof redacted === "string"
+        ? redacted
+        : String(redacted).slice(0, maxChars);
+}
+function boundedRedactedValue(value) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let serialized;
+    try {
+        serialized = JSON.stringify(redacted);
+    }
+    catch {
+        return "[UNSERIALIZABLE]";
+    }
+    if (serialized === undefined)
+        return "[UNSERIALIZABLE]";
+    if (serialized.length <= Limits.INSPECTOR_BODY_PREVIEW_CHARS)
+        return redacted;
+    let preview = serialized.slice(0, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let bounded = { preview: `${preview}…`, truncated: true };
+    while (preview &&
+        JSON.stringify(bounded).length > Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
+        const excess = JSON.stringify(bounded).length - Limits.INSPECTOR_BODY_PREVIEW_CHARS;
+        preview = preview.slice(0, Math.max(0, preview.length - Math.max(1, excess)));
+        bounded = { preview: `${preview}…`, truncated: true };
+    }
+    return bounded;
+}
+export function projectRunControl(control) {
+    const timestamps = Object.fromEntries(OPTIONAL_TIMESTAMP_FIELDS.flatMap((field) => {
+        const value = control[field];
+        return typeof value === "string"
+            ? [[field, boundedRedactedString(value, Limits.COMPACT_PREVIEW_CHARS)]]
+            : [];
+    }));
+    return {
+        action: boundedRedactedString(control.action, Limits.COMPACT_PREVIEW_CHARS),
+        ...timestamps,
+        ...(typeof control.error === "string"
+            ? {
+                error: boundedRedactedString(control.error, Limits.INSPECTOR_BODY_PREVIEW_CHARS),
+            }
+            : {}),
+        id: boundedRedactedString(control.id, Limits.COMPACT_PREVIEW_CHARS),
+        ...(control.input !== undefined
+            ? { input: boundedRedactedValue(control.input) }
+            : {}),
+        queued_at: boundedRedactedString(control.queued_at, Limits.COMPACT_PREVIEW_CHARS),
+        run_instance_id: boundedRedactedString(control.run_instance_id, Limits.COMPACT_PREVIEW_CHARS),
+        status: boundedRedactedString(control.status, Limits.COMPACT_PREVIEW_CHARS),
+    };
+}

package/dist/lib/control.d.ts

@@ -9,4 +9,7 @@ export interface ControlRequest {
     input?: unknown;
     verbose?: boolean;
 }
+export declare function isControlAction(value: string): boolean;
+export declare function normalizeControlAction(value: unknown): string;
+export declare function normalizeControlInput(input: unknown): unknown;
 export declare function normalizeControlRequest(input: unknown): ControlRequest;

package/dist/lib/control.js

@@ -17,7 +17,23 @@ const REMOVED_FIELDS = new Set([
     "to",
     "type",
 ]);
-function serializedInputBytes(input) {
+export function isControlAction(value) {
+    return ACTION_PATTERN.test(value);
+}
+export function normalizeControlAction(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error("control.action is required");
+    }
+    const action = value.trim();
+    if (!isControlAction(action)) {
+        throw new Error(`invalid control action: ${action}`);
+    }
+    if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+        throw new Error(`control.action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters`);
+    }
+    return action;
+}
+export function normalizeControlInput(input) {
     let serialized;
     try {
         serialized = JSON.stringify(input);
@@ -28,7 +44,11 @@ function serializedInputBytes(input) {
     if (serialized === undefined) {
         throw new Error("control.input must be JSON-serializable");
     }
-    return Buffer.byteLength(serialized);
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes > Limits.CONTROL_INPUT_MAX_BYTES) {
+        throw new Error(`control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} serialized bytes`);
+    }
+    return JSON.parse(serialized);
 }
 function normalizeTarget(value) {
     if (typeof value !== "string" || !value.trim()) {
@@ -61,24 +81,17 @@ export function normalizeControlRequest(input) {
         throw new Error(`unsupported control fields: ${unknown.sort().join(", ")}`);
     }
     const target = normalizeTarget(record.target);
-    if (typeof record.action !== "string" || !record.action.trim()) {
-        throw new Error("control.action is required");
-    }
-    const action = record.action.trim();
-    if (!ACTION_PATTERN.test(action)) {
-        throw new Error(`invalid control action: ${action}`);
-    }
+    const action = normalizeControlAction(record.action);
     if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
         throw new Error("control.verbose must be a boolean");
     }
-    if (record.input !== undefined &&
-        serializedInputBytes(record.input) > Limits.CONTROL_INPUT_MAX_BYTES) {
-        throw new Error(`control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} bytes`);
-    }
+    const normalizedInput = record.input === undefined
+        ? undefined
+        : normalizeControlInput(record.input);
     return {
         target,
         action,
-        ...(record.input !== undefined ? { input: record.input } : {}),
+        ...(normalizedInput !== undefined ? { input: normalizedInput } : {}),
         ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
     };
 }

package/dist/lib/draft-sleep.js

@@ -391,7 +391,7 @@ export function createDraftSleepScheduler(deps) {
                                 ...existing,
                                 failedStage: processed.stage ?? "result_processing",
                                 lastError: processed.error ?? "automatic draft review processing failed",
-                                nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                                nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                                 phase: "processing_failed",
                                 processingAttempts: (existing.processingAttempts ?? 0) + 1,
                                 updatedAt: now().toISOString(),
@@ -402,7 +402,7 @@ export function createDraftSleepScheduler(deps) {
                             ...existing,
                             failedStage: processed.stage ?? "review_result",
                             lastError: processed.error ?? "automatic draft reviewer failed",
-                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                             phase: "failed",
                             runId: undefined,
                             updatedAt: now().toISOString(),
@@ -444,7 +444,7 @@ export function createDraftSleepScheduler(deps) {
                             attempts: (prior?.batchId === batch.batchId ? prior.attempts : 0) + 1,
                             failedStage: "review_launch",
                             lastError: error instanceof Error ? error.message : String(error),
-                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                             batchId: batch.batchId,
                             inputPath: batch.inputPath,
                             phase: "failed",

package/dist/lib/file-state.d.ts

@@ -5,6 +5,7 @@
  */
 export declare function mutationLockPath(path: string): string;
 export interface FileMutationLockOptions {
+    onBeforeLockPublish?(): void;
     onBeforeReclaimRemove?(): void;
     onContention?(): void;
     onRemovalContention?(): void;

package/dist/lib/file-state.js

@@ -3,11 +3,12 @@
  * Zones: file persistence, atomic writes, runtime state support
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
+import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, parse, resolve } from "node:path";
-const FILE_MUTATION_LOCK_TIMEOUT_MS = 5000;
+const FILE_MUTATION_LOCK_TIMEOUT_MS = process.platform === "win32" ? 15000 : 5000;
 const FILE_MUTATION_LOCK_STALE_MS = 30000;
 const FILE_MUTATION_LOCK_ROOT = join(tmpdir(), "pi-actors-file-locks");
 function canonicalMutationPath(path) {
@@ -42,6 +43,20 @@ export function mutationLockPath(path) {
         .digest("hex");
     return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
 }
+function isZombieProcess(pid) {
+    if (process.platform === "linux")
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            return stat.slice(stat.lastIndexOf(")") + 2).startsWith("Z ");
+        }
+        catch {
+            return false;
+        }
+    if (process.platform !== "darwin")
+        return false;
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "stat="], { encoding: "utf8" });
+    return result.status === 0 && result.stdout.trim().startsWith("Z");
+}
 function lockOwnerStatus(lockPath) {
     try {
         const owner = JSON.parse(readFileSync(join(lockPath, "owner.json"), "utf8"));
@@ -50,6 +65,8 @@ function lockOwnerStatus(lockPath) {
             return "unknown";
         try {
             process.kill(pid, 0);
+            if (Date.now() - statSync(lockPath).mtimeMs > 50 && isZombieProcess(pid))
+                return "dead";
             return "alive";
         }
         catch (error) {
@@ -71,6 +88,46 @@ function readLockToken(lockPath) {
         return undefined;
     }
 }
+function prepareLockBoundary(lockPath, token, onBeforePublish) {
+    const pendingPath = `${lockPath}.${process.pid}.${token}.pending`;
+    try {
+        mkdirSync(pendingPath);
+        writeFileSync(join(pendingPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+        onBeforePublish?.();
+        return pendingPath;
+    }
+    catch (error) {
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
+        }
+        catch { }
+        throw error;
+    }
+}
+function removeLockBoundary(lockPath, token) {
+    if (readLockToken(lockPath) !== token)
+        return false;
+    if (process.platform === "win32")
+        try {
+            rmSync(lockPath, { recursive: true, force: true, maxRetries: 20, retryDelay: 5 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    const removingPath = `${lockPath}.${process.pid}.${randomUUID()}.removing`;
+    try {
+        renameSync(lockPath, removingPath);
+    }
+    catch {
+        return false;
+    }
+    try {
+        rmSync(removingPath, { recursive: true, force: true });
+    }
+    catch { }
+    return true;
+}
 function tryReclaimRemovalBoundary(reclaimPath) {
     if (!existsSync(reclaimPath))
         return;
@@ -81,7 +138,7 @@ function tryReclaimRemovalBoundary(reclaimPath) {
         if ((ownerStatus === "dead" ||
             (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
             readLockToken(reclaimPath) === inspectedToken) {
-            rmSync(reclaimPath, { recursive: true, force: true });
+            removeLockBoundary(reclaimPath, inspectedToken);
         }
     }
     catch {
@@ -91,28 +148,28 @@ function tryReclaimRemovalBoundary(reclaimPath) {
 function withRemovalBoundary(lockPath, action) {
     const reclaimPath = `${lockPath}.reclaim`;
     const token = randomUUID();
+    const pendingPath = prepareLockBoundary(reclaimPath, token);
     try {
-        mkdirSync(reclaimPath);
         try {
-            writeFileSync(join(reclaimPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+            renameSync(pendingPath, reclaimPath);
         }
-        catch (error) {
-            rmSync(reclaimPath, { recursive: true, force: true });
-            throw error;
+        catch {
+            tryReclaimRemovalBoundary(reclaimPath);
+            return false;
+        }
+        try {
+            action();
+            return true;
+        }
+        finally {
+            removeLockBoundary(reclaimPath, token);
         }
-    }
-    catch {
-        tryReclaimRemovalBoundary(reclaimPath);
-        return false;
-    }
-    try {
-        action();
-        return true;
     }
     finally {
-        if (readLockToken(reclaimPath) === token) {
-            rmSync(reclaimPath, { recursive: true, force: true });
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
         }
+        catch { }
     }
 }
 function tryReclaimMutationLock(lockPath, options) {
@@ -129,8 +186,7 @@ function tryReclaimMutationLock(lockPath, options) {
             (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
             readLockToken(lockPath) === inspectedToken) {
             options.onBeforeReclaimRemove?.();
-            rmSync(lockPath, { recursive: true, force: true });
-            reclaimed = true;
+            reclaimed = removeLockBoundary(lockPath, inspectedToken);
         }
     })) {
         return false;
@@ -142,32 +198,34 @@ export function acquireFileMutationLock(path, options = {}) {
     const lockPath = mutationLockPath(path);
     const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
     const token = randomUUID();
+    const pendingPath = prepareLockBoundary(lockPath, token, options.onBeforeLockPublish);
     let contentionReported = false;
-    for (;;) {
-        try {
-            mkdirSync(lockPath);
+    try {
+        for (;;) {
             try {
-                writeFileSync(join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+                renameSync(pendingPath, lockPath);
+                break;
             }
             catch (error) {
-                rmSync(lockPath, { recursive: true, force: true });
-                throw error;
+                if (!contentionReported) {
+                    contentionReported = true;
+                    options.onContention?.();
+                }
+                tryReclaimMutationLock(lockPath, options);
+                if (Date.now() >= deadline) {
+                    throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
+                        cause: error,
+                    });
+                }
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
             }
-            break;
         }
-        catch (error) {
-            if (!contentionReported) {
-                contentionReported = true;
-                options.onContention?.();
-            }
-            tryReclaimMutationLock(lockPath, options);
-            if (Date.now() >= deadline) {
-                throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
-                    cause: error,
-                });
-            }
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+    finally {
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
         }
+        catch { }
     }
     let released = false;
     return () => {
@@ -177,9 +235,7 @@ export function acquireFileMutationLock(path, options = {}) {
         const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
         let removalContentionReported = false;
         while (!withRemovalBoundary(lockPath, () => {
-            if (readLockToken(lockPath) === token) {
-                rmSync(lockPath, { recursive: true, force: true });
-            }
+            removeLockBoundary(lockPath, token);
         })) {
             if (!removalContentionReported) {
                 removalContentionReported = true;