@llblab/pi-actors 0.42.3 → 0.43.1

package/lib/command-templates.ts

@@ -5,9 +5,9 @@
  */
 
 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";
 
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
@@ -259,7 +259,7 @@ function getLeafCommandTemplateRiskLabels(
   const command = getExecutableName(parts[0]);
   const args = parts.slice(1);
   const labels = new Set<CommandTemplateRiskLabel>();
-  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");
   }
@@ -602,6 +602,46 @@ export function expandCommandTemplateExecutable(
   return command;
 }
 
+export type CommandTemplateExecutableResolver = (name: string) => string | undefined;
+
+function resolveExecutableOnPath(name: string): string | undefined {
+  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: CommandTemplateInvocation,
+  resolveExecutable: CommandTemplateExecutableResolver = resolveExecutableOnPath,
+): CommandTemplateInvocation {
+  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: string,
   values: Record<string, unknown>,
@@ -1072,5 +1112,5 @@ export function buildCommandTemplateInvocation(
       ),
     )
     .filter((part) => part !== "");
-  return { command, args };
+  return resolveCommandTemplateScriptInvocation({ command, args });
 }

package/lib/control-projection.ts

@@ -0,0 +1,105 @@
+/**
+ * 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.ts";
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+import * as SessionEvidence from "./session-evidence.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;
+}
+
+const OPTIONAL_TIMESTAMP_FIELDS = [
+  "claimed_at",
+  "delivered_at",
+  "failed_at",
+  "handled_at",
+] as const;
+type OptionalTimestampField = (typeof OPTIONAL_TIMESTAMP_FIELDS)[number];
+
+function boundedRedactedString(value: string, maxChars: number): string {
+  const redacted = SessionEvidence.redactSessionEvidenceValue(value, maxChars);
+  return typeof redacted === "string"
+    ? redacted
+    : String(redacted).slice(0, maxChars);
+}
+
+function boundedRedactedValue(value: unknown): unknown {
+  const redacted = SessionEvidence.redactSessionEvidenceValue(
+    value,
+    Limits.INSPECTOR_BODY_PREVIEW_CHARS,
+  );
+  let serialized: string | undefined;
+  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: RunControlRecord,
+): ProjectedRunControl {
+  const timestamps = Object.fromEntries(
+    OPTIONAL_TIMESTAMP_FIELDS.flatMap((field) => {
+      const value = control[field];
+      return typeof value === "string"
+        ? [[field, boundedRedactedString(value, Limits.COMPACT_PREVIEW_CHARS)] as const]
+        : [];
+    }),
+  ) as Partial<Pick<ProjectedRunControl, OptionalTimestampField>>;
+  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,
+    ) as RunControlStatus,
+  };
+}

package/lib/control.ts

@@ -0,0 +1,117 @@
+/**
+ * Run Control request contract.
+ * Zones: public request validation, Run/runtime target normalization, input bounds
+ * Owns pure Control validation; journaling, delivery, and lifecycle mutation stay in adapters.
+ */
+
+import * as Limits from "./limits.ts";
+
+export interface ControlRequest {
+  target: `run:${string}` | "runtime";
+  action: string;
+  input?: unknown;
+  verbose?: boolean;
+}
+
+const RUN_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const ACTION_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+const CONTROL_FIELDS = new Set(["action", "input", "target", "verbose"]);
+const REMOVED_FIELDS = new Set([
+  "body",
+  "correlation_id",
+  "from",
+  "metadata",
+  "reply_to",
+  "summary",
+  "to",
+  "type",
+]);
+
+export function isControlAction(value: string): boolean {
+  return ACTION_PATTERN.test(value);
+}
+
+export function normalizeControlAction(value: unknown): string {
+  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: unknown): unknown {
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(input);
+  } catch {
+    throw new Error("control.input must be JSON-serializable");
+  }
+  if (serialized === undefined) {
+    throw new Error("control.input must be JSON-serializable");
+  }
+  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) as unknown;
+}
+
+function normalizeTarget(value: unknown): ControlRequest["target"] {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("control.target is required");
+  }
+  const target = value.trim();
+  if (target === "runtime") return target;
+  if (!target.startsWith("run:")) {
+    throw new Error(
+      `unsupported control target: ${target}; use run:<id> or runtime`,
+    );
+  }
+  const run = target.slice(4);
+  if (!RUN_ID_PATTERN.test(run)) {
+    throw new Error(`invalid control Run target: ${target}`);
+  }
+  return `run:${run}`;
+}
+
+export function normalizeControlRequest(input: unknown): ControlRequest {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("control request must be an object");
+  }
+  const record = input as Record<string, unknown>;
+  const fields = Object.keys(record);
+  const removed = fields.filter((field) => REMOVED_FIELDS.has(field));
+  if (removed.length > 0) {
+    throw new Error(
+      `actor-message fields are removed: ${removed.sort().join(", ")}; use target, action, input, verbose`,
+    );
+  }
+  const unknown = fields.filter((field) => !CONTROL_FIELDS.has(field));
+  if (unknown.length > 0) {
+    throw new Error(`unsupported control fields: ${unknown.sort().join(", ")}`);
+  }
+  const target = normalizeTarget(record.target);
+  const action = normalizeControlAction(record.action);
+  if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
+    throw new Error("control.verbose must be a boolean");
+  }
+  const normalizedInput = record.input === undefined
+    ? undefined
+    : normalizeControlInput(record.input);
+  return {
+    target,
+    action,
+    ...(normalizedInput !== undefined ? { input: normalizedInput } : {}),
+    ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
+  };
+}

package/lib/draft-sleep.ts

@@ -498,7 +498,7 @@ export function createDraftSleepScheduler(
             ...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(),
@@ -509,7 +509,7 @@ export function createDraftSleepScheduler(
           ...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(),
@@ -552,7 +552,7 @@ export function createDraftSleepScheduler(
           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/lib/execution-sessions.ts

@@ -0,0 +1,111 @@
+/**
+ * Run-owned execution session evidence.
+ * Zones: execution manifest session discovery, canonical containment, rich turn correlation
+ * Owns reusable agent-turn loading; Trace and TUI projection stay in their adapters.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import * as SessionEvidence from "./session-evidence.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+export interface ExecutionTurnItem extends SessionEvidence.SessionEvidenceTurn {
+  commandId: string;
+  diagnostics: string[];
+  promptBytes?: number;
+  promptFile?: string;
+  recipeContext?: unknown;
+  sessionFile: string;
+  sessionTruncated: boolean;
+  stage?: string;
+}
+
+function ownedSessionPath(
+  stateDir: string,
+  sessionFile: string,
+): string | undefined {
+  if (path.isAbsolute(sessionFile)) return undefined;
+  const sessionsRoot = path.resolve(stateDir, "sessions");
+  const resolved = path.resolve(stateDir, sessionFile);
+  if (!resolved.startsWith(`${sessionsRoot}${path.sep}`)) return undefined;
+  try {
+    const canonicalRoot = fs.realpathSync(sessionsRoot);
+    const canonicalFile = fs.realpathSync(resolved);
+    return canonicalFile.startsWith(`${canonicalRoot}${path.sep}`)
+      ? canonicalFile
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function readExecutionTurns(stateDir: string): ExecutionTurnItem[] {
+  const execution = readJsonFileResilient<Record<string, unknown>>(
+    path.join(stateDir, "execution.json"),
+    {},
+  ).value;
+  const commands = Array.isArray(execution.commands)
+    ? (execution.commands as Array<Record<string, unknown>>)
+    : [];
+  const recordedFiles = new Set(
+    commands.flatMap((command) =>
+      (Array.isArray(command.session_files) ? command.session_files : []).filter(
+        (file): file is string => typeof file === "string",
+      ),
+    ),
+  );
+  let discoveredCommands: Array<Record<string, unknown>> = [];
+  try {
+    const sessionsDir = path.join(stateDir, "sessions");
+    discoveredCommands = fs
+      .readdirSync(sessionsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .flatMap((entry) => {
+        const files = fs
+          .readdirSync(path.join(sessionsDir, entry.name), {
+            withFileTypes: true,
+          })
+          .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
+          .map((file) => path.posix.join("sessions", entry.name, file.name))
+          .filter((file) => !recordedFiles.has(file));
+        return files.length > 0
+          ? [{ id: entry.name, session_files: files, stage: "subagent" }]
+          : [];
+      });
+  } catch {
+    discoveredCommands = [];
+  }
+  return [...commands, ...discoveredCommands]
+    .flatMap((command) =>
+      (Array.isArray(command.session_files) ? command.session_files : [])
+        .filter((file): file is string => typeof file === "string")
+        .flatMap((file) => {
+          const sessionPath = ownedSessionPath(stateDir, file);
+          if (!sessionPath) return [];
+          const session = SessionEvidence.readSessionEvidence(sessionPath);
+          return session.turns.map((turn) => ({
+            ...turn,
+            commandId: String(command.id ?? "unknown"),
+            diagnostics: session.diagnostics.map((item) =>
+              `${item.line === undefined ? "" : `line ${item.line}: `}${item.message}`,
+            ),
+            ...(typeof command.prompt_bytes === "number"
+              ? { promptBytes: command.prompt_bytes }
+              : {}),
+            ...(typeof command.prompt_file === "string"
+              ? { promptFile: command.prompt_file }
+              : {}),
+            ...(command.recipe_context !== undefined
+              ? { recipeContext: command.recipe_context }
+              : {}),
+            sessionFile: file,
+            sessionTruncated: session.truncated,
+            ...(typeof command.stage === "string"
+              ? { stage: command.stage }
+              : {}),
+          }));
+        }),
+    )
+    .map((turn, index) => ({ ...turn, index: index + 1 }));
+}

package/lib/file-state.ts

@@ -4,29 +4,28 @@
  * 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,
-  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: string): string {
   const absolute = resolve(path);
-  const suffix: string[] = [];
-  let existing = absolute;
+  try {
+    if (lstatSync(absolute).isSymbolicLink()) {
+      const target = realpathSync.native(absolute);
+      return process.platform === "win32" ? target.toLowerCase() : target;
+    }
+  } catch {
+    /* Materialization may race lock-key derivation; canonicalize through the parent. */
+  }
+  const suffix: string[] = [basename(absolute)];
+  let existing = dirname(absolute);
   while (!existsSync(existing)) {
     const parent = dirname(existing);
     if (parent === existing || existing === parse(existing).root) break;
@@ -47,6 +46,16 @@ export function mutationLockPath(path: string): string {
   return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
 }
 
+function isZombieProcess(pid: number): boolean {
+  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: string): "alive" | "dead" | "unknown" {
   try {
     const owner = JSON.parse(
@@ -56,6 +65,7 @@ function lockOwnerStatus(lockPath: string): "alive" | "dead" | "unknown" {
     if (!Number.isInteger(pid) || pid <= 0) return "unknown";
     try {
       process.kill(pid, 0);
+      if (Date.now() - statSync(lockPath).mtimeMs > 50 && isZombieProcess(pid)) return "dead";
       return "alive";
     } catch (error) {
       return (error as NodeJS.ErrnoException).code === "ESRCH"
@@ -68,6 +78,7 @@ function lockOwnerStatus(lockPath: string): "alive" | "dead" | "unknown" {
 }
 
 export interface FileMutationLockOptions {
+  onBeforeLockPublish?(): void;
   onBeforeReclaimRemove?(): void;
   onContention?(): void;
   onRemovalContention?(): void;
@@ -84,6 +95,28 @@ function readLockToken(lockPath: string): string | undefined {
   }
 }
 
+function prepareLockBoundary(lockPath: string, token: string, onBeforePublish?: () => void): string {
+  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: string, token: string | undefined): boolean {
+  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: string): void {
   if (!existsSync(reclaimPath)) return;
   try {
@@ -95,7 +128,7 @@ function tryReclaimRemovalBoundary(reclaimPath: string): void {
         (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
       readLockToken(reclaimPath) === inspectedToken
     ) {
-      rmSync(reclaimPath, { recursive: true, force: true });
+      removeLockBoundary(reclaimPath, inspectedToken);
     }
   } catch {
     /* another contender changed the boundary */
@@ -108,29 +141,20 @@ function withRemovalBoundary(
 ): boolean {
   const reclaimPath = `${lockPath}.reclaim`;
   const token = randomUUID();
+  const pendingPath = prepareLockBoundary(reclaimPath, token);
   try {
-    mkdirSync(reclaimPath);
+    try { renameSync(pendingPath, reclaimPath); } catch {
+      tryReclaimRemovalBoundary(reclaimPath);
+      return false;
+    }
     try {
-      writeFileSync(
-        join(reclaimPath, "owner.json"),
-        `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`,
-        "utf8",
-      );
-    } catch (error) {
-      rmSync(reclaimPath, { recursive: true, force: true });
-      throw error;
+      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 {}
   }
 }
 
@@ -153,8 +177,7 @@ function tryReclaimMutationLock(
       readLockToken(lockPath) === inspectedToken
     ) {
       options.onBeforeReclaimRemove?.();
-      rmSync(lockPath, { recursive: true, force: true });
-      reclaimed = true;
+      reclaimed = removeLockBoundary(lockPath, inspectedToken);
     }
   })) {
     return false;
@@ -170,34 +193,29 @@ export function acquireFileMutationLock(
   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;
-      }
-      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,
-        });
+        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);
       }
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
     }
+  } finally {
+    try { rmSync(pendingPath, { recursive: true, force: true }); } catch {}
   }
   let released = false;
   return () => {
@@ -207,9 +225,7 @@ export function acquireFileMutationLock(
     let removalContentionReported = false;
     while (
       !withRemovalBoundary(lockPath, () => {
-        if (readLockToken(lockPath) === token) {
-          rmSync(lockPath, { recursive: true, force: true });
-        }
+        removeLockBoundary(lockPath, token);
       })
     ) {
       if (!removalContentionReported) {
@@ -235,11 +251,11 @@ export function withFileMutationLock<T>(
   }
 }
 
-export function writeJsonAtomic(path: string, value: unknown): void {
+export function writeTextAtomic(path: string, content: string): void {
   mkdirSync(dirname(path), { recursive: true });
   const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
   try {
-    writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    writeFileSync(tempPath, content, "utf8");
     renameSync(tempPath, path);
   } catch (error) {
     try {
@@ -250,3 +266,7 @@ export function writeJsonAtomic(path: string, value: unknown): void {
     throw error;
   }
 }
+
+export function writeJsonAtomic(path: string, value: unknown): void {
+  writeTextAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}