@openclaw/fs-safe 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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
+
+- Restore the pre-0.4.2 `readRegularFile` and `readRegularFileSync` overflow error message while retaining allocation-bounded reads and the structured `too-large` error on the new low-level bounded-read primitives.
+
 ## 0.4.2 - 2026-07-18
 
 ### Features

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/regular-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAW7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AAWD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAuD3C;AA+CD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAwBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}
+{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAW7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AAsBD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAyD3C;AAoDD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAqBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}

package/dist/regular-file.js

@@ -20,6 +20,15 @@ function resolveRegularFileReadFlags() {
             ? fsSync.constants.O_NOFOLLOW
             : 0));
 }
+function regularFileTooLargeError(filePath, maxBytes, cause) {
+    return new FsSafeError("too-large", `File exceeds ${maxBytes} bytes: ${filePath}`, { cause });
+}
+function translateBoundedReadOverflow(error, filePath, maxBytes) {
+    if (error instanceof FsSafeError && error.code === "too-large") {
+        throw regularFileTooLargeError(filePath, maxBytes, error);
+    }
+    throw error;
+}
 export async function statRegularFile(filePath) {
     let stat;
     try {
@@ -59,7 +68,7 @@ export async function readRegularFile(params) {
         throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
     }
     if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${result.stat.size})`);
+        throw regularFileTooLargeError(params.filePath, params.maxBytes);
     }
     let handle;
     try {
@@ -90,13 +99,23 @@ export async function readRegularFile(params) {
             preOpenStat: result.stat,
         });
         if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-            throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${stat.size})`);
+            throw regularFileTooLargeError(params.filePath, params.maxBytes);
         }
         // With a byte cap, avoid readFile(): a raced file growth would allocate
         // the oversized content before the post-read check could reject it.
-        const buffer = params.maxBytes === undefined
-            ? await handle.readFile()
-            : await readFileHandleBounded(handle, params.maxBytes);
+        let buffer;
+        try {
+            buffer =
+                params.maxBytes === undefined
+                    ? await handle.readFile()
+                    : await readFileHandleBounded(handle, params.maxBytes);
+        }
+        catch (error) {
+            if (params.maxBytes !== undefined) {
+                translateBoundedReadOverflow(error, params.filePath, params.maxBytes);
+            }
+            throw error;
+        }
         return { buffer, stat };
     }
     finally {
@@ -121,13 +140,23 @@ function readOpenedRegularFileSync(params) {
         preOpenStat: params.preOpenStat,
     });
     if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${stat.size})`);
+        throw regularFileTooLargeError(params.filePath, params.maxBytes);
     }
     // Keep capped sync reads incremental for the same reason as async reads:
     // readFileSync(fd) would buffer a raced oversized file before throwing.
-    const buffer = params.maxBytes === undefined
-        ? fsSync.readFileSync(params.fd)
-        : readFileDescriptorBoundedSync(params.fd, params.maxBytes);
+    let buffer;
+    try {
+        buffer =
+            params.maxBytes === undefined
+                ? fsSync.readFileSync(params.fd)
+                : readFileDescriptorBoundedSync(params.fd, params.maxBytes);
+    }
+    catch (error) {
+        if (params.maxBytes !== undefined) {
+            translateBoundedReadOverflow(error, params.filePath, params.maxBytes);
+        }
+        throw error;
+    }
     return { buffer, stat };
 }
 export function readRegularFileSync(params) {
@@ -137,7 +166,7 @@ export function readRegularFileSync(params) {
         throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
     }
     if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${result.stat.size})`);
+        throw regularFileTooLargeError(params.filePath, params.maxBytes);
     }
     const fd = fsSync.openSync(params.filePath, resolveRegularFileReadFlags());
     try {

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

@@ -0,0 +1,26 @@
+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;
+};
+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":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIrC,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;CACd,CAAC;AAEF,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,CAQT;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,103 @@
+import fs from "node:fs/promises";
+import { sameFileIdentity } from "./file-identity.js";
+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.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":"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"}
+{"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, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 function getGlobalManagers() {
     const globalWithState = globalThis;
@@ -14,58 +15,21 @@ 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);
     }
-    return state;
-}
-async function readLockSnapshot(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;
-    }
-}
-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;
+    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();
     }
-    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);
+    return state;
 }
 function snapshotMatchesSync(lockPath, observed) {
     try {
@@ -112,6 +76,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 +100,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 +123,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 +136,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 +165,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 = `${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);
+                    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,7 @@ 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.
 
 ## API
 
@@ -51,7 +51,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 +62,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 +170,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 is fail-closed
+## Stale recovery: guarded `remove-if-unchanged`
 
-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`.
+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.
 
-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.
+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.
+
+`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.
+
+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/package.json

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