@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync.js

@@ -1,20 +1,17 @@
 import fs from "node:fs";
+import { acquireFileLockSyncWithRoot } from "./file-lock-sync-root-acquire.js";
+import { withSyncHeldLockHandle } from "./file-lock-sync-root-held.js";
 import path from "node:path";
-import { FsSafeError } from "./errors.js";
-import { readSidecarLockSnapshotSync, readSidecarLockRawSnapshotSync, parseSidecarLockSnapshot, relativeSidecarLockPath, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
-import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, sidecarLockPayloadCreatedAtMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { readSidecarLockRawSnapshotSync, readSidecarLockSnapshotSync, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { sidecarLockTimeout, isTransientLockFileDenial, validateSidecarLockStaleMs, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
-import { sleepSync } from "./timing.js";
-const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
-const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
-const SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupHandler");
-function getSyncHeldLocks() {
-    const globalWithState = globalThis;
-    if (!globalWithState[SYNC_HELD_LOCKS_KEY]) {
-        globalWithState[SYNC_HELD_LOCKS_KEY] = new Map();
-    }
-    return globalWithState[SYNC_HELD_LOCKS_KEY];
-}
+import { SyncLockAcquisition } from "./file-lock-sync-acquisition.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { ensureSyncLockExitCleanupRegistered, getSyncHeldLocks, foreignSyncHeldLock, getSyncLockAdmissions, syncReclaimGuardExists, } from "./file-lock-sync-admission.js";
+import { handleSyncStaleAdmission, } from "./file-lock-sync-stale-admission.js";
 function releaseAllSyncHeldLocks() {
     const heldLocks = getSyncHeldLocks();
     for (const [normalizedTargetPath, held] of heldLocks) {
@@ -37,17 +34,14 @@ function releaseAllSyncHeldLocks() {
         }
         heldLocks.delete(normalizedTargetPath);
     }
-}
-function ensureSyncExitCleanupRegistered() {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY])
-        return;
-    globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY] = true;
-    globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] = releaseAllSyncHeldLocks;
-    process.on("exit", releaseAllSyncHeldLocks);
+    getSyncLockAdmissions().clear();
 }
 function verifySyncHeldLock(held) {
-    const current = readSidecarLockSnapshotSync(held.lockPath, held.parsePayload);
+    const lockPath = held.lockPath;
+    const parsePayload = held.parsePayload;
+    const current = parsePayload
+        ? readSidecarLockSnapshotSync(lockPath, parsePayload)
+        : readSidecarLockRawSnapshotSync(lockPath);
     return !!current && sidecarLockSnapshotMatches(current, held.snapshot);
 }
 function releaseSyncHeldLock(held) {
@@ -91,259 +85,257 @@ function createSyncHeldLockHandle(held) {
 }
 function canonicalLockParentSync(parent) {
     // Match Root's async realpath, including Windows short-name expansion.
-    return process.platform === "win32" ? fs.realpathSync.native(parent) : fs.realpathSync(parent);
+    return process.platform === "win32" ? realpathSync.native(parent) : realpathSync(parent);
 }
 function normalizeTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
-    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    assertNoWindowsPathAlias(resolved);
+    fs.mkdirSync(recursiveMkdirPath(path.dirname(resolved)), { recursive: true });
+    let parent;
     try {
-        return path.join(canonicalLockParentSync(path.dirname(resolved)), path.basename(resolved));
+        parent = canonicalLockParentSync(path.dirname(resolved));
     }
     catch {
         return resolved;
     }
-}
-function boundedLockPath(lockPath, lockRoot) {
-    const resolved = path.resolve(lockPath);
-    if (!lockRoot)
-        return resolved;
-    relativeSidecarLockPath(lockRoot, resolved);
-    const parent = path.dirname(resolved);
-    const parentReal = canonicalLockParentSync(parent);
-    const parentRelative = path.relative(lockRoot.rootReal, parentReal);
-    if (parentRelative === ".." || parentRelative.startsWith(`..${path.sep}`) || path.isAbsolute(parentRelative)) {
-        throw new FsSafeError("outside-workspace", "sidecar lock parent is outside lockRoot");
-    }
-    return path.join(parentReal, path.basename(resolved));
-}
-function defaultShouldReclaim(snapshot, staleMs, nowMs) {
-    const createdAtMs = sidecarLockPayloadCreatedAtMs(snapshot.payload);
-    if (createdAtMs !== null)
-        return nowMs - createdAtMs > staleMs;
-    // A cooperating holder can unlink after the snapshot; use its observed age.
-    return !snapshot.stat || nowMs - snapshot.stat.mtimeMs > staleMs;
-}
-function reclaimGuardExists(reclaimGuardPath) {
-    try {
-        fs.lstatSync(reclaimGuardPath);
-        return true;
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return false;
-        throw error;
-    }
+    assertNoWindowsPathAlias(parent);
+    const normalized = path.join(parent, path.basename(resolved));
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
 }
 export function acquireFileLockSync(targetPath, options) {
+    const lockRoot = options.lockRoot;
+    if (lockRoot)
+        return acquireFileLockSyncWithRoot(targetPath, options, lockRoot);
     const defaults = getFsSafeLockConfig();
     const retry = options.retry ?? defaults.retry ?? {};
     const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
     validateSidecarLockRetryOptions(retry);
     validateSidecarLockTimeoutMs(timeoutMs);
+    const staleMs = options.staleMs ?? defaults.staleMs ?? 30_000;
+    validateSidecarLockStaleMs(staleMs);
+    const compromiseCheckIntervalMs = options.compromiseCheckIntervalMs;
+    validateSidecarLockCompromiseCheckIntervalMs(compromiseCheckIntervalMs);
+    const explicitLockPath = options.lockPath;
+    assertNoWindowsPathAlias(targetPath);
+    if (explicitLockPath !== undefined)
+        assertNoWindowsPathAlias(explicitLockPath);
     const normalizedTargetPath = normalizeTargetPath(targetPath);
-    const lockPath = boundedLockPath(options.lockPath ?? `${normalizedTargetPath}.lock`, options.lockRoot);
+    const lockPath = path.resolve(explicitLockPath ?? `${normalizedTargetPath}.lock`);
+    assertNoWindowsPathAlias(lockPath);
+    const requestedReentrantOwner = options.reentrantOwner;
     const heldLocks = getSyncHeldLocks();
-    const held = heldLocks.get(normalizedTargetPath);
-    if (held &&
-        options.reentrantOwner !== undefined &&
-        held.reentrantOwner !== undefined &&
-        options.reentrantOwner === held.reentrantOwner) {
-        held.refCount += 1;
-        return createSyncHeldLockHandle(held);
+    const currentTargetHolder = () => heldLocks.get(normalizedTargetPath) ??
+        foreignSyncHeldLock("raw", normalizedTargetPath);
+    const initiallyHeld = heldLocks.get(normalizedTargetPath);
+    if (initiallyHeld && !foreignSyncHeldLock("raw", normalizedTargetPath) &&
+        requestedReentrantOwner !== undefined &&
+        initiallyHeld.reentrantOwner !== undefined &&
+        requestedReentrantOwner === initiallyHeld.reentrantOwner) {
+        initiallyHeld.refCount += 1;
+        return createSyncHeldLockHandle(initiallyHeld);
     }
-    // Process defaults fill the same fields here as withLockDefaults() fills for
-    // the asynchronous manager, so both acquirers honor configureFsSafeLocks().
-    const staleMs = options.staleMs ?? defaults.staleMs ?? 30_000;
-    const staleRecovery = options.staleRecovery ?? defaults.staleRecovery;
-    const startedAt = Date.now();
-    let attempt = 0;
-    let transientDenials = 0;
+    const acquisition = new SyncLockAcquisition(lockPath, normalizedTargetPath, retry, timeoutMs);
+    let payloadCallback;
+    let onCompromised = undefined;
+    let onCompromisedObserved = false;
+    let parsePayload = undefined;
+    let parsePayloadObserved = false;
+    let staleRecovery = undefined;
+    let staleRecoveryObserved = false;
+    const staleOptions = {};
     const reclaimGuardPath = `${lockPath}.reclaim`;
-    const waitForRetry = () => {
-        const elapsed = Date.now() - startedAt;
-        const timedOut = timeoutMs !== undefined && elapsed >= timeoutMs;
-        if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
-            throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                code: "file_lock_timeout",
-                lockPath,
-                normalizedTargetPath,
-            });
-        }
-        const remaining = timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY
-            ? Number.POSITIVE_INFINITY
-            : Math.max(0, timeoutMs - elapsed);
-        sleepSync(Math.min(computeSidecarLockDelayMs(retry, attempt), remaining));
-        attempt += 1;
-    };
-    const retryLockFileDenial = (error) => {
-        if (!isTransientLockFileDenial(error, lockPath) ||
-            ++transientDenials > maxTransientLockDenials)
-            return false;
-        try {
-            waitForRetry();
-        }
-        catch (waitError) {
-            // Preserve the filesystem diagnosis when the caller's budget runs out.
-            if (waitError.code === "file_lock_timeout")
-                throw error;
-            throw waitError;
-        }
-        return true;
-    };
-    while (true) {
-        if (reclaimGuardExists(reclaimGuardPath)) {
-            waitForRetry();
-            continue;
-        }
-        let fd;
-        const payload = options.payload();
-        const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
-        let lockFileCreateDenied = false;
-        try {
-            const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
-                ? fs.constants.O_NOFOLLOW
-                : 0;
-            try {
-                fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
-            }
-            catch (error) {
-                lockFileCreateDenied = isTransientLockFileDenial(error, lockPath);
-                throw error;
+    try {
+        while (true) {
+            if (!acquisition.owns) {
+                const held = heldLocks.get(normalizedTargetPath);
+                if (held && !foreignSyncHeldLock("raw", normalizedTargetPath) &&
+                    requestedReentrantOwner !== undefined &&
+                    held.reentrantOwner !== undefined &&
+                    requestedReentrantOwner === held.reentrantOwner) {
+                    held.refCount += 1;
+                    return createSyncHeldLockHandle(held);
+                }
+                acquisition.reserve();
             }
-            fs.writeFileSync(fd, raw, "utf8");
-            fs.fsyncSync(fd);
-            const snapshot = {
-                raw,
-                payload,
-                stat: fs.fstatSync(fd),
-                ownershipToken,
-            };
-            const createdHeld = {
-                fd,
-                lockPath,
-                normalizedTargetPath,
-                parsePayload: options.parsePayload,
-                refCount: 1,
-                reentrantOwner: options.reentrantOwner,
-                snapshot,
+            const attemptHeld = currentTargetHolder();
+            const holderWasReplaced = () => {
+                const current = currentTargetHolder();
+                return current !== undefined && current !== attemptHeld;
             };
-            heldLocks.set(normalizedTargetPath, createdHeld);
-            ensureSyncExitCleanupRegistered();
-            const returnedHandle = createSyncHeldLockHandle(createdHeld);
-            if (options.onCompromised && (options.compromiseCheckIntervalMs ?? 0) > 0) {
-                createdHeld.timer = setInterval(() => {
-                    let stillHeld;
-                    try {
-                        stillHeld = returnedHandle.verifyStillHeld();
-                    }
-                    catch {
-                        stillHeld = false;
-                    }
-                    if (!stillHeld && createdHeld.timer) {
-                        clearInterval(createdHeld.timer);
-                        createdHeld.timer = undefined;
-                        options.onCompromised?.({ lockPath, normalizedTargetPath });
-                    }
-                }, options.compromiseCheckIntervalMs);
-                createdHeld.timer.unref();
+            if (!staleRecoveryObserved) {
+                staleRecovery = acquisition.run(() => options.staleRecovery ?? defaults.staleRecovery);
+                staleRecoveryObserved = true;
+                if (holderWasReplaced()) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
             }
-            fd = undefined;
-            return returnedHandle;
-        }
-        catch (error) {
-            if (fd !== undefined) {
-                const failed = { payload: null, stat: fs.fstatSync(fd) };
-                fs.closeSync(fd);
-                fd = undefined;
-                removeSidecarLockIfUnchangedSync(lockPath, failed);
+            const reclaimGuardExists = syncReclaimGuardExists(reclaimGuardPath);
+            if (!acquisition.hasToken())
+                throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
+                continue;
             }
-            if (lockFileCreateDenied && retryLockFileDenial(error))
+            if (reclaimGuardExists) {
+                acquisition.waitForRetry();
                 continue;
-            if (error.code !== "EEXIST")
-                throw error;
-            if (heldLocks.has(normalizedTargetPath)) {
-                waitForRetry();
+            }
+            let fd;
+            let createdHeld;
+            let createdSnapshot;
+            if (!payloadCallback)
+                payloadCallback = acquisition.run(() => options.payload);
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
                 continue;
             }
-            let rawSnapshot;
-            let lockFileOpenDenied = false;
-            try {
-                rawSnapshot = readSidecarLockRawSnapshotSync(lockPath, {
-                    rejectNonFile: true,
-                    onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
-                });
+            const payload = acquisition.run(() => Reflect.apply(payloadCallback, options, []));
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
+                continue;
             }
-            catch (readError) {
-                if (lockFileOpenDenied && retryLockFileDenial(readError))
-                    continue;
-                throw readError;
+            const { raw, ownershipToken } = acquisition.run(() => serializeSidecarLockPayload(payload));
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
+                continue;
             }
-            const snapshot = parseSidecarLockSnapshot(rawSnapshot, options.parsePayload);
-            if (!snapshot) {
-                waitForRetry();
+            if (currentTargetHolder() !== undefined) {
+                acquisition.waitForRetry();
                 continue;
             }
-            const nowMs = Date.now();
-            const reclaim = options.shouldReclaim
-                ? options.shouldReclaim({
+            if (!onCompromisedObserved) {
+                onCompromised = acquisition.run(() => options.onCompromised);
+                onCompromisedObserved = true;
+                if (currentTargetHolder() !== undefined) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+            }
+            if (!parsePayloadObserved) {
+                parsePayload = acquisition.run(() => options.parsePayload);
+                parsePayloadObserved = true;
+                if (currentTargetHolder() !== undefined) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+            }
+            let lockFileCreateDenied = false;
+            let exclusiveCreateConflict = false;
+            try {
+                const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
+                    ? fs.constants.O_NOFOLLOW
+                    : 0;
+                try {
+                    fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
+                }
+                catch (error) {
+                    lockFileCreateDenied = isTransientLockFileDenial(error, lockPath);
+                    exclusiveCreateConflict = error.code === "EEXIST";
+                    throw error;
+                }
+                fs.writeFileSync(fd, raw, "utf8");
+                fs.fsyncSync(fd);
+                createdSnapshot = {
+                    raw,
+                    payload,
+                    stat: fs.fstatSync(fd),
+                    ownershipToken,
+                };
+                createdHeld = {
+                    fd,
                     lockPath,
                     normalizedTargetPath,
-                    payload: snapshot.payload,
-                    staleMs,
-                    nowMs,
-                    heldByThisProcess: false,
-                })
-                : defaultShouldReclaim(snapshot, staleMs, nowMs);
-            if (reclaim) {
-                if (staleRecovery === "remove-if-unchanged" &&
-                    snapshot.raw !== undefined &&
-                    options.shouldRemoveStaleLock?.({
-                        lockPath,
-                        normalizedTargetPath,
-                        raw: snapshot.raw,
-                        payload: snapshot.payload,
-                    })) {
-                    let ownsReclaimGuard = false;
+                    parsePayload,
+                    refCount: 1,
+                    reentrantOwner: requestedReentrantOwner,
+                    snapshot: createdSnapshot,
+                };
+                const candidateHeld = createdHeld;
+                ensureSyncLockExitCleanupRegistered(releaseAllSyncHeldLocks, lockPath, normalizedTargetPath);
+                if (!acquisition.hasToken() || currentTargetHolder() !== undefined) {
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                }
+                const returnedHandle = createSyncHeldLockHandle(candidateHeld);
+                acquisition.monitor(candidateHeld, returnedHandle, onCompromised, compromiseCheckIntervalMs, options);
+                if (!acquisition.hasToken() ||
+                    currentTargetHolder() !== undefined) {
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                }
+                heldLocks.set(normalizedTargetPath, candidateHeld);
+                acquisition.release();
+                fd = undefined;
+                return returnedHandle;
+            }
+            catch (error) {
+                if (createdHeld?.timer) {
+                    clearInterval(createdHeld.timer);
+                    createdHeld.timer = undefined;
+                }
+                if (createdHeld && heldLocks.get(normalizedTargetPath) === createdHeld) {
+                    heldLocks.delete(normalizedTargetPath);
+                }
+                if (fd !== undefined) {
+                    const failed = createdSnapshot ?? { payload: null };
+                    if (!failed.stat) {
+                        try {
+                            failed.stat = fs.fstatSync(fd);
+                        }
+                        catch {
+                            // Missing identity leaves the sidecar in place, but must not skip close.
+                        }
+                    }
+                    const failedFd = fd;
+                    fd = undefined;
+                    if (createdHeld)
+                        createdHeld.fd = undefined;
                     try {
-                        fs.mkdirSync(reclaimGuardPath);
-                        ownsReclaimGuard = true;
-                        if (removeSidecarLockIfUnchangedSync(lockPath, snapshot))
-                            continue;
+                        fs.closeSync(failedFd);
+                        if (failed.stat)
+                            removeSidecarLockIfUnchangedSync(lockPath, failed);
                     }
-                    catch (reclaimError) {
-                        if (reclaimError.code !== "EEXIST") {
-                            throw reclaimError;
-                        }
-                        waitForRetry();
-                        continue;
+                    catch (cleanupError) {
+                        throw createSuppressedError(error, cleanupError, "file lock acquisition and cleanup both failed");
                     }
-                    finally {
-                        if (ownsReclaimGuard) {
-                            try {
-                                fs.rmdirSync(reclaimGuardPath);
-                            }
-                            catch {
-                                // A surviving reclaim guard fails closed.
-                            }
-                        }
+                }
+                if (lockFileCreateDenied) {
+                    if (!acquisition.hasToken())
+                        throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                    if (currentTargetHolder() !== undefined) {
+                        acquisition.waitForRetry();
+                        continue;
                     }
+                    if (acquisition.retryDenial(error))
+                        continue;
+                    throw error;
                 }
-                throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                    code: "file_lock_stale",
-                    lockPath,
-                    normalizedTargetPath,
+                if (!exclusiveCreateConflict)
+                    throw error;
+                if (!acquisition.hasToken())
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                if (currentTargetHolder() !== undefined) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+                handleSyncStaleAdmission(acquisition, {
+                    currentHeld: currentTargetHolder,
+                    options,
+                    parsePayload,
+                    reclaimGuardPath,
+                    staleMs,
+                    staleOptions,
+                    staleRecovery,
                 });
+                continue;
             }
-            waitForRetry();
         }
     }
+    finally {
+        acquisition.release();
+    }
 }
 export function withFileLockSync(targetPath, options, fn) {
     const lock = acquireFileLockSync(targetPath, options);
-    try {
-        return fn();
-    }
-    finally {
-        lock.release();
-    }
+    return withSyncHeldLockHandle(lock, fn);
 }

package/node_modules/@openclaw/fs-safe/dist/file-lock.d.ts

@@ -21,4 +21,3 @@ export declare function withFileLock<T, TPayload extends Record<string, unknown>
 export declare function createFileLockManager(key: string): FileLockManager;
 export declare function drainFileLockManagerForTest(targetPath: string, managerKey?: string): Promise<void>;
 export declare function resetFileLockManagerForTest(targetPath: string, managerKey?: string): void;
-//# sourceMappingURL=file-lock.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/file-lock.js

@@ -5,13 +5,29 @@ function resolveFileLockManagerKey(targetPath, managerKey) {
     return managerKey ?? `fs-safe.file-lock:${targetPath}`;
 }
 function withLockDefaults(options) {
+    const { managerKey: _managerKey, lockPath } = options;
+    const acquireOptions = {};
+    for (const key of Reflect.ownKeys(options)) {
+        // Node 22 object-rest can read excluded accessors; exclude before copying.
+        if (key === "managerKey" || key === "lockPath")
+            continue;
+        if (!Object.getOwnPropertyDescriptor(options, key)?.enumerable)
+            continue;
+        Object.defineProperty(acquireOptions, key, {
+            value: Reflect.get(options, key),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
     const defaults = getFsSafeLockConfig();
     return {
-        ...options,
-        retry: options.retry ?? defaults.retry,
-        staleMs: options.staleMs ?? defaults.staleMs ?? 30_000,
-        staleRecovery: options.staleRecovery ?? defaults.staleRecovery,
-        timeoutMs: options.timeoutMs ?? defaults.timeoutMs,
+        ...acquireOptions,
+        retry: acquireOptions.retry ?? defaults.retry,
+        staleMs: acquireOptions.staleMs ?? defaults.staleMs ?? 30_000,
+        staleRecovery: acquireOptions.staleRecovery ?? defaults.staleRecovery,
+        timeoutMs: acquireOptions.timeoutMs ?? defaults.timeoutMs,
+        ...(lockPath === undefined ? {} : { lockPath }),
     };
 }
 export async function acquireFileLock(targetPath, options) {
@@ -26,12 +42,16 @@ export function createFileLockManager(key) {
     const manager = createSidecarLockManager(key);
     return {
         acquire: async (targetPath, options) => {
-            const { managerKey: _managerKey, ...acquireOptions } = options;
-            return await manager.acquire({ ...withLockDefaults(acquireOptions), targetPath });
+            return await manager.acquire({
+                ...withLockDefaults(options),
+                targetPath,
+            });
         },
         withLock: async (targetPath, options, fn) => {
-            const { managerKey: _managerKey, ...acquireOptions } = options;
-            return await manager.withLock({ ...withLockDefaults(acquireOptions), targetPath }, fn);
+            return await manager.withLock({
+                ...withLockDefaults(options),
+                targetPath,
+            }, fn);
         },
         drain: manager.drain,
         reset: manager.reset,

package/node_modules/@openclaw/fs-safe/dist/file-observation.d.ts

@@ -1,4 +1,4 @@
-type FailureKind = "identity" | "resolution" | `open:${string}` | `exclusive-create:${string}` | `unlinked:${string}` | `changed:${string}`;
+type FailureKind = "identity" | "resolution" | `open:${string}` | `exclusive-create:${string}` | `unlinked:${string}` | `changed:${string}` | `stat-leaf-missing:${string}` | `stat-leaf-changed:${string}`;
 export declare function recordFileObservationFailure(error: unknown, kind: FailureKind): void;
 export declare function isFileObservationFailure(error: unknown, kind: FailureKind): boolean;
 export declare function fileObservation(): {
@@ -6,4 +6,3 @@ export declare function fileObservation(): {
     has(error: unknown, kind: FailureKind): boolean;
 };
 export {};
-//# sourceMappingURL=file-observation.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/file-store-boundary.d.ts

@@ -1,8 +1,8 @@
 import type { Readable } from "node:stream";
-import { type SyncDirectoryGuard } from "./directory-guard.js";
+import { type SyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
 import { type Root } from "./root.js";
 import { prepareSecretFileWrite } from "./secret-file.js";
-export type SyncParentGuard = SyncDirectoryGuard;
+export type SyncParentGuard = SyncStoreDirectoryReceipt;
 export declare function ensureParentInRoot(scopedRoot: Root, relativePath: string, mode: number): Promise<void>;
 export declare function openWritableStoreRoot(params: {
     rootDir: string;
@@ -18,7 +18,6 @@ export declare function writeStreamToTempSource(params: {
     path: string;
     cleanup: () => Promise<void>;
 }>;
-export declare function assertSyncDirectoryGuard(guard: SyncParentGuard): void;
 export declare function ensureParentSync(params: {
     rootDir: string;
     filePath: string;
@@ -30,4 +29,10 @@ export declare function ensureStoreDirectorySync(params: {
     mode: number;
     messagePrefix: "private store" | "store";
 }): SyncParentGuard;
-//# sourceMappingURL=file-store-boundary.d.ts.map
+export declare function assertRelativePath(relativePath: string): string;
+export declare function resolveStorePath(rootDir: string, relativePath: string): string;
+export declare function assertFileStoreMaxBytes(size: number, limit: number | undefined): void;
+export declare function readFileStoreCopySource(params: {
+    sourcePath: string;
+    maxBytes: number;
+}): Promise<Buffer>;