@superbee/core 0.2.0-pre.3 → 0.2.0-pre.30

package/dist/filesystem-lock.js

@@ -1,5 +1,6 @@
 import { promises as fs, realpathSync } from "node:fs";
-import { homedir, hostname, userInfo } from "node:os";
+import { homedir, hostname } from "node:os";
+import { captureFilesystemHostPolicy } from "./filesystem-host.js";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 const OWNER_FILE = "owner.json";
@@ -19,19 +20,6 @@ export class FilesystemMutationLockError extends Error {
         this.malformed = details.malformed;
     }
 }
-function runtimeOwnerKey() {
-    const uid = process.getuid?.();
-    if (uid !== undefined)
-        return `uid-${uid}`;
-    let username = "unknown";
-    try {
-        username = userInfo().username;
-    }
-    catch {
-        // Windows temp directories are already user-scoped; this is only a stable path segment.
-    }
-    return `user-${createHash("sha256").update(username).digest("hex").slice(0, 16)}`;
-}
 function canonicalExistingPath(value) {
     try {
         return realpathSync(value);
@@ -45,17 +33,13 @@ function pathContains(root, candidate) {
     return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
 /** Stable per-user runtime namespace outside `portableRoot`; refuses an impossible root bundle. */
-export function filesystemMutationLockRoot(portableRoot) {
-    // POSIX TMPDIR is process/session-scoped (notably shell vs launchd on macOS). Use the
-    // system-wide sticky directory so every same-user writer derives one lock namespace. Windows
-    // temp variables are process-scoped too, so use the per-user LocalAppData known folder instead
-    // of tmpdir(); otherwise two shells can derive different locks for the same portable target.
-    const runtimeParent = process.platform === "win32"
-        ? path.join(homedir(), "AppData", "Local")
-        : "/tmp";
+export function filesystemMutationLockRoot(portableRoot, hostPolicy) {
+    const policy = captureFilesystemHostPolicy(hostPolicy);
+    // A stable host parent keeps different process/session temp settings in one namespace.
+    const runtimeParent = policy.runtimeLockParent();
     const tempParent = canonicalExistingPath(runtimeParent);
     const homeParent = canonicalExistingPath(homedir());
-    const ownerKey = runtimeOwnerKey();
+    const ownerKey = policy.runtimeOwnerKey();
     const candidates = [
         path.join(tempParent, `agentstate-lite-mutation-locks-${ownerKey}`),
         path.join(homeParent, ".agentstate", `mutation-locks-${ownerKey}`),
@@ -78,8 +62,8 @@ function explicitFilesystemMutationLockRoot(root, portableRoot) {
     throw new FilesystemMutationLockError(`cannot place filesystem mutation locks outside portable root '${portable}'`, { lockPath: portable, owner: null, stale: false, malformed: true });
 }
 /** Runtime lock directory for one already-canonical physical target. */
-export function filesystemMutationLockPath(target, portableRoot) {
-    return filesystemMutationLockPathInRoot(target, filesystemMutationLockRoot(portableRoot));
+export function filesystemMutationLockPath(target, portableRoot, hostPolicy) {
+    return filesystemMutationLockPathInRoot(target, filesystemMutationLockRoot(portableRoot, hostPolicy));
 }
 function filesystemMutationLockPathInRoot(target, lockRoot) {
     const digest = createHash("sha256").update(path.resolve(target)).digest("hex");
@@ -113,14 +97,44 @@ export function parseFilesystemMutationLockOwner(value) {
         target: value.target,
     };
 }
-async function readOwner(lockPath) {
+/** A missing path or malformed content is `absent`; every other read failure is `unreadable`. */
+async function readOwnerRecord(lockPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(lockPath, OWNER_FILE), "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "ENOENT" || code === "ENOTDIR" ? { state: "absent" } : { state: "unreadable", error: err };
+    }
+    let owner = null;
     try {
-        return parseFilesystemMutationLockOwner(JSON.parse(await fs.readFile(path.join(lockPath, OWNER_FILE), "utf8")));
+        owner = parseFilesystemMutationLockOwner(JSON.parse(raw));
     }
     catch {
-        return null;
+        owner = null;
+    }
+    return owner === null ? { state: "absent" } : { state: "record", owner };
+}
+/**
+ * Resolve the owner record to a definitive answer, polling out an indeterminate read inside the
+ * caller's remaining budget. `EMFILE`/`ENFILE` under concurrency, and the `EBUSY`/`EACCES`/`EPERM`
+ * open transients that Windows indexing and antivirus software produce, otherwise read as "no
+ * record" and let a caller conclude that a lock it still owns has changed hands. An unreadable
+ * record never authorizes the destructive step: the caller fails closed when the budget expires.
+ */
+async function resolveOwnerRecord(lockPath, started, waitMs, pollMs) {
+    while (true) {
+        const record = await readOwnerRecord(lockPath);
+        if (record.state !== "unreadable" || Date.now() - started >= waitMs)
+            return record;
+        await delay(pollMs);
     }
 }
+async function readOwner(lockPath) {
+    const record = await readOwnerRecord(lockPath);
+    return record.state === "record" ? record.owner : null;
+}
 function processExists(pid) {
     try {
         process.kill(pid, 0);
@@ -130,6 +144,27 @@ function processExists(pid) {
         return err.code !== "ESRCH";
     }
 }
+/**
+ * Tokens of the claims held in this process, from just before each owner record is written until
+ * its release. The set lives on the global object so every copy of this module one process loads
+ * (each published bundle carries its own) shares it: the start-time test below cannot protect
+ * such a copy's claims, because a suspend or a forward clock step moves the start it computes past
+ * them.
+ */
+const HELD_TOKENS = Symbol.for("superbee.filesystem-lock.held-tokens");
+const heldTokens = (globalThis[HELD_TOKENS] ??= new Set());
+/**
+ * Whether a same-host owner is demonstrably gone. `kill(pid, 0)` answers that for another process,
+ * but for this process's own id it always answers "alive", so a record left by an earlier process
+ * that had this id (a container entry point that is PID 1 again after a restart) would hold its
+ * lock forever. Such a record is gone only when no claim in this process carries its token and it
+ * was written before this process started.
+ */
+function ownerIsGone(owner) {
+    if (owner.pid !== process.pid)
+        return !processExists(owner.pid);
+    return !heldTokens.has(owner.token) && owner.created_at_ms < Date.now() - process.uptime() * 1000;
+}
 function staleLockQuarantinePath(lockPath, owner) {
     const tokenHash = createHash("sha256").update(owner.token).digest("hex");
     return `${lockPath}.stale-${tokenHash}`;
@@ -148,10 +183,15 @@ async function pathExists(candidate) {
 /**
  * Move one demonstrably dead same-host lock aside without deleting its evidence. The destination
  * is stable for the dead owner's token and remains non-empty, so a delayed competing reclaimer
- * cannot rename a replacement live lock over it on either POSIX or Windows.
+ * cannot rename a replacement live lock over it across supported filesystems.
  */
-async function quarantineStaleLock(lockPath, owner) {
-    if (owner.hostname !== hostname() || processExists(owner.pid))
+async function quarantineStaleLock(lockPath, owner, policy) {
+    if (owner.hostname !== hostname() || !ownerIsGone(owner))
+        return false;
+    // Death was established for this owner's snapshot. If the path no longer carries that owner's
+    // record, the lock changed hands after the snapshot and the rename would move a live lock.
+    const current = await readOwner(lockPath);
+    if (current === null || current.token !== owner.token)
         return false;
     const quarantinePath = staleLockQuarantinePath(lockPath, owner);
     try {
@@ -164,7 +204,7 @@ async function quarantineStaleLock(lockPath, owner) {
             return false;
         if (await pathExists(quarantinePath))
             return false;
-        if (process.platform === "win32" && WINDOWS_DIRECTORY_CONTENTION_CODES.has(code ?? ""))
+        if (policy.isDirectoryContentionError(err))
             return false;
         throw err;
     }
@@ -185,7 +225,7 @@ export function isPrivateFilesystemMutationLockRoot(facts) {
     const unsafeMode = facts.enforcePrivateMode && (facts.mode & 0o777) !== 0o700;
     return facts.directory && !facts.symbolicLink && !wrongOwner && !unsafeMode;
 }
-async function ensurePrivateLockRoot(root) {
+async function ensurePrivateLockRoot(root, policy) {
     try {
         await fs.mkdir(root, { recursive: true, mode: 0o700 });
     }
@@ -201,7 +241,7 @@ async function ensurePrivateLockRoot(root) {
         ownerUid: stat.uid,
         expectedUid: uid,
         mode: stat.mode,
-        enforcePrivateMode: process.platform !== "win32",
+        enforcePrivateMode: policy.enforcePrivateMode,
     })) {
         throw new FilesystemMutationLockError(`refusing unsafe filesystem mutation lock root '${root}'; it must be a private directory owned by this user`, { lockPath: root, owner: null, stale: false, malformed: true });
     }
@@ -231,7 +271,7 @@ async function canonicalTargetInDirectory(directory, requestedBasename) {
             candidateStat = await fs.lstat(candidate);
         }
         catch {
-            // A sibling may disappear during the scan, or Windows may deny metadata for a protected
+            // A sibling may disappear during the scan, or the host may deny metadata for a protected
             // system entry in an otherwise-readable directory. Neither sibling can be the successfully
             // witnessed requested entry, so it contributes no alias evidence and must not block locking.
             continue;
@@ -250,10 +290,24 @@ async function canonicalTargetInDirectory(directory, requestedBasename) {
  * a lock reached through its own fold key holds the same identity by construction, but nothing
  * here re-derives that from an arbitrary `owner.json`, so it must not assert the equivalence.
  */
-function timeoutError(lockPath, owner, guarded) {
+async function timeoutError(lockPath, snapshot, guarded) {
+    // A dead-owner answer is only about the snapshot; report it as stale only while the path still
+    // carries that owner's record. Otherwise the lock was released and possibly claimed since, so
+    // diagnose the record there now, never the dead snapshot as its holder: a caller that checks the
+    // named PID (the push role's PID-reuse check, or a person running `ps`) would otherwise judge a
+    // live replacement by a process that no longer holds anything.
+    let diagnosed = snapshot;
+    let stale = false;
+    if (snapshot !== null && snapshot.hostname === hostname() && ownerIsGone(snapshot)) {
+        const current = await readOwner(lockPath);
+        if (current?.token === snapshot.token)
+            stale = true;
+        else
+            diagnosed = current;
+    }
+    const owner = diagnosed;
     const malformed = owner === null;
     const sameHost = owner?.hostname === hostname();
-    const stale = owner !== null && sameHost && !processExists(owner.pid);
     let message;
     if (malformed) {
         message =
@@ -265,9 +319,21 @@ function timeoutError(lockPath, owner, guarded) {
             `stale filesystem mutation lock '${lockPath}' belongs to absent PID ${owner.pid} on ${owner.hostname}. ` +
                 `Inspect and remove the lock, then retry.`;
     }
+    else if (!sameHost) {
+        // Another host's process ids cannot be probed from here, and a holder that crashed before this
+        // host was renamed looks exactly like a live holder elsewhere, so no retry can clear it.
+        message =
+            `filesystem mutation lock '${lockPath}' is held by PID ${owner.pid} on ${owner.hostname}, which is not this host (${hostname()}); ` +
+                `whether its holder is alive cannot be checked from here, so the lock is never reclaimed automatically. ` +
+                `A person must check it: once no process on ${owner.hostname} is mutating the target (this host may have been renamed since the lock was taken), remove the lock, then retry.`;
+    }
     else {
+        // A live process id is not proof of the holder: the holder may have exited and its id been
+        // reused, which this module cannot tell apart from a long mutation.
         message =
-            `timed out waiting for filesystem mutation lock '${lockPath}' held by PID ${owner.pid} on ${owner.hostname}; retry the mutation.`;
+            `timed out waiting for filesystem mutation lock '${lockPath}' held by PID ${owner.pid} on ${owner.hostname}; retry the mutation. ` +
+                `If it stays held, PID ${owner.pid} may no longer be the process that claimed it, because a process id is reused after its process exits: ` +
+                `remove the lock only after confirming no process is mutating the target.`;
     }
     const heldFor = owner !== null && owner.target !== guarded
         ? ` Its holder recorded '${owner.target}' for the same lock key.`
@@ -280,22 +346,21 @@ async function resolvedPortableRoot(portableRoot) {
         return undefined;
     return fs.realpath(portableRoot).catch(() => path.resolve(portableRoot));
 }
-async function selectLockRoot(options) {
+async function selectLockRoot(options, policy) {
     const portableRoot = await resolvedPortableRoot(options.portableRoot);
     const lockRoot = options.lockRoot !== undefined
         ? explicitFilesystemMutationLockRoot(options.lockRoot, portableRoot)
-        : filesystemMutationLockRoot(portableRoot);
-    await ensurePrivateLockRoot(lockRoot);
+        : filesystemMutationLockRoot(portableRoot, policy);
+    await ensurePrivateLockRoot(lockRoot, policy);
     return lockRoot;
 }
-const WINDOWS_DIRECTORY_CONTENTION_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
-async function classifyLockClaimFailure(error, lockPath) {
+async function classifyLockClaimFailure(error, lockPath, policy) {
     const code = error.code;
     if (code === "EEXIST")
         return "contention";
-    if (process.platform !== "win32" || !WINDOWS_DIRECTORY_CONTENTION_CODES.has(code ?? ""))
+    if (!policy.isDirectoryContentionError(error))
         return "terminal";
-    // Win32 may report a sharing-shaped error while another claimer creates or removes this exact
+    // A host may report a contention-shaped error while another claimer creates or removes this exact
     // directory. A witnessed path is contention. An absent path is ambiguous: permit one bounded
     // retry in case the competing directory operation just completed, but never turn a durable
     // create denial into a malformed-lock timeout. A denied probe remains terminal immediately.
@@ -306,7 +371,7 @@ async function classifyLockClaimFailure(error, lockPath) {
     catch (probeError) {
         const probeCode = probeError.code;
         return probeCode === "ENOENT" || probeCode === "ENOTDIR"
-            ? "unwitnessed-windows-sharing-error"
+            ? "unwitnessed-contention-error"
             : "terminal";
     }
 }
@@ -315,31 +380,31 @@ async function classifyLockClaimFailure(error, lockPath) {
  * owner record makes a crash leftover diagnosable, and release is token-checked so a caller can
  * never remove a lock it no longer owns. Waits up to `waitMs`, polling every `pollMs`.
  */
-async function claimLockPath(lockPath, owner, waitMs, pollMs) {
+async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
     const started = owner.created_at_ms;
-    let unwitnessedWindowsRetryUsed = false;
+    let unwitnessedRetryUsed = false;
     while (true) {
         try {
             await fs.mkdir(lockPath, { mode: 0o700 });
         }
         catch (err) {
-            const failure = await classifyLockClaimFailure(err, lockPath);
+            const failure = await classifyLockClaimFailure(err, lockPath, policy);
             if (failure === "terminal")
                 throw err;
-            if (failure === "unwitnessed-windows-sharing-error") {
-                if (unwitnessedWindowsRetryUsed)
+            if (failure === "unwitnessed-contention-error") {
+                if (unwitnessedRetryUsed)
                     throw err;
-                unwitnessedWindowsRetryUsed = true;
+                unwitnessedRetryUsed = true;
                 // This is one immediate re-attempt, not a wait. It is permitted even with waitMs: 0 so
                 // the next result can distinguish a one-shot sharing race from a durable create denial.
                 continue;
             }
             else {
-                unwitnessedWindowsRetryUsed = false;
+                unwitnessedRetryUsed = false;
             }
             let existingOwner = await readOwner(lockPath);
             if (existingOwner !== null) {
-                if (await quarantineStaleLock(lockPath, existingOwner))
+                if (await quarantineStaleLock(lockPath, existingOwner, policy))
                     continue;
                 // A failed quarantine attempt is non-progress: another reclaimer may have moved the stale
                 // lock and installed a live replacement while this caller was delayed in rename. Diagnose
@@ -347,12 +412,18 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs) {
                 existingOwner = await readOwner(lockPath);
             }
             if (Date.now() - started >= waitMs)
-                throw timeoutError(lockPath, existingOwner, owner.target);
+                throw await timeoutError(lockPath, existingOwner, owner.target);
             await delay(pollMs);
             continue;
         }
-        // The claim is ours now. Owner initialization and rollback failures are not claim
-        // contention—even when Windows reports a sharing-shaped errno—and must propagate unchanged.
+        // The directory this claim made, to recognize it later even if the owner record never lands.
+        const claimed = await fs.lstat(lockPath, { bigint: true }).catch(() => null);
+        // The claim is ours now, unless this claimer was suspended long enough for the owner-less
+        // directory to be removed as orphaned and claimed again. Owner initialization and rollback
+        // failures are not claim contention, even when the host reports a contention-shaped error, and
+        // must propagate unchanged. A lost claim is contention: a record this claim never wrote
+        // (EEXIST), or no directory to write into (ENOENT, ENOTDIR).
+        heldTokens.add(owner.token);
         try {
             await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}\n`, {
                 encoding: "utf8",
@@ -361,22 +432,172 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs) {
             });
         }
         catch (err) {
-            await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+            const code = err.code;
+            // `wx` fails with EEXIST only when another claimer's owner.json was already there, possibly
+            // opened but not yet written. The directory is that claimer's now: never roll it back.
+            // A lost claim re-enters the loop, whose next `mkdir` either claims or reaches the timeout check.
+            if (code === "EEXIST") {
+                heldTokens.delete(owner.token);
+                continue;
+            }
+            await rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy).catch(() => { });
+            heldTokens.delete(owner.token);
+            if (code === "ENOENT" || code === "ENOTDIR")
+                continue;
             throw err;
         }
-        return async () => {
-            const current = await readOwner(lockPath);
-            if (current?.token !== owner.token) {
-                throw new FilesystemMutationLockError(`refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`, { lockPath, owner: current, stale: false, malformed: current === null });
-            }
-            try {
-                await fs.rm(lockPath, { recursive: true, force: false });
+        // One release in flight per claim: a concurrent second invocation shares the first outcome
+        // instead of racing it, so two removers can never act on one claim. A later invocation
+        // re-verifies the record and refuses, as it always did.
+        let inFlight;
+        return () => {
+            if (inFlight)
+                return inFlight;
+            inFlight = (async () => {
+                // One budget spans ownership resolution and removal, so the worst-case hold stays the
+                // mutation plus waitMs however the two steps divide it.
+                const started = Date.now();
+                const current = await resolveOwnerRecord(lockPath, started, waitMs, pollMs);
+                if (current.state === "unreadable")
+                    throw unreadableOwnerRefusal(lockPath, current.error);
+                if (current.state !== "record" || current.owner.token !== owner.token) {
+                    throw changedOwnerRefusal(lockPath, current.state === "record" ? current.owner : null);
+                }
+                await removeReleasedLock(lockPath, owner, started, waitMs, pollMs, policy);
+                heldTokens.delete(owner.token);
+            })();
+            return inFlight.finally(() => {
+                inFlight = undefined;
+            });
+        };
+    }
+}
+/**
+ * Undo a claim whose owner record could not be written, removing the lock directory only when it
+ * is provably this claim's: a compare-and-release. The directory is this claim's when it carries
+ * this claim's owner record, or when it carries no record and is still the very directory this
+ * claim made (same device, inode and birth time). Any other record is another process's lock, and
+ * a directory that is not the one this claim made may be another claim in progress; both are left
+ * alone. So is a record this process still cannot read once the wait budget is spent (a transient
+ * read failure is polled out first), and a host that reports no birth time (Linux on NFS, say), where the
+ * directory cannot be told from a successor that reused its inode: an owner-less lock left behind
+ * is reported as orphaned once the claim grace passes, while a deleted live lock breaks exclusion.
+ */
+async function rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy) {
+    const started = Date.now();
+    const record = await resolveOwnerRecord(lockPath, started, waitMs, pollMs);
+    if (record.state === "record") {
+        if (record.owner.token === owner.token)
+            await removeReleasedLock(lockPath, owner, started, waitMs, pollMs, policy);
+        return;
+    }
+    if (record.state === "unreadable" || !(await isClaimedDirectory(lockPath, claimed)))
+        return;
+    // Move exactly the verified directory aside, under a name only this claim can produce, then remove it.
+    const remnant = releasedLockRemnantPath(lockPath, owner);
+    await fs.rename(lockPath, remnant);
+    await fs.rm(remnant, { recursive: true, force: true });
+}
+async function isClaimedDirectory(lockPath, claimed) {
+    if (claimed === null || claimed.birthtimeNs <= 0n)
+        return false;
+    const current = await fs.lstat(lockPath, { bigint: true }).catch(() => null);
+    return current !== null && current.isDirectory() && current.dev === claimed.dev && current.ino === claimed.ino && current.birthtimeNs === claimed.birthtimeNs;
+}
+function changedOwnerRefusal(lockPath, current) {
+    return new FilesystemMutationLockError(`refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`, { lockPath, owner: current, stale: false, malformed: current === null });
+}
+/**
+ * A record this process could never read is not a record that changed; say which one happened.
+ * `malformed` stays true because the outcome for a consumer is the same one it already handled,
+ * no usable owner record, and the message carries the distinction the flag cannot.
+ */
+function unreadableOwnerRefusal(lockPath, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new FilesystemMutationLockError(`refusing to release filesystem mutation lock '${lockPath}' because its owner record could not be read within the wait budget (${message}); the mutation may have completed, inspect the lock before retrying.`, { lockPath, owner: null, stale: false, malformed: true });
+}
+/** Token-derived sibling name that only this claim can produce; a competitor can never claim it. */
+function releasedLockRemnantPath(lockPath, owner) {
+    const tokenHash = createHash("sha256").update(owner.token).digest("hex");
+    return `${lockPath}.released-${tokenHash}`;
+}
+function removalFailure(inspectPath, owner, err, attempts, detail) {
+    const message = err instanceof Error ? err.message : String(err);
+    const suffix = attempts > 1 ? ` after ${attempts} bounded attempts` : "";
+    return new FilesystemMutationLockError(`mutation completed but ${detail}${suffix} (${message}); inspect the lock before retrying.`, { lockPath: inspectPath, owner, stale: false, malformed: false });
+}
+/**
+ * Release a lock directory whose owner record was just verified as this caller's, in two steps
+ * that keep the destructive action fenced to this claim.
+ *
+ * Step one renames the directory to a token-derived sibling. Rename is atomic and moves exactly
+ * the directory whose record was verified; the lock key is free the instant it succeeds, and a
+ * competitor's later claim lands on a fresh directory that step two never names. Step two removes
+ * the renamed remnant, which only this claim can produce. What remains is the check-then-act gap
+ * between a record read and the next rename syscall, reachable only through an external actor
+ * that removes the verified directory and a completed competitor claim inside that gap: the same
+ * class the stale-lock quarantine rename accepts.
+ *
+ * A host may report a contention-shaped error while another claimer still holds a handle inside
+ * the directory: Windows unlink through older libuv-backed Node releases marks a file delete-on-close, so a
+ * competitor's poll of `owner.json` briefly blocks both the directory rename and the removal of
+ * its unlinked record. Retry only what the host policy classifies as directory contention, inside
+ * the budget `started` at release entry and bounded by the claim's `waitMs`, polling every
+ * `pollMs`, so the worst-case hold is the mutation plus `waitMs`. The default supported policy
+ * classifies nothing, so its release stays single-shot. Before each rename retry the record is
+ * re-read: rename never removes the record, so anything but this claim's own record means the
+ * directory changed hands and the release refuses, unless the directory itself is gone. A record
+ * this process cannot read is neither, and is polled out rather than acted on. A directory gone
+ * between attempts is the requested outcome, and so is an absent remnant, whose token-derived
+ * name no competitor can produce.
+ */
+async function removeReleasedLock(lockPath, owner, started, waitMs, pollMs, policy) {
+    const remnant = releasedLockRemnantPath(lockPath, owner);
+    let attempts = 0;
+    while (true) {
+        try {
+            await fs.rename(lockPath, remnant);
+            break;
+        }
+        catch (err) {
+            attempts += 1;
+            if (attempts > 1 && err.code === "ENOENT")
+                return;
+            if (!policy.isDirectoryContentionError(err) || Date.now() - started >= waitMs) {
+                throw removalFailure(lockPath, owner, err, attempts, `filesystem lock '${lockPath}' could not be removed`);
             }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                throw new FilesystemMutationLockError(`mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`, { lockPath, owner: current, stale: false, malformed: false });
+        }
+        await delay(pollMs);
+        // Only a definitive record authorizes another rename, so an indeterminate read delays this
+        // claim's own cleanup instead of ever pointing the rename at a directory it did not verify.
+        const current = await resolveOwnerRecord(lockPath, started, waitMs, pollMs);
+        if (current.state === "record" && current.owner.token === owner.token)
+            continue;
+        if (current.state === "unreadable")
+            throw unreadableOwnerRefusal(lockPath, current.error);
+        // Rename never removes the record, so a record-less directory here is a competitor's claim in
+        // progress, never this caller's leftover; only an absent directory means already released.
+        if (current.state === "absent" && !(await pathExists(lockPath)))
+            return;
+        throw changedOwnerRefusal(lockPath, current.state === "record" ? current.owner : null);
+    }
+    attempts = 0;
+    while (true) {
+        try {
+            await fs.rm(remnant, { recursive: true, force: false });
+            return;
+        }
+        catch (err) {
+            attempts += 1;
+            // No competitor can produce this token-derived name, so an absent remnant on any attempt,
+            // the first included, means the release already reached its requested end state.
+            if (err.code === "ENOENT")
+                return;
+            if (!policy.isDirectoryContentionError(err) || Date.now() - started >= waitMs) {
+                throw removalFailure(remnant, owner, err, attempts, `filesystem lock '${lockPath}' was released yet its remnant '${remnant}' could not be removed`);
             }
-        };
+        }
+        await delay(pollMs);
     }
 }
 function newOwner(target) {
@@ -398,13 +619,14 @@ function newOwner(target) {
  * fail-closed.
  */
 export async function acquireFilesystemMutationLock(target, options = {}) {
+    const policy = captureFilesystemHostPolicy(options.hostPolicy);
     const waitMs = positiveOption(options.waitMs, DEFAULT_WAIT_MS, "waitMs");
     const pollMs = positiveOption(options.pollMs, DEFAULT_POLL_MS, "pollMs");
     const targetResolved = path.resolve(target);
     const targetDir = path.dirname(targetResolved);
     const owner = newOwner(targetResolved);
-    // An existing Windows drive root (for example C:\) can reject even a recursive mkdir with
-    // EPERM. Resolve first and create only when the parent is genuinely absent. This preserves the
+    // Existing filesystem roots can reject even a recursive mkdir. Resolve first and create
+    // only when the parent is genuinely absent. This preserves the
     // create-on-demand behavior without mutating an already-existing filesystem root.
     let canonicalDir;
     try {
@@ -419,9 +641,9 @@ export async function acquireFilesystemMutationLock(target, options = {}) {
     // Two callers may spell the same bundle through real and symlinked parent paths. Canonicalize
     // the now-existing parent so both claim the same runtime lock for the physical target.
     const targetCanonical = await canonicalTargetInDirectory(canonicalDir, path.basename(targetResolved));
-    const lockRoot = await selectLockRoot(options);
+    const lockRoot = await selectLockRoot(options, policy);
     const lockPath = filesystemMutationLockPathInRoot(targetCanonical, lockRoot);
-    return claimLockPath(lockPath, { ...owner, target: targetCanonical }, waitMs, pollMs);
+    return claimLockPath(lockPath, { ...owner, target: targetCanonical }, waitMs, pollMs, policy);
 }
 const IDENTITY_KEY_SHAPE = /^[0-9a-f]{64}$/;
 function assertIdentityKey(key) {
@@ -429,9 +651,9 @@ function assertIdentityKey(key) {
         throw new TypeError("identity key must be a lowercase hex sha256 digest");
 }
 /** @internal Runtime lock directory for one identity key; the key is the whole path component. */
-export function filesystemIdentityLockPath(key, portableRoot) {
+export function filesystemIdentityLockPath(key, portableRoot, hostPolicy) {
     assertIdentityKey(key);
-    return path.join(filesystemMutationLockRoot(portableRoot), `${key}.lock`);
+    return path.join(filesystemMutationLockRoot(portableRoot, hostPolicy), `${key}.lock`);
 }
 /**
  * @internal Claim the same-user cross-process lock for an identity key that the caller derived
@@ -441,11 +663,12 @@ export function filesystemIdentityLockPath(key, portableRoot) {
  */
 export async function acquireFilesystemIdentityLock(key, identity, options = {}) {
     assertIdentityKey(key);
+    const policy = captureFilesystemHostPolicy(options.hostPolicy);
     const waitMs = positiveOption(options.waitMs, DEFAULT_WAIT_MS, "waitMs");
     const pollMs = positiveOption(options.pollMs, DEFAULT_POLL_MS, "pollMs");
     const owner = newOwner(identity);
-    const lockRoot = await selectLockRoot(options);
-    return claimLockPath(path.join(lockRoot, `${key}.lock`), owner, waitMs, pollMs);
+    const lockRoot = await selectLockRoot(options, policy);
+    return claimLockPath(path.join(lockRoot, `${key}.lock`), owner, waitMs, pollMs, policy);
 }
 /** Run `fn` while holding the same-user cross-process mutation lock for `target`. */
 export async function withFilesystemMutationLock(target, fn, options = {}) {
@@ -457,4 +680,27 @@ export async function withFilesystemMutationLock(target, fn, options = {}) {
         await release();
     }
 }
+/**
+ * How long ago a lock directory last changed (its owner record written or removed), or null when
+ * it is gone. Lets a caller tell a claim or release in progress from an orphaned lock.
+ */
+export async function filesystemLockAgeMs(lockPath) {
+    try {
+        const info = await fs.stat(lockPath);
+        return Math.max(0, Date.now() - info.mtimeMs);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the lock at `lockPath` still carries the owner record with `token`: a definite answer
+ * when a record or its absence was read, `null` when this process could not read it.
+ */
+export async function filesystemLockHeldBy(lockPath, token) {
+    const record = await readOwnerRecord(lockPath);
+    if (record.state === "unreadable")
+        return null;
+    return record.state === "record" && record.owner.token === token;
+}
 //# sourceMappingURL=filesystem-lock.js.map