@openclaw/fs-safe 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.4.5 - 2026-07-20
+
+### Highlights
+
+- Preserve sidecar-lock ownership across filesystem identity drift without weakening legacy stale-lock checks.
+
+### Security and Correctness
+
+- Give new sidecar locks an internal random ownership token outside the parsed JSON payload so release remains ownership-checked when virtual filesystems report different descriptor and pathname identities, while legacy locks retain the stricter identity-plus-content check.
+
+## 0.4.4 - 2026-07-18
+
+### Security and Correctness
+
+- Restore opt-in stale sidecar recovery with an exclusive reclaim guard that serializes snapshot verification and unlink, preserving dead-owner recovery without allowing a competing reclaimer to delete a fresh replacement lock.
+
 ## 0.4.3 - 2026-07-18
 
 ### Compatibility

package/README.md

@@ -283,9 +283,10 @@ the common merge-into-defaults case. Standalone helpers use options bags
 because they do not carry a bound root and often need multiple authority, path,
 and policy knobs.
 
-Sidecar locks fail closed on stale holders. The legacy `remove-if-unchanged`
-option remains accepted for source compatibility, but it no longer unlinks a
-third-party stale lock during acquisition; see the [file lock docs](docs/sidecar-lock.md).
+Sidecar locks fail closed on stale holders by default. Opt-in `remove-if-unchanged`
+recovery requires caller approval and serializes snapshot verification and unlink
+with an exclusive reclaim guard so a replacement lock cannot be deleted; see the
+[file lock docs](docs/sidecar-lock.md).
 
 Use `fileStore()` for cache/blob/media-style directories where callers
 need safe relative paths, size limits, atomic replacement, stream writes, and

package/dist/sidecar-lock-reclaim.d.ts

@@ -0,0 +1,32 @@
+import type { Stats } from "node:fs";
+export type SidecarLockStaleSnapshot = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    raw: string;
+    payload: Record<string, unknown> | null;
+};
+export type SidecarLockSnapshot = {
+    raw?: string;
+    payload: Record<string, unknown> | null;
+    stat?: Stats;
+    ownershipToken?: string;
+};
+export declare function readSidecarLockOwnershipToken(raw: string): string | undefined;
+export declare function serializeSidecarLockPayload(payload: Record<string, unknown>): {
+    raw: string;
+    ownershipToken: string;
+};
+export declare function readSidecarLockSnapshot(lockPath: string): Promise<SidecarLockSnapshot | null>;
+export declare function sidecarLockSnapshotMatches(current: SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
+export declare function removeSidecarLockIfUnchanged(lockPath: string, observed: SidecarLockSnapshot | null): Promise<boolean>;
+export declare function sidecarLockSnapshotStillPresent(lockPath: string, observed: SidecarLockSnapshot | null): Promise<boolean>;
+export declare function sidecarReclaimGuardExists(pathname: string): Promise<boolean>;
+export declare function tryAcquireSidecarReclaimGuard(reclaimGuards: Set<string>, reclaimGuardPath: string): Promise<boolean>;
+export declare function releaseSidecarReclaimGuard(reclaimGuards: Set<string>, reclaimGuardPath: string): Promise<void>;
+export declare function removeStaleSidecarLockIfAllowed(params: {
+    lockPath: string;
+    normalizedTargetPath: string;
+    snapshot: SidecarLockSnapshot;
+    shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
+}): Promise<"removed" | "changed" | "not-approved">;
+//# sourceMappingURL=sidecar-lock-reclaim.d.ts.map

package/dist/sidecar-lock-reclaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAWrC,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAYF,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;CACxB,CAMA;AAED,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAoBrC;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAkBT;AAED,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GACnC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GACnC,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUlF;AAED,wBAAsB,6BAA6B,CACjD,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5F,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,GAAG,cAAc,CAAC,CA6BlD"}

package/dist/sidecar-lock-reclaim.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import { sameFileIdentity } from "./file-identity.js";
+const SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES = 16;
+const SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS = SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES * 8;
+const SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX = "\t".repeat(8);
+const SIDECAR_LOCK_OWNERSHIP_TOKEN_PATTERN = new RegExp(`\\n(${SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX}[ \\t]{${SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS}})\\n$`);
+function createSidecarLockOwnershipToken() {
+    let token = SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX;
+    for (const byte of randomBytes(SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES)) {
+        for (let bit = 7; bit >= 0; bit -= 1) {
+            token += byte & (1 << bit) ? "\t" : " ";
+        }
+    }
+    return token;
+}
+export function readSidecarLockOwnershipToken(raw) {
+    return SIDECAR_LOCK_OWNERSHIP_TOKEN_PATTERN.exec(raw)?.[1];
+}
+export function serializeSidecarLockPayload(payload) {
+    const ownershipToken = createSidecarLockOwnershipToken();
+    return {
+        raw: `${JSON.stringify(payload, null, 2)}\n${ownershipToken}\n`,
+        ownershipToken,
+    };
+}
+export async function readSidecarLockSnapshot(lockPath) {
+    try {
+        const stat = await fs.lstat(lockPath);
+        const raw = await fs.readFile(lockPath, "utf8");
+        try {
+            const parsed = JSON.parse(raw);
+            const payload = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : null;
+            return { raw, payload, stat };
+        }
+        catch {
+            return { raw, payload: null, stat };
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+export function sidecarLockSnapshotMatches(current, observed) {
+    if (observed.ownershipToken !== undefined) {
+        return (current.stat?.isFile() === true &&
+            current.raw !== undefined &&
+            observed.raw !== undefined &&
+            readSidecarLockOwnershipToken(current.raw) === observed.ownershipToken &&
+            readSidecarLockOwnershipToken(observed.raw) === observed.ownershipToken &&
+            current.raw === observed.raw);
+    }
+    if (observed.stat && current.stat && !sameFileIdentity(observed.stat, current.stat)) {
+        return false;
+    }
+    if (observed.raw !== undefined) {
+        return current.raw === observed.raw;
+    }
+    return observed.stat !== undefined && current.stat !== undefined;
+}
+export async function removeSidecarLockIfUnchanged(lockPath, observed) {
+    const current = await readSidecarLockSnapshot(lockPath);
+    if (!current || !observed || !sidecarLockSnapshotMatches(current, observed)) {
+        return false;
+    }
+    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+    return true;
+}
+export async function sidecarLockSnapshotStillPresent(lockPath, observed) {
+    const current = await readSidecarLockSnapshot(lockPath);
+    return !!current && !!observed && sidecarLockSnapshotMatches(current, observed);
+}
+export async function sidecarReclaimGuardExists(pathname) {
+    try {
+        await fs.lstat(pathname);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return false;
+        }
+        throw err;
+    }
+}
+export async function tryAcquireSidecarReclaimGuard(reclaimGuards, reclaimGuardPath) {
+    try {
+        await fs.mkdir(reclaimGuardPath);
+        reclaimGuards.add(reclaimGuardPath);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            return false;
+        }
+        throw err;
+    }
+}
+export async function releaseSidecarReclaimGuard(reclaimGuards, reclaimGuardPath) {
+    await fs.rmdir(reclaimGuardPath);
+    reclaimGuards.delete(reclaimGuardPath);
+}
+export async function removeStaleSidecarLockIfAllowed(params) {
+    if (!params.shouldRemoveStaleLock || params.snapshot.raw === undefined) {
+        return "not-approved";
+    }
+    if (!(await sidecarLockSnapshotStillPresent(params.lockPath, params.snapshot))) {
+        return "changed";
+    }
+    if (!(await params.shouldRemoveStaleLock({
+        lockPath: params.lockPath,
+        normalizedTargetPath: params.normalizedTargetPath,
+        raw: params.snapshot.raw,
+        payload: params.snapshot.payload,
+    }))) {
+        return "not-approved";
+    }
+    if (!(await sidecarLockSnapshotStillPresent(params.lockPath, params.snapshot))) {
+        return "changed";
+    }
+    try {
+        await fs.rm(params.lockPath);
+        return "removed";
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return "changed";
+        }
+        throw err;
+    }
+}

package/dist/sidecar-lock.d.ts

@@ -1,3 +1,5 @@
+import { type SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
+export type { SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
 export type SidecarLockRetryOptions = {
     retries?: number;
     factor?: number;
@@ -5,16 +7,7 @@ export type SidecarLockRetryOptions = {
     maxTimeout?: number;
     randomize?: boolean;
 };
-export type SidecarLockStaleRecovery = "fail-closed"
-/** @deprecated Stale locks now always fail closed. */
- | "remove-if-unchanged";
-/** @deprecated Stale-removal callbacks are retained for source compatibility but are not invoked. */
-export type SidecarLockStaleSnapshot = {
-    lockPath: string;
-    normalizedTargetPath: string;
-    raw: string;
-    payload: Record<string, unknown> | null;
-};
+export type SidecarLockStaleRecovery = "fail-closed" | "remove-if-unchanged";
 export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     targetPath: string;
     lockPath?: string;
@@ -32,7 +25,6 @@ export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>>
         nowMs: number;
         heldByThisProcess: boolean;
     }) => boolean | Promise<boolean>;
-    /** @deprecated Stale locks now always fail closed; this callback is not invoked. */
     shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
     metadata?: Record<string, unknown>;
 };

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAChC,aAAa;AACf,sDAAsD;GACpD,qBAAqB,CAAC;AAE1B,qGAAqG;AACrG,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,oFAAoF;IACpF,qBAAqB,CAAC,EAAE,CACtB,QAAQ,EAAE,wBAAwB,KAC/B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AA0MF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAW3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAwHL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBASW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock.js

@@ -2,6 +2,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { sameFileIdentity } from "./file-identity.js";
+import { readSidecarLockSnapshot, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotMatches, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 function getGlobalManagers() {
     const globalWithState = globalThis;
@@ -14,70 +15,62 @@ function resolveManagerState(key) {
     const managers = getGlobalManagers();
     let state = managers.get(key);
     if (!state) {
-        state = { cleanupRegistered: false, held: new Map() };
+        state = {
+            cleanupRegistered: false,
+            held: new Map(),
+            reclaimCleanupRegistered: false,
+            reclaimGuards: new Set(),
+        };
         managers.set(key, state);
     }
+    else {
+        // The global manager symbol is shared across package copies and hot reloads.
+        // Backfill state created by fs-safe versions that predate reclaim guards.
+        state.reclaimCleanupRegistered ??= false;
+        state.reclaimGuards ??= new Set();
+    }
     return state;
 }
-async function readLockSnapshot(lockPath) {
+function snapshotMatchesSync(lockPath, observed) {
+    let fd;
     try {
-        const stat = await fs.lstat(lockPath);
-        const raw = await fs.readFile(lockPath, "utf8");
-        try {
-            const parsed = JSON.parse(raw);
-            const payload = parsed && typeof parsed === "object" && !Array.isArray(parsed)
-                ? parsed
-                : null;
-            return { raw, payload, stat };
+        const beforeStat = fsSync.lstatSync(lockPath);
+        if (!beforeStat.isFile()) {
+            return false;
         }
-        catch {
-            return { raw, payload: null, stat };
+        const openFlags = fsSync.constants.O_RDONLY |
+            (process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
+                ? fsSync.constants.O_NOFOLLOW
+                : 0) |
+            (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0);
+        fd = fsSync.openSync(lockPath, openFlags);
+        const openedStat = fsSync.fstatSync(fd);
+        if (!openedStat.isFile()) {
+            return false;
         }
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            return null;
+        if (observed.raw !== undefined && openedStat.size !== Buffer.byteLength(observed.raw)) {
+            return false;
         }
-        throw err;
-    }
-}
-function snapshotMatches(current, observed) {
-    if (observed.stat && current.stat && !sameFileIdentity(observed.stat, current.stat)) {
-        return false;
-    }
-    if (observed.raw !== undefined) {
-        return current.raw === observed.raw;
-    }
-    return observed.stat !== undefined && current.stat !== undefined;
-}
-async function removeLockIfUnchanged(lockPath, observed) {
-    const current = await readLockSnapshot(lockPath);
-    if (!current || !observed) {
-        return false;
-    }
-    if (!snapshotMatches(current, observed)) {
-        // The lock changed after we decided it was stale. Leave the fresh holder's
-        // file alone; deleting by path here would break mutual exclusion.
-        return false;
-    }
-    await fs.rm(lockPath, { force: true }).catch(() => undefined);
-    return true;
-}
-async function lockSnapshotStillPresent(lockPath, observed) {
-    const current = await readLockSnapshot(lockPath);
-    return !!current && !!observed && snapshotMatches(current, observed);
-}
-function snapshotMatchesSync(lockPath, observed) {
-    try {
-        const stat = fsSync.lstatSync(lockPath);
-        if (observed.stat && !sameFileIdentity(observed.stat, stat)) {
+        const raw = fsSync.readFileSync(fd, "utf8");
+        const afterStat = fsSync.lstatSync(lockPath);
+        if (!afterStat.isFile() || !sameFileIdentity(beforeStat, afterStat)) {
             return false;
         }
-        return observed.raw === undefined || fsSync.readFileSync(lockPath, "utf8") === observed.raw;
+        return sidecarLockSnapshotMatches({ raw, payload: null, stat: afterStat }, observed);
     }
     catch {
         return false;
     }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // Best-effort process-exit cleanup.
+            }
+        }
+    }
 }
 async function resolveNormalizedTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
@@ -112,6 +105,17 @@ async function defaultShouldReclaim(params) {
         return true;
     }
 }
+function releaseAllReclaimGuardsSync(state) {
+    for (const reclaimGuardPath of state.reclaimGuards) {
+        try {
+            fsSync.rmdirSync(reclaimGuardPath);
+            state.reclaimGuards.delete(reclaimGuardPath);
+        }
+        catch {
+            // Best-effort process-exit cleanup. A surviving guard fails closed.
+        }
+    }
+}
 function releaseAllLocksSync(state) {
     for (const [normalizedTargetPath, held] of state.held) {
         void held.handle.close().catch(() => undefined);
@@ -125,6 +129,7 @@ function releaseAllLocksSync(state) {
         }
         state.held.delete(normalizedTargetPath);
     }
+    releaseAllReclaimGuardsSync(state);
 }
 async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
     const current = state.held.get(normalizedTargetPath);
@@ -147,7 +152,7 @@ async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
     state.held.delete(normalizedTargetPath);
     held.releasePromise = (async () => {
         await held.handle.close().catch(() => undefined);
-        await removeLockIfUnchanged(held.lockPath, held.snapshot);
+        await removeSidecarLockIfUnchanged(held.lockPath, held.snapshot);
     })();
     try {
         await held.releasePromise;
@@ -160,11 +165,16 @@ async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
 export function createSidecarLockManager(key) {
     const state = resolveManagerState(key);
     function ensureExitCleanupRegistered() {
-        if (state.cleanupRegistered) {
+        if (!state.cleanupRegistered) {
+            state.cleanupRegistered = true;
+            state.reclaimCleanupRegistered = true;
+            process.on("exit", () => releaseAllLocksSync(state));
             return;
         }
-        state.cleanupRegistered = true;
-        process.on("exit", () => releaseAllLocksSync(state));
+        if (!state.reclaimCleanupRegistered) {
+            state.reclaimCleanupRegistered = true;
+            process.on("exit", () => releaseAllReclaimGuardsSync(state));
+        }
     }
     async function acquire(options) {
         ensureExitCleanupRegistered();
@@ -184,99 +194,146 @@ export function createSidecarLockManager(key) {
         const startedAt = Date.now();
         const retry = options.retry ?? {};
         const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
+        const reclaimGuardPath = `${lockPath}.reclaim`;
+        let ownsReclaimGuard = false;
         let attempt = 0;
-        while (true) {
-            let handle = null;
-            try {
-                handle = await fs.open(lockPath, "wx");
-                const payload = await options.payload();
-                const raw = `${JSON.stringify(payload, null, 2)}\n`;
-                await handle.writeFile(raw, "utf8");
-                const snapshot = { raw, payload, stat: await handle.stat() };
-                const createdHeld = {
-                    count: 1,
-                    handle,
-                    lockPath,
-                    snapshot,
-                    acquiredAt: Date.now(),
-                    metadata: options.metadata ?? {},
-                };
-                state.held.set(normalizedTargetPath, createdHeld);
-                const release = () => releaseHeldLock(state, normalizedTargetPath, createdHeld).then(() => undefined);
-                return {
+        const waitForRetry = async () => {
+            const elapsed = Date.now() - startedAt;
+            if ((options.timeoutMs !== undefined &&
+                options.timeoutMs !== Number.POSITIVE_INFINITY &&
+                elapsed >= options.timeoutMs) ||
+                (maxRetries !== undefined && attempt >= maxRetries)) {
+                throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+                    code: "file_lock_timeout",
                     lockPath,
                     normalizedTargetPath,
-                    release,
-                    [Symbol.asyncDispose]: release,
-                };
+                });
             }
-            catch (err) {
-                if (handle) {
-                    const failedSnapshot = { payload: null };
-                    try {
-                        failedSnapshot.stat = await handle.stat();
-                    }
-                    catch {
-                        // Best-effort cleanup of a failed exclusive create.
-                    }
-                    const current = state.held.get(normalizedTargetPath);
-                    if (current?.handle === handle) {
-                        state.held.delete(normalizedTargetPath);
-                    }
-                    // If payload serialization/write fails, the file may be empty or
-                    // partial JSON, so remove while our exclusive handle is still open.
-                    await fs.rm(lockPath, { force: true }).catch(() => undefined);
-                    await handle.close().catch(() => undefined);
-                    // Windows can refuse removing an open file; retry after close but
-                    // only if the path still points at the file identity we created.
-                    await removeLockIfUnchanged(lockPath, failedSnapshot);
-                }
-                if (err.code !== "EEXIST") {
-                    throw err;
-                }
-                const nowMs = Date.now();
-                const snapshot = await readLockSnapshot(lockPath);
-                if (!snapshot) {
+            const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
+                ? Number.POSITIVE_INFINITY
+                : Math.max(0, options.timeoutMs - elapsed);
+            const delay = Math.min(computeDelayMs(retry, attempt), remaining);
+            attempt += 1;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        };
+        try {
+            while (true) {
+                if (!ownsReclaimGuard && (await sidecarReclaimGuardExists(reclaimGuardPath))) {
+                    await waitForRetry();
                     continue;
                 }
-                const shouldReclaim = options.shouldReclaim ?? defaultShouldReclaim;
-                if (await shouldReclaim({
-                    lockPath,
-                    normalizedTargetPath,
-                    payload: snapshot?.payload ?? null,
-                    staleMs: options.staleMs,
-                    nowMs,
-                    heldByThisProcess: state.held.has(normalizedTargetPath),
-                })) {
-                    if (!(await lockSnapshotStillPresent(lockPath, snapshot))) {
-                        continue;
+                let handle = null;
+                try {
+                    handle = await fs.open(lockPath, "wx");
+                    const payload = await options.payload();
+                    const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
+                    await handle.writeFile(raw, "utf8");
+                    const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
+                    const createdHeld = {
+                        count: 1,
+                        handle,
+                        lockPath,
+                        snapshot,
+                        acquiredAt: Date.now(),
+                        metadata: options.metadata ?? {},
+                    };
+                    state.held.set(normalizedTargetPath, createdHeld);
+                    if (ownsReclaimGuard) {
+                        try {
+                            await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
+                            ownsReclaimGuard = false;
+                        }
+                        catch (err) {
+                            await releaseHeldLock(state, normalizedTargetPath, createdHeld, { force: true });
+                            throw err;
+                        }
                     }
-                    // A pathname recheck followed by unlink is not atomic: a fresh lock
-                    // can replace the observed file in between. Legacy recovery inputs
-                    // remain accepted, but third-party stale locks always fail closed.
-                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                        code: "file_lock_stale",
+                    const release = () => releaseHeldLock(state, normalizedTargetPath, createdHeld).then(() => undefined);
+                    return {
                         lockPath,
                         normalizedTargetPath,
-                    });
+                        release,
+                        [Symbol.asyncDispose]: release,
+                    };
                 }
-                const elapsed = Date.now() - startedAt;
-                if ((options.timeoutMs !== undefined &&
-                    options.timeoutMs !== Number.POSITIVE_INFINITY &&
-                    elapsed >= options.timeoutMs) ||
-                    (maxRetries !== undefined && attempt >= maxRetries)) {
-                    throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                        code: "file_lock_timeout",
+                catch (err) {
+                    if (handle) {
+                        const failedSnapshot = { payload: null };
+                        try {
+                            failedSnapshot.stat = await handle.stat();
+                        }
+                        catch {
+                            // Best-effort cleanup of a failed exclusive create.
+                        }
+                        const current = state.held.get(normalizedTargetPath);
+                        if (current?.handle === handle) {
+                            state.held.delete(normalizedTargetPath);
+                        }
+                        // If payload serialization/write fails, the file may be empty or
+                        // partial JSON, so remove while our exclusive handle is still open.
+                        await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                        await handle.close().catch(() => undefined);
+                        // Windows can refuse removing an open file; retry after close but
+                        // only if the path still points at the file identity we created.
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot);
+                    }
+                    if (err.code !== "EEXIST") {
+                        throw err;
+                    }
+                    if (ownsReclaimGuard) {
+                        await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
+                        ownsReclaimGuard = false;
+                        continue;
+                    }
+                    const nowMs = Date.now();
+                    const snapshot = await readSidecarLockSnapshot(lockPath);
+                    if (!snapshot) {
+                        continue;
+                    }
+                    const shouldReclaim = options.shouldReclaim ?? defaultShouldReclaim;
+                    if (await shouldReclaim({
                         lockPath,
                         normalizedTargetPath,
-                    });
+                        payload: snapshot?.payload ?? null,
+                        staleMs: options.staleMs,
+                        nowMs,
+                        heldByThisProcess: state.held.has(normalizedTargetPath),
+                    })) {
+                        if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot))) {
+                            continue;
+                        }
+                        const staleRecovery = options.staleRecovery ?? "fail-closed";
+                        if (staleRecovery === "remove-if-unchanged") {
+                            if (!(await tryAcquireSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath))) {
+                                await waitForRetry();
+                                continue;
+                            }
+                            ownsReclaimGuard = true;
+                            const removal = await removeStaleSidecarLockIfAllowed({
+                                lockPath,
+                                normalizedTargetPath,
+                                snapshot,
+                                shouldRemoveStaleLock: options.shouldRemoveStaleLock,
+                            });
+                            if (removal === "removed" || removal === "changed") {
+                                continue;
+                            }
+                            await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
+                            ownsReclaimGuard = false;
+                        }
+                        throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                            code: "file_lock_stale",
+                            lockPath,
+                            normalizedTargetPath,
+                        });
+                    }
+                    await waitForRetry();
                 }
-                const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
-                    ? Number.POSITIVE_INFINITY
-                    : Math.max(0, options.timeoutMs - elapsed);
-                const delay = Math.min(computeDelayMs(retry, attempt), remaining);
-                attempt += 1;
-                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        finally {
+            if (ownsReclaimGuard) {
+                await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath).catch(() => undefined);
             }
         }
     }

package/docs/config.md

@@ -56,7 +56,7 @@ Return the effective configuration: programmatic overrides win, then env vars, t
 function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
 
 type FsSafeLockConfig = {
-  staleRecovery: "fail-closed" | "remove-if-unchanged"; // legacy value also fails closed
+  staleRecovery: "fail-closed" | "remove-if-unchanged";
   staleMs?: number;
   timeoutMs?: number;
   retry?: FileLockRetryOptions;
@@ -65,7 +65,7 @@ type FsSafeLockConfig = {
 
 Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
 
-`staleRecovery` defaults to `"fail-closed"`. The deprecated `"remove-if-unchanged"` value remains accepted for source and configuration compatibility, but behaves as `"fail-closed"`. fs-safe never removes a stale third-party lock during acquisition because a pathname recheck followed by unlink cannot prevent deleting a replacement lock.
+`staleRecovery` defaults to `"fail-closed"`. The opt-in `"remove-if-unchanged"` mode requires caller approval and serializes the final snapshot check and unlink with an exclusive `.reclaim` guard. A reclaim guard left by a killed reclaimer fails closed and requires externally coordinated cleanup.
 
 ## `getFsSafeLockConfig()`
 

package/docs/json-store.md

@@ -53,7 +53,7 @@ type JsonStoreLockOptions = {
   staleMs?: number;     // default 30_000
   timeoutMs?: number;   // default 30_000
   retry?: FileLockRetryOptions;
-  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // legacy value also fails closed
+  staleRecovery?: "fail-closed" | "remove-if-unchanged";
   managerKey?: string;  // default `fs-safe.json-store:<filePath>`
 };
 
@@ -141,7 +141,7 @@ When `lock` is falsy, `read` / `write` / `update` are unlocked. The `update` sha
 
 Process-wide lock defaults from `configureFsSafeLocks()` apply only after locking is explicitly enabled. They do not make JSON stores lock by default.
 
-JSON store locks always fail closed on stale sidecars. The deprecated `staleRecovery: "remove-if-unchanged"` value remains accepted for compatibility, but it behaves as `"fail-closed"` and never removes the lock.
+JSON store locks fail closed on stale sidecars by default. Opt-in `staleRecovery: "remove-if-unchanged"` requires caller approval and uses the same exclusive reclaim guard as the low-level sidecar-lock API.
 
 The default `managerKey` namespaces the in-process `FileLockManager` per absolute file path, so two `jsonStore` calls on the same file share lock state automatically.
 

package/docs/sidecar-lock.md

@@ -21,7 +21,11 @@ try {
 
 The lock file sits next to the protected resource. If a process crashes mid-lock, the next acquirer notices the held entry, inspects its payload (PID, host, acquired-at timestamp), and decides — via `shouldReclaim` (defaulting to "is the lock older than `staleMs`?") — whether it should keep waiting or fail.
 
-The library installs a `process.on("exit")` handler that releases all currently-held locks synchronously, so well-behaved exits leave no stale sidecars. Crashed holders leave their sidecar behind; remove those through an application-owned recovery path after you have proved the holder cannot still be writing.
+The library installs a `process.on("exit")` handler that releases all currently-held locks synchronously, so well-behaved exits leave no stale sidecars. Crashed holders leave their sidecar behind; recover only after an application-owned liveness policy proves the holder cannot still be writing.
+
+Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check.
+
+The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.
 
 ## API
 
@@ -51,7 +55,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   staleMs?: number;                      // default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
-  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // legacy value also fails closed
+  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
   allowReentrant?: boolean;              // if this process already holds it, increment a count instead of failing
   payload: () => TPayload | Promise<TPayload>;
   shouldReclaim?: (params: {
@@ -62,7 +66,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     nowMs: number;
     heldByThisProcess: boolean;
   }) => boolean | Promise<boolean>;
-  shouldRemoveStaleLock?: (snapshot: {          // deprecated; retained but not invoked
+  shouldRemoveStaleLock?: (snapshot: {
     lockPath: string;
     normalizedTargetPath: string;
     raw: string;
@@ -170,24 +174,28 @@ const handle = await acquireFileLock(targetPath, {
 });
 ```
 
-`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result marks the observed sidecar as stale and acquisition throws an error with code `file_lock_stale`.
+`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or attempts caller-approved removal.
+
+## Stale recovery: guarded `remove-if-unchanged`
+
+The default `staleRecovery: "fail-closed"` never removes third-party sidecars. Use `staleRecovery: "remove-if-unchanged"` only when your app has a reliable owner-liveness policy and can prove a stale owner cannot still be writing.
 
-## Stale recovery is fail-closed
+Opt-in recovery creates an exclusive `<lockPath>.reclaim` directory before the final snapshot check and unlink. Every compliant acquirer waits while that guard exists, so two reclaimers cannot perform the check/unlink race that could delete a fresh replacement lock. If another acquirer creates the replacement during the handoff, its exclusive create wins and the reclaimer leaves it untouched.
 
-fs-safe never removes a stale third-party sidecar during acquisition. Checking a pathname's content and identity before unlinking it is not atomic: another process can replace the lock between the final check and the unlink. Every stale result therefore fails closed with error code `file_lock_stale`.
+`shouldRemoveStaleLock` receives the exact lock snapshot that fs-safe inspected. The callback must approve that owner as definitely stale. If the callback is missing, returns false, or the file changed, acquisition fails closed or keeps retrying according to the normal retry policy.
 
-The `"remove-if-unchanged"` value and `shouldRemoveStaleLock` callback remain accepted as deprecated compatibility inputs. They are ignored and the callback is not invoked. To recover, stop or otherwise exclude every process that can acquire the lock, remove the confirmed stale sidecar under that external authority, and retry acquisition.
+A process killed during the short reclaim section can leave the empty `.reclaim` directory behind. That ambiguous state intentionally fails closed; remove the guard only under external authority that excludes every competing lock acquirer.
 
 ## What sidecar locks defend against
 
 - **Two processes writing the same file at once.** `acquire` serializes the critical section.
-- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks always fail closed and are never unlinked during acquisition.
+- **Accidentally deleting a fresh lock during stale recovery.** Opt-in removal is serialized by the reclaim guard and rechecks the approved snapshot before unlinking.
 - **Race between simultaneous acquire attempts.** `O_CREAT | O_EXCL` ensures one wins.
 
 ## What they do **not** defend against
 
 - **Misbehaving holders that ignore the lock.** Locks are advisory — only callers that go through `acquire` are bound.
-- **Automatic stale lock deletion.** If a process crashes, recover only under external authority that excludes every competing lock acquirer.
+- **Unapproved stale lock deletion.** If a process crashes, use the payload and your own liveness policy before opting into guarded recovery.
 - **Multi-host coordination over network filesystems.** Behavior depends on the underlying filesystem's `O_EXCL` semantics; treat as best-effort.
 
 ## Common patterns

package/docs/writing.md

@@ -250,7 +250,7 @@ await fs.write("state.json", body); // succeeds on rclone FUSE
 
 **Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain the Python helper's fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
 
-Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-is-fail-closed).
+Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-guarded-remove-if-unchanged).
 
 ## See also
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {