@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

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

@@ -0,0 +1,349 @@
+import fs from "node:fs";
+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 { 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];
+}
+function releaseAllSyncHeldLocks() {
+    const heldLocks = getSyncHeldLocks();
+    for (const [normalizedTargetPath, held] of heldLocks) {
+        if (held.timer) {
+            clearInterval(held.timer);
+            held.timer = undefined;
+        }
+        try {
+            if (held.fd !== undefined)
+                fs.closeSync(held.fd);
+        }
+        catch {
+            // Best-effort process-exit cleanup.
+        }
+        try {
+            removeSidecarLockIfUnchangedSync(held.lockPath, held.snapshot);
+        }
+        catch {
+            // A surviving sidecar fails closed and can be reclaimed by policy.
+        }
+        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);
+}
+function verifySyncHeldLock(held) {
+    const current = readSidecarLockSnapshotSync(held.lockPath, held.parsePayload);
+    return !!current && sidecarLockSnapshotMatches(current, held.snapshot);
+}
+function releaseSyncHeldLock(held) {
+    const heldLocks = getSyncHeldLocks();
+    if (heldLocks.get(held.normalizedTargetPath) !== held)
+        return false;
+    if (held.refCount > 1) {
+        held.refCount -= 1;
+        return false;
+    }
+    // Keep the final reference and cleanup receipt until deletion succeeds.
+    if (held.timer) {
+        clearInterval(held.timer);
+        held.timer = undefined;
+    }
+    if (held.fd !== undefined) {
+        const fd = held.fd;
+        // A close error may still free the number; consume ownership before closing.
+        held.fd = undefined;
+        fs.closeSync(fd);
+    }
+    removeSidecarLockIfUnchangedSync(held.lockPath, held.snapshot);
+    heldLocks.delete(held.normalizedTargetPath);
+    return true;
+}
+function createSyncHeldLockHandle(held) {
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        releaseSyncHeldLock(held);
+        released = true;
+    };
+    return {
+        lockPath: held.lockPath,
+        normalizedTargetPath: held.normalizedTargetPath,
+        verifyStillHeld: () => verifySyncHeldLock(held),
+        release,
+        [Symbol.dispose]: release,
+    };
+}
+function canonicalLockParentSync(parent) {
+    // Match Root's async realpath, including Windows short-name expansion.
+    return process.platform === "win32" ? fs.realpathSync.native(parent) : fs.realpathSync(parent);
+}
+function normalizeTargetPath(targetPath) {
+    const resolved = path.resolve(targetPath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    try {
+        return path.join(canonicalLockParentSync(path.dirname(resolved)), path.basename(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;
+    }
+}
+export function acquireFileLockSync(targetPath, options) {
+    const defaults = getFsSafeLockConfig();
+    const retry = options.retry ?? defaults.retry ?? {};
+    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(timeoutMs);
+    const normalizedTargetPath = normalizeTargetPath(targetPath);
+    const lockPath = boundedLockPath(options.lockPath ?? `${normalizedTargetPath}.lock`, options.lockRoot);
+    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);
+    }
+    // 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 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;
+            }
+            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,
+            };
+            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();
+            }
+            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);
+            }
+            if (lockFileCreateDenied && retryLockFileDenial(error))
+                continue;
+            if (error.code !== "EEXIST")
+                throw error;
+            if (heldLocks.has(normalizedTargetPath)) {
+                waitForRetry();
+                continue;
+            }
+            let rawSnapshot;
+            let lockFileOpenDenied = false;
+            try {
+                rawSnapshot = readSidecarLockRawSnapshotSync(lockPath, {
+                    rejectNonFile: true,
+                    onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
+                });
+            }
+            catch (readError) {
+                if (lockFileOpenDenied && retryLockFileDenial(readError))
+                    continue;
+                throw readError;
+            }
+            const snapshot = parseSidecarLockSnapshot(rawSnapshot, options.parsePayload);
+            if (!snapshot) {
+                waitForRetry();
+                continue;
+            }
+            const nowMs = Date.now();
+            const reclaim = options.shouldReclaim
+                ? options.shouldReclaim({
+                    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;
+                    try {
+                        fs.mkdirSync(reclaimGuardPath);
+                        ownsReclaimGuard = true;
+                        if (removeSidecarLockIfUnchangedSync(lockPath, snapshot))
+                            continue;
+                    }
+                    catch (reclaimError) {
+                        if (reclaimError.code !== "EEXIST") {
+                            throw reclaimError;
+                        }
+                        waitForRetry();
+                        continue;
+                    }
+                    finally {
+                        if (ownsReclaimGuard) {
+                            try {
+                                fs.rmdirSync(reclaimGuardPath);
+                            }
+                            catch {
+                                // A surviving reclaim guard fails closed.
+                            }
+                        }
+                    }
+                }
+                throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                    code: "file_lock_stale",
+                    lockPath,
+                    normalizedTargetPath,
+                });
+            }
+            waitForRetry();
+        }
+    }
+}
+export function withFileLockSync(targetPath, options, fn) {
+    const lock = acquireFileLockSync(targetPath, options);
+    try {
+        return fn();
+    }
+    finally {
+        lock.release();
+    }
+}

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

@@ -0,0 +1,24 @@
+import { type SidecarLockAcquireOptions, type SidecarLockHandle, type SidecarLockHeldEntry, type SidecarLockRetryOptions, type SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export { acquireFileLockSync, withFileLockSync, type FileLockSyncAcquireOptions, type FileLockSyncHandle, } from "./file-lock-sync.js";
+export type FileLockRetryOptions = SidecarLockRetryOptions;
+export type FileLockStaleRecovery = SidecarLockStaleRecovery;
+export type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = Omit<SidecarLockAcquireOptions<TPayload>, "targetPath" | "staleMs"> & {
+    managerKey?: string;
+    staleMs?: number;
+};
+export type FileLockHandle = SidecarLockHandle;
+export type FileLockHeldEntry = SidecarLockHeldEntry;
+export type { SidecarLockCompromisedInfo } from "./sidecar-lock.js";
+export type FileLockManager = {
+    acquire<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>): Promise<FileLockHandle>;
+    withLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>, fn: () => Promise<T>): Promise<T>;
+    drain(): Promise<void>;
+    reset(): void;
+    heldEntries(): FileLockHeldEntry[];
+};
+export declare function acquireFileLock<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>): Promise<FileLockHandle>;
+export declare function withFileLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>, fn: () => Promise<T>): Promise<T>;
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAE7D,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,GAAG,SAAS,CACzB,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AACrD,YAAY,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,QAAQ,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,IAAI,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAmBF,wBAAsB,eAAe,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAelE;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF"}

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

@@ -0,0 +1,46 @@
+import { createSidecarLockManager, } from "./sidecar-lock.js";
+import { getFsSafeLockConfig } from "./lock-config.js";
+export { acquireFileLockSync, withFileLockSync, } from "./file-lock-sync.js";
+function resolveFileLockManagerKey(targetPath, managerKey) {
+    return managerKey ?? `fs-safe.file-lock:${targetPath}`;
+}
+function withLockDefaults(options) {
+    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,
+    };
+}
+export async function acquireFileLock(targetPath, options) {
+    return await createFileLockManager(resolveFileLockManagerKey(targetPath, options.managerKey))
+        .acquire(targetPath, options);
+}
+export async function withFileLock(targetPath, options, fn) {
+    return await createFileLockManager(resolveFileLockManagerKey(targetPath, options.managerKey))
+        .withLock(targetPath, options, fn);
+}
+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 });
+        },
+        withLock: async (targetPath, options, fn) => {
+            const { managerKey: _managerKey, ...acquireOptions } = options;
+            return await manager.withLock({ ...withLockDefaults(acquireOptions), targetPath }, fn);
+        },
+        drain: manager.drain,
+        reset: manager.reset,
+        heldEntries: manager.heldEntries,
+    };
+}
+export async function drainFileLockManagerForTest(targetPath, managerKey) {
+    await createFileLockManager(resolveFileLockManagerKey(targetPath, managerKey)).drain();
+}
+export function resetFileLockManagerForTest(targetPath, managerKey) {
+    createFileLockManager(resolveFileLockManagerKey(targetPath, managerKey)).reset();
+}

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

@@ -0,0 +1,9 @@
+type FailureKind = "identity" | "resolution" | `open:${string}` | `exclusive-create:${string}` | `unlinked:${string}` | `changed:${string}`;
+export declare function recordFileObservationFailure(error: unknown, kind: FailureKind): void;
+export declare function isFileObservationFailure(error: unknown, kind: FailureKind): boolean;
+export declare function fileObservation(): {
+    run<T>(operation: () => T): T;
+    has(error: unknown, kind: FailureKind): boolean;
+};
+export {};
+//# sourceMappingURL=file-observation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-observation.d.ts","sourceRoot":"","sources":["../src/file-observation.ts"],"names":[],"mappings":"AAEA,KAAK,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,MAAM,EAAE,GAAG,oBAAoB,MAAM,EAAE,GAAG,YAAY,MAAM,EAAE,GAAG,WAAW,MAAM,EAAE,CAAC;AAG5I,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAMpF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAEnF;AAGD,wBAAgB,eAAe;IAG3B,GAAG,CAAC,CAAC,aAAa,MAAM,CAAC,GAAG,CAAC;IAC7B,GAAG,QAAQ,OAAO,QAAQ,WAAW,GAAG,OAAO;EAElD"}

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

@@ -0,0 +1,22 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const active = new AsyncLocalStorage();
+export function recordFileObservationFailure(error, kind) {
+    const failures = active.getStore();
+    if (!failures)
+        return;
+    let kinds = failures.get(error);
+    if (!kinds)
+        failures.set(error, kinds = new Set());
+    kinds.add(kind);
+}
+export function isFileObservationFailure(error, kind) {
+    return active.getStore()?.get(error)?.has(kind) === true;
+}
+// Each Root observation owns its receipts, including nested and concurrent reads.
+export function fileObservation() {
+    const failures = new Map();
+    return {
+        run(operation) { return active.run(failures, operation); },
+        has(error, kind) { return failures.get(error)?.has(kind) === true; },
+    };
+}

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

@@ -0,0 +1,33 @@
+import type { Readable } from "node:stream";
+import { type SyncDirectoryGuard } from "./directory-guard.js";
+import { type Root } from "./root.js";
+import { prepareSecretFileWrite } from "./secret-file.js";
+export type SyncParentGuard = SyncDirectoryGuard;
+export declare function ensureParentInRoot(scopedRoot: Root, relativePath: string, mode: number): Promise<void>;
+export declare function openWritableStoreRoot(params: {
+    rootDir: string;
+    dirMode: number;
+    maxBytes?: number;
+}): Promise<Root>;
+export declare function openPrivateStoreLockRoot(params: Parameters<typeof prepareSecretFileWrite>[0]): Promise<Root>;
+export declare function writeStreamToTempSource(params: {
+    stream: Readable;
+    maxBytes?: number;
+    mode: number;
+}): Promise<{
+    path: string;
+    cleanup: () => Promise<void>;
+}>;
+export declare function assertSyncDirectoryGuard(guard: SyncParentGuard): void;
+export declare function ensureParentSync(params: {
+    rootDir: string;
+    filePath: string;
+    mode: number;
+}): SyncParentGuard;
+export declare function ensureStoreDirectorySync(params: {
+    rootDir: string;
+    targetDir: string;
+    mode: number;
+    messagePrefix: "private store" | "store";
+}): SyncParentGuard;
+//# sourceMappingURL=file-store-boundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-store-boundary.d.ts","sourceRoot":"","sources":["../src/file-store-boundary.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAA4C,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGhF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAOjD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,IAAI,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC,CASf;AAsCD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAwC1D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAWrE;AAUD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,eAAe,CAOlB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,eAAe,GAAG,OAAO,CAAC;CAC1C,GAAG,eAAe,CAyDlB"}