agents-can-communicate 0.8.4 → 0.9.0

package/node_modules/@agents-can-communicate/storage-filesystem/src/safe-directory.mjs

@@ -7,11 +7,12 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
 // path is validated segment by segment against the canonical root, so a
 // symlinked ancestor cannot redirect a read or a publication - neither outside
 // the store, nor to another directory inside it.
-function invalidDirectory(message, directory, root, cause) {
+function invalidDirectory(message, directory, root, cause, resolved) {
   return new AccError(EXIT.DATA, message, {
     directory,
     root,
     ...(cause === undefined ? {} : { cause }),
+    ...(resolved === undefined ? {} : { resolved }),
   });
 }
 
@@ -40,7 +41,7 @@ async function inspectRealDirectory(directory, root, create) {
   for (let attempt = 0; ; attempt += 1) {
     let details;
     try {
-      details = await lstat(directory);
+      details = await lstat(directory, { bigint: true });
     } catch (error) {
       if (error.code !== "ENOENT") {
         throw invalidDirectory("cannot inspect managed directory", directory, root, error.message);
@@ -64,10 +65,46 @@ async function inspectRealDirectory(directory, root, create) {
   }
 }
 
-async function inspectManagedDirectory(rootPath, directoryPath, create, { afterInspect } = {}) {
+// A directory validated once is known by its identity: volume and file id, as
+// bigint because an NTFS file id does not fit a double. The same name is
+// checked again with one lstat, which follows every ancestor, so an ancestor
+// replaced by a link lands on another directory and anything but the identity
+// that was validated takes the whole walk again. What is not repeated is
+// finding the same directory under the same name: every record read walked
+// its path from the root twice, about a thousand calls a hook and 130 ms of one
+// on windows-latest. The one case the walk would still refuse is the store's
+// own directory moved elsewhere with a link left at its name - the same data in
+// another place (decided 2026-09-30). The seams bypass it: the race tests
+// exercise the walk itself.
+const VALIDATED = new Map();
+const VALIDATED_LIMIT = 512;
+
+async function validatedEarlier(key, directory) {
+  const known = VALIDATED.get(key);
+  if (known === undefined) return null;
+  const current = await lstat(directory, { bigint: true }).catch(() => null);
+  if (current !== null && current.isDirectory() && !current.isSymbolicLink()
+    && current.dev === known.dev && current.ino === known.ino) return current;
+  VALIDATED.delete(key);
+  return null;
+}
+
+function remember(key, details) {
+  if (VALIDATED.size >= VALIDATED_LIMIT) VALIDATED.clear();
+  VALIDATED.set(key, { dev: details.dev, ino: details.ino });
+}
+
+async function inspectManagedDirectory(rootPath, directoryPath, create, options = {}) {
+  const { afterInspect, realpath: resolve = realpath, platform = process.platform } = options;
   const root = absolutePath(rootPath, "managed root");
   const directory = absolutePath(directoryPath, "managed directory", root);
   const relative = relativeWithin(root, directory);
+  const key = options.afterInspect === undefined && options.realpath === undefined
+    && options.platform === undefined ? `${root}\u0000${directory}` : null;
+  if (key !== null) {
+    const known = await validatedEarlier(key, directory);
+    if (known !== null) return { directory, stat: known };
+  }
   let details = await inspectRealDirectory(root, root, create);
   const canonicalRoot = await realpath(root);
   let current = root;
@@ -78,15 +115,33 @@ async function inspectManagedDirectory(rootPath, directoryPath, create, { afterI
   for (const segment of relative.split(path.sep).filter(Boolean)) {
     current = path.join(current, segment);
     let resolved;
-    for (let attempt = 0; ; attempt += 1) {
-      details = await inspectRealDirectory(current, root, create);
-      await afterInspect?.(current);
-      // A create-mode caller uses this name next. A directory renamed away
-      // between the check and the resolution leaves realpath nothing to resolve
-      // (ENOENT), so it is checked and created again, then resolved again; every
-      // check below applies to whichever attempt settles.
-      resolved = await resolveSegment(current, create && attempt < VANISHED_RETRIES);
-      if (resolved !== null) break;
+    for (let look = 1; ; look += 1) {
+      for (let attempt = 0; ; attempt += 1) {
+        details = await inspectRealDirectory(current, root, create);
+        await afterInspect?.(current);
+        // A create-mode caller uses this name next. A directory renamed away
+        // between the check and the resolution leaves realpath nothing to
+        // resolve (ENOENT), so it is checked and created again, then resolved
+        // again; every check below applies to whichever attempt settles.
+        resolved = await resolveSegment(current, create && attempt < VANISHED_RETRIES,
+          { resolve, platform, root });
+        if (resolved !== null) break;
+      }
+      if (path.dirname(resolved) === canonicalParent) break;
+      // An answer outside the parent says where the directory lives only when
+      // that place holds this directory. On windows-latest, a lock renamed
+      // aside and back without a pause was once answered with its name under
+      // another store's root, which an earlier test had already removed (PR
+      // #243). A place holding nothing, or another directory, is asked again;
+      // a name that keeps answering that way has changed while it resolved.
+      if (await sameDirectoryAt(details, resolved, current, root)) {
+        throw invalidDirectory("managed directory escapes the canonical store root", current, root,
+          undefined, resolved);
+      }
+      if (look >= ELSEWHERE_RETRIES) {
+        throw invalidDirectory("managed parent directory changed while it resolved", current, root,
+          undefined, resolved);
+      }
     }
     // realpath answers with the name the directory carries *now*, which is not
     // always the name that was asked for: on Darwin it resolves by opening the
@@ -106,28 +161,86 @@ async function inspectManagedDirectory(rootPath, directoryPath, create, { afterI
     // swapped in under this name is not. ENOENT on the re-stat means it moved
     // again between the two calls, which cannot redirect anything: whatever
     // the caller opens through this path next fails the same way.
-    if (path.dirname(resolved) !== canonicalParent
-      || (path.basename(resolved) !== segment
-        && !await stillTheSameDirectory(details, resolved, current, root))) {
-      throw invalidDirectory("managed directory escapes the canonical store root", current, root);
+    if (path.basename(resolved) !== segment
+      && !await stillTheSameDirectory(details, resolved, current, root)) {
+      throw invalidDirectory("managed directory escapes the canonical store root", current, root,
+        undefined, resolved);
     }
     canonicalParent = resolved;
   }
+  if (key !== null) remember(key, details);
   return { directory, stat: details };
 }
 
+// Where NTFS keeps a directory deleted while something still has it open.
+const DELETED = /^(?:\\\\\?\\)?[A-Za-z]:\\\$Extend\\\$Deleted\\/i;
+
+// How many times a name answered with a directory leaving it is resolved again.
+const LEAVING_RETRIES = 3;
+
+// How many times a name answered with a place that does not hold it is looked
+// at again.
+const ELSEWHERE_RETRIES = 3;
+
 // null when the name went away and the caller may take it again.
-async function resolveSegment(current, retry) {
-  try {
-    return await realpath(current);
-  } catch (error) {
-    if (error.code === "ENOENT" && retry) return null;
-    throw error;
+//
+// Linux realpath fails ENOENT on a name removed or renamed away while it
+// resolves. Windows, measured on windows-latest, answers that window with
+// EBADF, with EPERM, or with the directory's place in $Extend\$Deleted (above):
+// the handle it took was to a directory leaving the name. The name itself may
+// already hold a new one - `stage` does, right after a sweep - so it is resolved
+// again. A directory there is the answer, no directory there is gone, and a
+// name that keeps answering that way while present fails as it always did:
+// read as gone, a directory would read as holding no records.
+async function resolveSegment(current, retry, { resolve, platform, root }) {
+  for (let attempt = 1; ; attempt += 1) {
+    let resolved = null;
+    let failure = null;
+    try {
+      resolved = await resolve(current);
+    } catch (error) {
+      failure = error;
+    }
+    const leaving = platform === "win32" && (failure === null ? DELETED.test(resolved)
+      : ["EBADF", "EPERM"].includes(failure.code));
+    if (failure === null && !leaving) return resolved;
+    if (failure?.code === "ENOENT") {
+      if (retry) return null;
+      throw failure;
+    }
+    if (!leaving) throw failure;
+    if (attempt < LEAVING_RETRIES) continue;
+    const present = await lstat(current).then(() => true, missing => missing.code !== "ENOENT");
+    // Present: refused, never read as gone - its records would read as none.
+    // Deleted directories' places, or EBADF - a handle taken to a directory
+    // leaving the name - while the name stays, is a directory moving in and out
+    // of the name; the writer lock does so for a living. It is refused as
+    // changed, which a reader takes as a reason to look again, and never as an
+    // escape: nothing left the store. EPERM can be a refusal in earnest and
+    // stays what it says.
+    if (present) {
+      if (failure !== null && failure.code !== "EBADF") throw failure;
+      throw invalidDirectory("managed parent directory changed while it resolved", current, root,
+        undefined, resolved);
+    }
+    if (retry) return null;
+    throw Object.assign(new Error(`ENOENT: ${current} left its name while it resolved`,
+      failure === null ? {} : { cause: failure }), { code: "ENOENT", syscall: "realpath", path: current });
   }
 }
 
+// Whether `resolved` holds the directory `details` describes. A place that
+// holds nothing is not where it lives.
+async function sameDirectoryAt(details, resolved, current, root) {
+  const served = await stat(resolved, { bigint: true }).then(found => found, error => {
+    if (["ENOENT", "ENOTDIR"].includes(error.code)) return null;
+    throw invalidDirectory("cannot inspect managed directory", current, root, error.message);
+  });
+  return served !== null && served.dev === details.dev && served.ino === details.ino;
+}
+
 async function stillTheSameDirectory(details, resolved, current, root) {
-  const served = await stat(resolved).then(found => found, error => {
+  const served = await stat(resolved, { bigint: true }).then(found => found, error => {
     if (error.code === "ENOENT") return null;
     throw invalidDirectory("cannot inspect managed directory", current, root, error.message);
   });
@@ -135,7 +248,8 @@ async function stillTheSameDirectory(details, resolved, current, root) {
 }
 
 // `afterInspect` is the seam the race tests use: it runs between a segment's
-// check and its resolution, the window a concurrent rename lands in.
+// check and its resolution, the window a concurrent rename lands in. `realpath`
+// and `platform` let them put a platform's answer in that window.
 export async function assertManagedDirectory(rootPath, directoryPath, options) {
   return inspectManagedDirectory(rootPath, directoryPath, false, options);
 }

package/node_modules/@agents-can-communicate/storage-filesystem/src/safe-file.mjs

@@ -4,13 +4,14 @@ import path from "node:path";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
+import { openNoFollow } from "./portable-fs.mjs";
 import { assertManagedDirectory } from "./safe-directory.mjs";
 
 function sameDirectory(left, right) {
   return left.dev === right.dev && left.ino === right.ino;
 }
 
-// The operation runs through the opened handle only after O_NOFOLLOW and the
+// The operation runs through the opened handle only after the no-follow open and the
 // before/after parent identity check agree. Replacing the pathname after that
 // point cannot redirect a read or append through the already-open descriptor.
 export async function withRegularNoFollow(filePath, root, flags, operation, openFile = open) {
@@ -18,7 +19,7 @@ export async function withRegularNoFollow(filePath, root, flags, operation, open
   const before = await assertManagedDirectory(root, parent);
   let handle;
   try {
-    handle = await openFile(filePath, flags | constants.O_NOFOLLOW);
+    handle = await openNoFollow(filePath, flags, { open: openFile });
   } catch (error) {
     if (error.code === "ENOENT") throw error;
     throw new AccError(EXIT.DATA, "cannot safely open regular file",

package/node_modules/@agents-can-communicate/storage-filesystem/src/stage-sweep.mjs

@@ -1,11 +1,11 @@
-import { rename } from "node:fs/promises";
 import path from "node:path";
 
 import { EXIT } from "@agents-can-communicate/protocol";
 
 import { encode, listDirectoryEntries, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
-import { discard, discardLeftovers, doomedName, expired, syncDirectory }
+import { discard, discardLeftovers, doomedName, expired }
   from "./doomed-directory.mjs";
+import { renameEntry, syncEntry } from "./portable-fs.mjs";
 import { reclaimRetired } from "./reclaim.mjs";
 import { ensureManagedDirectory } from "./safe-directory.mjs";
 
@@ -30,7 +30,7 @@ async function reclaimLegacy(paths, root, detached, budget, deadlineAt) {
   for (const entry of await listDirectoryEntries(paths.tmp, { root })) {
     if (spent >= budget || expired(deadlineAt)) return { spent, drained: false };
     if (!entry.isFile() || !entry.name.endsWith(".published")) continue;
-    await rename(path.join(paths.tmp, entry.name), path.join(detached, entry.name));
+    await renameEntry(path.join(paths.tmp, entry.name), path.join(detached, entry.name));
     spent += 1;
   }
   return { spent, drained: true };
@@ -69,9 +69,9 @@ export async function sweepAcceptedStages(paths,
   // the ordinary case rather than an error, and such a store is exactly the one
   // whose accepted stages are all still in tmp for the reclamation below.
   await ensureManagedDirectory(root, paths.stage);
-  await rename(paths.stage, detached);
+  await renameEntry(paths.stage, detached);
   await ensureManagedDirectory(root, paths.stage);
-  await syncDirectory(root);
+  await syncEntry(root, detached);
 
   const reclaimed = await reclaimLegacy(paths, root, detached, limit - spent, deadlineAt);
   spent += reclaimed.spent;
@@ -167,8 +167,11 @@ export async function sweepIfDue(paths,
     if (result.remaining || expired(deadlineAt)) {
       return { swept: result.swept, remaining: true };
     }
+    // Without a flush: sweptAt reads a damaged or missing marker as a pass
+    // that is due, so a crash costs one more sweep.
     await publishAtomic(markerPath(paths), encode({ sweptAt: clock.now() }),
-      { root, tmpDir: paths.tmp, stageDir: paths.stage, replace: true, deadlineAt });
+      { root, tmpDir: paths.tmp, stageDir: paths.stage, replace: true, durability: "none",
+        deadlineAt });
     return result;
   });
 }

package/node_modules/@agents-can-communicate/storage-filesystem/src/store.mjs

@@ -6,7 +6,8 @@ import { AccError, EXIT, assertPortableId, validateRecord }
 
 import { encode, listDirectoryEntries, listJsonFiles, publishAtomic, readJsonIfPresent,
   retainFile } from "./atomic-json.mjs";
-import { initialiseActiveJournal } from "./active-journal.mjs";
+import { initialiseActiveJournal, readActiveJournal } from "./active-journal.mjs";
+import { publicationPath } from "./publication-path.mjs";
 import { assertPublicationDeadline } from "./deadline.mjs";
 import { requireStoreIdentity } from "./identity.mjs";
 import { journalEntry, readJournalCeiling, readOpenJournals, rollForward, writeJournalEntry }
@@ -26,6 +27,11 @@ import { withWriterMutex } from "./writer-mutex.mjs";
 // make it easy to reintroduce separate locks and resurrect replaced sessions.
 
 const SEQUENCE_WIDTH = 16;
+// An ephemeral record describes a live session. A crash of the machine ends
+// every session it describes, and a session whose record comes back as its
+// previous version, or not at all, is recovered by its next hook. Its bytes are
+// still flushed, so no reader finds a torn record.
+const EPHEMERAL = "bytes";
 export const ZERO_CURSOR = "0".repeat(SEQUENCE_WIDTH);
 // No quarantine area. One was created in every workspace, named in the path
 // typedef, and written to by nothing: repair deliberately refuses to move a
@@ -100,7 +106,7 @@ async function nextSequence(paths, root) {
 }
 
 export async function openFilesystemStore({ root, clock, ids, workspaceId, failAt,
-  deadlineAt: storeDeadline }) {
+  deadlineAt: storeDeadline, platform = process.platform }) {
   assertPublicationDeadline(storeDeadline);
   const paths = storePaths(root);
   // The caller owns the root path, so its ancestors are created here. Inside the
@@ -109,9 +115,9 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
   await mkdir(root, { recursive: true });
   // Identity is settled before any read or write. Adopting a directory that
   // already belongs to another workspace is the failure this fails closed on.
-  await requireStoreIdentity(paths, { workspaceId, clock });
+  await requireStoreIdentity(paths, { workspaceId, clock, platform });
   for (const name of DIRECTORIES) await ensureManagedDirectory(root, paths[name]);
-  const publishOptions = { root, tmpDir: paths.tmp, clock, failAt };
+  const publishOptions = { root, tmpDir: paths.tmp, clock, failAt, platform };
   await initialiseActiveJournal(paths, publishOptions);
 
   // Any journal left behind by a crashed writer is completed before the store
@@ -251,7 +257,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       // ceiling in eventsSince has to hide.
       const publications = [
         ...events.map(event => ({
-          path: path.relative(root, eventPath(paths, event.sequence)),
+          path: publicationPath(root, eventPath(paths, event.sequence)),
           bytes: encode(event),
           replace: false,
         })),
@@ -259,13 +265,29 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
           ? stateDeletionPublication(paths, root, entry.kind, entry.id, entry.generation,
             statePath(paths, entry.kind, entry.id))
           : {
-            path: path.relative(root, statePath(paths, entry.kind, entry.id)),
+            path: publicationPath(root, statePath(paths, entry.kind, entry.id)),
             bytes: encode(stateEnvelope(entry.kind, entry.id, entry.generation, entry.record)),
             replace: true,
           })),
       ];
       if (publications.length === 0) return result;
 
+      // One record replaced and nothing appended - a session's heartbeat, every
+      // turn - needs no journal to appear at once: the rename replaces it
+      // atomically, and the bytes are flushed before and after it. The journal
+      // cost five atomic writes for it, ten flushes on Windows at 8 to 23 ms
+      // each (windows-latest). Only while no other transaction is open: an open
+      // one would later roll its own bytes over this record, and it refuses a
+      // journalled write too, which the path below keeps.
+      const [only] = staged.values();
+      if (events.length === 0 && staged.size === 1 && only.removed !== true
+        && (await readActiveJournal(paths, root)).state === "idle") {
+        assertPublicationDeadline(deadlineAt);
+        await publishAtomic(statePath(paths, only.kind, only.id), publications[0].bytes,
+          { ...publishOptions, replace: true, deadlineAt });
+        return result;
+      }
+
       // Preparation is still cancellable. The active journal's atomic
       // publication decides the write; roll-forward must then finish even if
       // this invocation expires, so its publication options carry no deadline.
@@ -372,7 +394,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       validateRecord(kind, record);
       return withWriterMutex(paths, { ...publishOptions, deadlineAt: storeDeadline }, async () => {
         await publishAtomic(ephemeralPath(kind, id), encode(record),
-          { root, tmpDir: paths.tmp, replace: true, deadlineAt: storeDeadline });
+          { root, tmpDir: paths.tmp, replace: true, durability: EPHEMERAL, deadlineAt: storeDeadline });
         // Once record bytes are accepted, finish the same logical publication.
         await markEphemeral(paths, publishOptions, kind, id, "present");
         return record;
@@ -386,7 +408,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
         validateRecord(kind, next);
         assertPublicationDeadline(deadlineAt);
         await publishAtomic(ephemeralPath(kind, id), encode(next),
-          { root, tmpDir: paths.tmp, replace: true, deadlineAt });
+          { root, tmpDir: paths.tmp, replace: true, durability: EPHEMERAL, deadlineAt });
         await markEphemeral(paths, publishOptions, kind, id, "present");
         return next;
       });

package/node_modules/@agents-can-communicate/storage-filesystem/src/writer-mutex.mjs

@@ -1,12 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { mkdir, open, rename, rm } from "node:fs/promises";
+import { lstat, mkdir, rmdir } from "node:fs/promises";
 import path from "node:path";
 import { performance } from "node:perf_hooks";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 import { encode, readJsonIfPresent } from "./atomic-json.mjs";
+import { isWindows, removeTree, renameEntry } from "./portable-fs.mjs";
 import { ensureManagedDirectory } from "./safe-directory.mjs";
 import { withRegularNoFollow } from "./safe-file.mjs";
 
@@ -16,8 +17,15 @@ const OWNER = "owner.json";
 const sleepFor = duration => new Promise(resolve => { setTimeout(resolve, duration); });
 
 // A fully prepared directory is the atomic primitive. Publishing the owner
-// with the directory means a crash can leave an unused candidate, but never an
-// ownerless canonical lock that blocks every later writer.
+// with the directory means a process that dies can leave an unused candidate,
+// but never an ownerless canonical lock that blocks every later writer.
+//
+// Nothing here is flushed. The lock guards live processes, and a crash of the
+// machine leaves none: whatever it left in the lock guards nobody. A flush cost
+// up to 5.8 s on windows-latest beside the suite (2026-10-01), three of them per
+// acquisition on POSIX, and the only thing they bought was an owner record that
+// stays readable through a crash. An unreadable one is reclaimed instead, once
+// it is older than any write takes (takeStaleOwnership).
 function defaultPidIsAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -27,16 +35,7 @@ function defaultPidIsAlive(pid) {
   }
 }
 
-async function syncDirectory(directory) {
-  const handle = await open(directory, "r");
-  try {
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-}
-
-async function prepareCandidate(paths, root, owner) {
+async function prepareCandidate(paths, root, owner, platform) {
   const identity = createHash("sha256").update(owner.token).digest("hex");
   const candidate = path.join(paths.locks, `writer.candidate-${identity}.lock`);
   await mkdir(candidate);
@@ -44,17 +43,15 @@ async function prepareCandidate(paths, root, owner) {
     await withRegularNoFollow(path.join(candidate, OWNER), root,
       constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, async handle => {
         await handle.writeFile(encode(owner));
-        await handle.sync();
       });
-    await syncDirectory(candidate);
     return candidate;
   } catch (error) {
-    await rm(candidate, { recursive: true, force: true });
+    await removeTree(candidate, { platform });
     throw error;
   }
 }
 
-async function releaseCanonical(directory, root, owner, openFile) {
+async function releaseCanonical(directory, root, owner, openFile, { platform, rename }) {
   const current = await readOwner(directory, root, openFile);
   if (current?.token !== owner.token) return;
   // Recursive removal would first unlink owner.json and briefly expose an
@@ -63,14 +60,51 @@ async function releaseCanonical(directory, root, owner, openFile) {
   const identity = createHash("sha256")
     .update(JSON.stringify([owner.pid, owner.token, owner.acquiredAt]))
     .digest("hex");
+  if (isWindows(platform)) {
+    await releaseByOwnerRecord(directory,
+      path.join(path.dirname(directory), `writer.released-${identity}.json`), { platform, rename });
+    return;
+  }
   const retired = path.join(path.dirname(directory), `writer.released-${identity}.lock`);
   try {
-    await rename(directory, retired);
+    // POSIX moves the whole lock aside; Windows released it above, by its
+    // owner record, because a reader inside holds the directory in place.
+    await renameEntry(directory, retired, { platform, rename });
   } catch (error) {
     if (["ENOENT", "EEXIST", "ENOTEMPTY"].includes(error.code)) return;
     throw error;
   }
-  await rm(retired, { recursive: true, force: true });
+  await removeTree(retired, { platform });
+}
+
+/**
+ * Release on Windows, where a directory cannot be renamed while a file inside
+ * it is open - and every waiting writer opens owner.json to see who holds the
+ * lock. Eight writers polling one lock on windows-latest held the move back
+ * until one of them gave up at the acquire timeout.
+ *
+ * A file can be renamed while it is open (Node opens with FILE_SHARE_DELETE),
+ * so the owner record leaves first, in one rename, and the lock is an empty
+ * directory from then on. On Windows an empty lock is a released one: the
+ * acquiring loop removes it with rmdir, which cannot remove a lock that has an
+ * owner in it, and so does this owner. A reader that opened the record before
+ * it left sees this owner once more and looks again.
+ *
+ * Reclaiming a dead owner still moves the whole directory. Node's rename
+ * replaces an existing file on Windows, so a late reclaimer moving owner.json
+ * could take a successor's record; a directory never lands on another one.
+ */
+async function releaseByOwnerRecord(directory, retiredOwner, { platform, rename }) {
+  try {
+    await renameEntry(path.join(directory, OWNER), retiredOwner, { platform, rename });
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  // ENOENT: a waiting writer removed it first. ENOTEMPTY: a successor is in.
+  // Busy: somebody is looking at it, and the next writer removes it instead.
+  await rmdir(directory).catch(() => null);
+  await removeTree(retiredOwner, { platform });
 }
 
 /**
@@ -93,14 +127,22 @@ async function releaseCanonical(directory, root, owner, openFile) {
  * refuses everywhere a parent has no business changing.
  */
 async function readOwner(directory, root, openFile) {
+  const file = path.join(directory, OWNER);
   try {
-    const found = await readJsonIfPresent(path.join(directory, OWNER), root, openFile);
+    const found = await readJsonIfPresent(file, root, openFile);
     return found?.value ?? null;
   } catch (error) {
     if (error instanceof AccError && error.code === EXIT.DATA
       && /parent directory changed/.test(error.message)) {
       return null;
     }
+    // Bytes a crash kept from the disk: an empty record, or zeros where NTFS
+    // kept its length. Its age is all that is left to judge it by.
+    if (error instanceof AccError && error.code === EXIT.DATA
+      && /^invalid JSON record/.test(error.message)) {
+      const stat = await lstat(file).catch(() => null);
+      return stat === null ? null : { unreadable: true, modifiedMs: stat.mtimeMs };
+    }
     throw error;
   }
 }
@@ -125,25 +167,40 @@ async function readOwner(directory, root, openFile) {
  * unrelated, and then `pidIsAlive` says yes forever. Sixty seconds is far longer
  * than any write here takes - the hook budget is five - so a holder that old is
  * not a writer that is still going.
+ *
+ * An owner record nobody can read is judged by the same age, on the clock that
+ * stamped its file. Only a crash of the machine leaves one: a live writer's
+ * record is complete before the lock carries it, and an older ACC that wrote
+ * into the lock directly takes microseconds to finish.
  */
-async function takeStaleOwnership(directory, root, owner, now, pidIsAlive) {
+async function takeStaleOwnership(directory, root, owner, now, pidIsAlive,
+  { platform, rename, deadlineAt, wallNow }) {
   if (owner === null) return false;
-  const age = Date.parse(now) - Date.parse(owner.acquiredAt);
-  if (pidIsAlive(owner.pid) && !(age > STALE_MS)) return false;
+  if (owner.unreadable === true) {
+    if (!(wallNow() - owner.modifiedMs > STALE_MS)) return false;
+  } else {
+    const age = Date.parse(now) - Date.parse(owner.acquiredAt);
+    if (pidIsAlive(owner.pid) && !(age > STALE_MS)) return false;
+  }
   // Every contender that observed this owner names the same retained target.
   // rename() moves the whole lock atomically; exactly one contender can put it
   // there. The target is deliberately left non-empty. A late contender cannot
   // rename a successor over it, so a stale pathname observation never becomes
   // permission to remove the writer that acquired the lock afterwards.
   const identity = createHash("sha256")
-    .update(JSON.stringify([owner.pid, owner.token, owner.acquiredAt]))
+    .update(JSON.stringify(owner.unreadable === true ? ["unreadable", owner.modifiedMs]
+      : [owner.pid, owner.token, owner.acquiredAt]))
     .digest("hex");
   const reclaimed = path.join(path.dirname(directory), `writer.reclaimed-${identity}.lock`);
   try {
-    await rename(directory, reclaimed);
+    await renameEntry(directory, reclaimed, { platform, rename, deadlineAt });
     return true;
   } catch (error) {
     if (["ENOENT", "EEXIST", "ENOTEMPTY"].includes(error.code)) return false;
+    // Windows refuses the move while a waiting writer has the owner record
+    // open, and it was retried up to this writer's deadline: not reclaimed
+    // this time, which the loop reports as the conflict it is.
+    if (isWindows(platform) && ["EPERM", "EACCES", "EBUSY"].includes(error.code)) return false;
     throw error;
   }
 }
@@ -152,7 +209,9 @@ export async function withWriterMutex(paths, options, operation) {
   const { root, clock, pidIsAlive = defaultPidIsAlive, uuid = randomUUID,
     attempts = Number.POSITIVE_INFINITY, waitMs = 20, openFile,
     acquireTimeoutMs = ACQUIRE_TIMEOUT_MS, monotonicNow = () => performance.now(),
-    wallNow = Date.now, deadlineAt, sleep = sleepFor } = options;
+    wallNow = Date.now, deadlineAt, sleep = sleepFor, platform = process.platform,
+    rename } = options;
+  const fsOptions = { platform, rename };
   const directory = path.join(paths.locks, "writer.lock");
   // Wall time can jump while a process waits. A monotonic absolute deadline
   // bounds all owner reads and retries, leaving half the hook's five-second
@@ -164,7 +223,7 @@ export async function withWriterMutex(paths, options, operation) {
   await ensureManagedDirectory(root, paths.locks);
   const token = uuid();
   const owner = { pid: process.pid, token, acquiredAt: clock.now() };
-  const candidate = await prepareCandidate(paths, root, owner);
+  const candidate = await prepareCandidate(paths, root, owner, platform);
   let ownsCanonical = false;
 
   try {
@@ -175,13 +234,24 @@ export async function withWriterMutex(paths, options, operation) {
         // lock left by the old mkdir-then-publish sequence. A live publisher
         // either fills it first (so rename fails) or loses its no-replace owner
         // publication after this complete candidate wins.
-        await rename(candidate, directory);
+        // Windows reports the taken name as EPERM; renameEntry turns that into
+        // the EEXIST this loop waits on, and waits out a busy source itself.
+        await renameEntry(candidate, directory,
+          { ...fsOptions, deadlineAt: wallNow() + Math.max(0, deadline - monotonicNow()) });
         ownsCanonical = true;
-        await syncDirectory(paths.locks);
       } catch (error) {
         if (!["EEXIST", "ENOTEMPTY"].includes(error.code)) throw error;
         const current = await readOwner(directory, root, openFile);
-        if (!await takeStaleOwnership(directory, root, current, clock.now(), pidIsAlive)) {
+        // POSIX rename replaces the empty lock an older ACC's mkdir-then-publish
+        // left; Windows cannot rename onto any directory, and an owner there
+        // releases by leaving an empty one. rmdir removes only an empty one, so
+        // the outcome is POSIX's: a publisher still filling it loses its
+        // no-replace owner write, and a complete lock is never touched.
+        if (current === null && isWindows(platform)
+          && await rmdir(directory).then(() => true, () => false)) continue;
+        if (!await takeStaleOwnership(directory, root, current, clock.now(), pidIsAlive,
+          { ...fsOptions, wallNow,
+            deadlineAt: wallNow() + Math.max(0, deadline - monotonicNow()) })) {
           const remaining = deadline - monotonicNow();
           if (remaining <= 0) break;
           await sleep(Math.min(waitMs, remaining));
@@ -193,11 +263,11 @@ export async function withWriterMutex(paths, options, operation) {
     }
   } finally {
     if (ownsCanonical) {
-      await releaseCanonical(directory, root, owner, openFile);
+      await releaseCanonical(directory, root, owner, openFile, fsOptions);
     } else {
       const current = await readOwner(candidate, root, openFile);
       if (current?.token === token) {
-        await rm(candidate, { recursive: true, force: true });
+        await removeTree(candidate, { platform });
       }
     }
   }