@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

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

@@ -0,0 +1,143 @@
+import { syncFileBestEffort } from "./file-sync.js";
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+import { serializePathWrite } from "./write-queue.js";
+function assertRegularFile(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "symlink sibling temp not allowed");
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "sibling temp must be a regular file");
+    }
+    if (stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", "sibling temp must have exactly one link");
+    }
+}
+async function inspectStage(inspect, expected) {
+    return await inspectFileIdentity(async () => {
+        const stat = await inspect();
+        assertRegularFile(stat);
+        return stat;
+    }, expected);
+}
+// Callback paths are not owned until all three admission observations agree.
+// Keep one descriptor and one exact identity through mode, sync, rename and cleanup.
+// Read/write access is needed only when the caller requests file synchronization.
+export async function writeCallbackSibling(params) {
+    const parent = path.dirname(params.tempPath);
+    const guard = await createAsyncDirectoryGuard(parent);
+    const parentIdentity = await inspectFileIdentity(() => fs.lstat(parent, { bigint: true }));
+    const assertParent = async () => {
+        await assertAsyncDirectoryGuard(guard);
+        await inspectFileIdentity(() => fs.lstat(parent, { bigint: true }), parentIdentity);
+    };
+    let handle;
+    let identity;
+    let unregister;
+    let renamed = false;
+    let failure;
+    const inspectPath = (pathname, expected) => inspectStage(() => fs.lstat(pathname, { bigint: true }), expected);
+    const assertCurrent = async (pathname) => {
+        await assertParent();
+        const opened = await inspectStage(() => handle.stat({ bigint: true }), identity);
+        const current = await inspectPath(pathname, opened);
+        if (params.maxBytes !== undefined &&
+            (opened.size > params.maxBytes || current.size > params.maxBytes)) {
+            throw new FsSafeError("too-large", `sibling temp exceeds maxBytes (${params.maxBytes})`);
+        }
+    };
+    try {
+        const result = await params.write(params.tempPath);
+        await assertParent();
+        const before = await inspectPath(params.tempPath);
+        try {
+            // No create/truncate flags; O_NONBLOCK also bounds a FIFO swap during open.
+            const access = params.syncTempFile ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
+            handle = await fs.open(params.tempPath, access | resolveReadOpenFlags());
+        }
+        catch (error) {
+            if (error?.code === "ELOOP") {
+                throw new FsSafeError("symlink", "symlink sibling temp not allowed", { cause: error });
+            }
+            throw error;
+        }
+        const opened = await inspectStage(() => handle.stat({ bigint: true }), before);
+        await inspectPath(params.tempPath, opened);
+        await assertParent();
+        identity = opened;
+        unregister = registerTempPathForExit(params.tempPath, { identity, singleLinkFile: true });
+        const filePath = path.resolve(params.resolveFinalPath(result));
+        if (path.dirname(filePath) !== parent) {
+            throw new Error("Final path must be in the sibling temp directory.");
+        }
+        if (filePath === params.tempPath) {
+            throw new FsSafeError("invalid-path", "final path must differ from the sibling temp path");
+        }
+        await serializePathWrite(filePath, async () => {
+            await assertCurrent(params.tempPath);
+            if (params.mode !== undefined) {
+                try {
+                    await handle.chmod(params.mode);
+                }
+                catch (error) {
+                    if (!params.ignoreModeError)
+                        throw error;
+                }
+            }
+            if (params.syncTempFile) {
+                await assertCurrent(params.tempPath);
+                await syncFileBestEffort(handle);
+            }
+            await assertCurrent(params.tempPath);
+            await fs.rename(params.tempPath, filePath);
+            // A later verification failure never authorizes rollback of the final name.
+            renamed = true;
+            unregister();
+            await assertCurrent(filePath);
+            if (params.syncParentDir)
+                await syncDirectoryBestEffort(parent);
+            await assertCurrent(filePath);
+        });
+        return { filePath, result };
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        try {
+            if (!renamed && identity) {
+                try {
+                    await assertParent();
+                    await inspectStage(() => handle.stat({ bigint: true }), identity);
+                    await inspectPath(params.tempPath, identity);
+                    await fs.unlink(params.tempPath);
+                    unregister?.();
+                }
+                catch (error) {
+                    // Preserve observed substitutes; retry only operational cleanup failures.
+                    if (error instanceof FsSafeError || error?.code === "ENOENT") {
+                        unregister?.();
+                    }
+                }
+            }
+        }
+        finally {
+            try {
+                await handle?.close();
+            }
+            catch (error) {
+                if (failure)
+                    throw new AggregateError([failure.error, error], "sibling publication and close failed");
+                throw error;
+            }
+        }
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/sibling-temp.d.ts

@@ -0,0 +1,27 @@
+export type WriteSiblingTempFileOptions<T> = {
+    dir: string;
+    writeTemp: (tempPath: string) => Promise<T>;
+    resolveFinalPath: (result: T) => string;
+    tempPrefix?: string;
+    dirMode?: number;
+    chmodDir?: boolean;
+    /** Final file mode; omitted preserves the producer's mode. Applied through the retained descriptor. */
+    mode?: number;
+    /** Sync the staged descriptor before rename; defaults to false. */
+    syncTempFile?: boolean;
+    /** Best-effort parent directory sync after rename; defaults to false. */
+    syncParentDir?: boolean;
+};
+export type WriteSiblingTempFileResult<T> = {
+    filePath: string;
+    result: T;
+};
+export declare function writeSiblingTempFile<T>(options: WriteSiblingTempFileOptions<T>): Promise<WriteSiblingTempFileResult<T>>;
+export declare function writeViaSiblingTempPath(params: {
+    rootDir: string;
+    targetPath: string;
+    writeTemp: (tempPath: string) => Promise<void>;
+    fallbackFileName?: string;
+    tempPrefix?: string;
+}): Promise<void>;
+//# sourceMappingURL=sibling-temp.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/sibling-temp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uGAAuG;IACvG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AASF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAoBxC;AAwBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0ChB"}

package/node_modules/@openclaw/fs-safe/dist/sibling-temp.js

@@ -0,0 +1,95 @@
+import crypto, { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./filename.js";
+import { applyDirectoryMode } from "./replace-file-descriptor.js";
+import { root } from "./root.js";
+import { assertSafePathPrefix } from "./safe-path-segment.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { writeCallbackSibling } from "./sibling-staged-file.js";
+import { tempFile } from "./temp-target.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function buildTempPath(dir, tempPrefix) {
+    const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-stream", {
+        label: "sibling temp prefix",
+    });
+    return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
+}
+export async function writeSiblingTempFile(options) {
+    const dir = path.resolve(options.dir);
+    await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
+    if (options.chmodDir !== false) {
+        await applyDirectoryMode({
+            fsModule: fs,
+            dirPath: dir,
+            mode: options.dirMode ?? 0o700,
+            ignoreChmodError: true,
+        });
+    }
+    return await writeCallbackSibling({
+        tempPath: buildTempPath(dir, options.tempPrefix),
+        write: options.writeTemp,
+        resolveFinalPath: options.resolveFinalPath,
+        mode: options.mode,
+        ignoreModeError: true,
+        syncTempFile: options.syncTempFile === true,
+        syncParentDir: options.syncParentDir === true,
+    });
+}
+function buildSiblingTempPath(params) {
+    const id = crypto.randomUUID();
+    const safePrefix = assertSafePathPrefix(params.tempPrefix, {
+        label: "sibling temp prefix",
+    });
+    const prefix = `${safePrefix}${id}-`;
+    const suffix = ".part";
+    const safeTail = fitFileNameToPortableComponent({
+        prefix,
+        fileName: sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName),
+        suffix,
+    });
+    return path.join(path.dirname(params.targetPath), `${prefix}${safeTail}${suffix}`);
+}
+export async function writeViaSiblingTempPath(params) {
+    const rootDir = await fs
+        .realpath(path.resolve(params.rootDir))
+        .catch(() => path.resolve(params.rootDir));
+    const requestedTargetPath = path.resolve(params.targetPath);
+    const targetPath = await fs
+        .realpath(path.dirname(requestedTargetPath))
+        .then((realDir) => path.join(realDir, path.basename(requestedTargetPath)))
+        .catch(() => requestedTargetPath);
+    const relativeTargetPath = path.relative(rootDir, targetPath);
+    if (!relativeTargetPath ||
+        relativeTargetPath === ".." ||
+        relativeTargetPath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeTargetPath)) {
+        throw new Error("Target path is outside the allowed root");
+    }
+    const rootGuard = await createAsyncDirectoryGuard(rootDir);
+    const workspace = await tempFile({
+        rootDir: resolveSecureTempRoot({
+            fallbackPrefix: "fs-safe-output",
+            unsafeFallbackLabel: "sibling temp output dir",
+            warn: () => undefined,
+        }),
+        prefix: "fs-safe-output",
+    });
+    try {
+        const tempPath = buildSiblingTempPath({
+            targetPath: path.join(workspace.dir, path.basename(targetPath)),
+            fallbackFileName: params.fallbackFileName ?? "output.bin",
+            tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+        });
+        await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
+        await params.writeTemp(tempPath);
+        await assertAsyncDirectoryGuard(rootGuard);
+        const targetRoot = await root(rootDir);
+        await targetRoot.copyIn(relativeTargetPath, tempPath, { mkdir: false });
+        await assertAsyncDirectoryGuard(rootGuard);
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}

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

@@ -0,0 +1,31 @@
+import { type NativeFileHandle } from "./native-operations.js";
+import type { Root } from "./root-impl.js";
+import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import type { SidecarLockAcquireOptions, SidecarLockHandle } from "./sidecar-lock-types.js";
+type SidecarFileHandle = Pick<NativeFileHandle, "close" | "stat" | "writeFile">;
+export type HeldSidecarLock = {
+    refCount: number;
+    reentrantOwner?: string;
+    handle: SidecarFileHandle;
+    lockPath: string;
+    snapshot: SidecarLockSnapshot;
+    acquiredAt: number;
+    metadata: Record<string, unknown>;
+    releasePromise?: Promise<void>;
+    lockRoot?: Root;
+    retainOnExit?: boolean;
+    parsePayload?: (raw: string) => unknown;
+    compromiseTimer?: NodeJS.Timeout;
+};
+type SidecarLockAcquisitionContext = {
+    held: Map<string, HeldSidecarLock>;
+    reclaimGuards: Set<string>;
+    ensureExitCleanupRegistered(): void;
+    handleForHeldLock(normalizedTargetPath: string, held: HeldSidecarLock): SidecarLockHandle;
+    releaseHeldLock(normalizedTargetPath: string, held: HeldSidecarLock, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+};
+export declare function acquireSidecarLock<TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>, context: SidecarLockAcquisitionContext): Promise<SidecarLockHandle>;
+export {};
+//# sourceMappingURL=sidecar-lock-acquire.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-acquire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAOA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAS3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAqBF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAqT5B"}

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

@@ -0,0 +1,336 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
+import { FsSafeError } from "./errors.js";
+import { fileObservation } from "./file-observation.js";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { openSidecarRoot } from "./sidecar-lock-root.js";
+import { createNativeExclusiveFile } from "./native-operations.js";
+import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { readSidecarLockRawSnapshot, parseSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { createSuppressedError } from "./suppressed-error.js";
+async function resolveNormalizedTargetPath(targetPath, lockRoot) {
+    const resolved = path.resolve(targetPath);
+    const dir = path.dirname(resolved);
+    if (lockRoot) {
+        // The target is an arbitration key, not necessarily inside the lock Root.
+        // Leave parent creation to the Root-backed sidecar write.
+        await lockRoot.resolve(".");
+        const parent = await canonicalPathFromExistingAncestor(dir);
+        await lockRoot.resolve(".");
+        return path.join(parent, path.basename(resolved));
+    }
+    await fs.mkdir(dir, { recursive: true });
+    try {
+        return path.join(await fs.realpath(dir), path.basename(resolved));
+    }
+    catch {
+        return resolved;
+    }
+}
+export async function acquireSidecarLock(options, context) {
+    const retry = options.retry ?? {};
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(options.timeoutMs);
+    context.ensureExitCleanupRegistered();
+    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
+    const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
+    let held = context.held.get(normalizedTargetPath);
+    if (held &&
+        options.reentrantOwner !== undefined &&
+        held.reentrantOwner !== undefined &&
+        options.reentrantOwner === held.reentrantOwner) {
+        // A final release may already have decremented the count to zero and be
+        // removing the sidecar. Do not admit a new reentrant handle until that
+        // cleanup settles: successful cleanup requires a fresh acquisition, while
+        // failed cleanup leaves the existing sidecar held for a retry.
+        if (held.releasePromise) {
+            await held.releasePromise.catch(() => undefined);
+            held = context.held.get(normalizedTargetPath);
+        }
+        if (held &&
+            options.reentrantOwner !== undefined &&
+            held.reentrantOwner !== undefined &&
+            options.reentrantOwner === held.reentrantOwner) {
+            held.refCount += 1;
+            // Retention is monotonic: any same-owner request to keep the sidecar on
+            // exit upgrades the held lock; a later default acquisition never revokes it.
+            if (options.retainOnExit === true) {
+                held.retainOnExit = true;
+            }
+            return context.handleForHeldLock(normalizedTargetPath, held);
+        }
+    }
+    const startedAt = Date.now();
+    const reclaimGuardPath = `${lockPath}.reclaim`;
+    let ownsReclaimGuard = false;
+    let attempt = 0;
+    // Bounded so a genuine denial still surfaces as EPERM, not a lock timeout.
+    let transientDenials = 0;
+    const withinDenialBudget = () => ++transientDenials <= maxTransientLockDenials;
+    const waitForRetry = async () => {
+        const elapsed = Date.now() - startedAt;
+        if ((options.timeoutMs !== undefined &&
+            options.timeoutMs !== Number.POSITIVE_INFINITY &&
+            elapsed >= options.timeoutMs) ||
+            (retry.retries !== undefined && attempt >= retry.retries)) {
+            throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+                code: "file_lock_timeout",
+                lockPath,
+                normalizedTargetPath,
+            });
+        }
+        const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
+            ? Number.POSITIVE_INFINITY
+            : Math.max(0, options.timeoutMs - elapsed);
+        const delay = Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
+        attempt += 1;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    };
+    // Waiting can fail on the caller's own retry or deadline limits. Classifying
+    // a denial as contention must not cost them the original diagnosis, so hand
+    // the denial back when no further attempt can be scheduled.
+    const retryOrRethrowDenial = async (denial) => {
+        try {
+            await waitForRetry();
+        }
+        catch (waitError) {
+            if (waitError.code === "file_lock_timeout")
+                throw denial;
+            throw waitError;
+        }
+    };
+    try {
+        while (true) {
+            if (!ownsReclaimGuard && (await sidecarReclaimGuardExists(reclaimGuardPath))) {
+                await waitForRetry();
+                continue;
+            }
+            let handle = null;
+            let createdSnapshot = null;
+            let lockFileCreateDenied = false;
+            const payload = await options.payload();
+            const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
+            try {
+                if (options.lockRoot) {
+                    const lockRoot = options.lockRoot;
+                    const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
+                    const observation = fileObservation();
+                    try {
+                        await observation.run(() => lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 }));
+                    }
+                    catch (error) {
+                        // Only this invocation's failed exclusive open grants denial retry authority.
+                        lockFileCreateDenied = observation.has(error, `exclusive-create:${lockPath}`) &&
+                            isTransientLockFileDenial(error, lockPath);
+                        if (error instanceof FsSafeError && error.code === "already-exists") {
+                            throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
+                        }
+                        throw error;
+                    }
+                    createdSnapshot = { raw, payload, ownershipToken };
+                    const opened = await openSidecarRoot(lockRoot, relativeLockPath, "unlinked");
+                    if (!opened) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    try {
+                        // Root.open admits the current file, not necessarily the one we created.
+                        const currentRaw = await readFileHandleBounded(opened.handle, Buffer.byteLength(raw));
+                        if (!currentRaw.equals(Buffer.from(raw))) {
+                            throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+                        }
+                    }
+                    catch (error) {
+                        await opened.handle.close().catch(() => undefined);
+                        throw error;
+                    }
+                    handle = opened.handle;
+                }
+                else {
+                    try {
+                        handle =
+                            (await createNativeExclusiveFile(lockPath, 0o600)) ??
+                                (await fs.open(lockPath, "wx"));
+                    }
+                    catch (createError) {
+                        lockFileCreateDenied = isTransientLockFileDenial(createError, lockPath);
+                        throw createError;
+                    }
+                    await handle.writeFile(raw, "utf8");
+                }
+                const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
+                if (snapshot.stat.nlink === 0) {
+                    await handle.close();
+                    handle = null;
+                    await waitForRetry();
+                    continue;
+                }
+                const createdHeld = {
+                    refCount: 1,
+                    reentrantOwner: options.reentrantOwner,
+                    handle,
+                    lockPath,
+                    snapshot,
+                    acquiredAt: Date.now(),
+                    metadata: options.metadata ?? {},
+                    lockRoot: options.lockRoot,
+                    retainOnExit: options.retainOnExit,
+                    parsePayload: options.parsePayload,
+                };
+                context.held.set(normalizedTargetPath, createdHeld);
+                if (ownsReclaimGuard) {
+                    try {
+                        await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
+                        ownsReclaimGuard = false;
+                    }
+                    catch (err) {
+                        await context.releaseHeldLock(normalizedTargetPath, createdHeld, { force: true });
+                        throw err;
+                    }
+                }
+                const returnedHandle = context.handleForHeldLock(normalizedTargetPath, createdHeld);
+                const interval = options.compromiseCheckIntervalMs;
+                if (options.onCompromised && interval !== undefined && interval > 0) {
+                    createdHeld.compromiseTimer = setInterval(() => {
+                        void returnedHandle
+                            .verifyStillHeld()
+                            .catch(() => false)
+                            .then((stillHeld) => {
+                            if (!stillHeld && createdHeld.compromiseTimer) {
+                                clearInterval(createdHeld.compromiseTimer);
+                                createdHeld.compromiseTimer = undefined;
+                                options.onCompromised?.({ lockPath, normalizedTargetPath });
+                            }
+                        });
+                    }, interval);
+                    createdHeld.compromiseTimer.unref();
+                }
+                return returnedHandle;
+            }
+            catch (err) {
+                try {
+                    if (handle) {
+                        const failedSnapshot = createdSnapshot ?? { payload: null };
+                        try {
+                            failedSnapshot.stat = await handle.stat();
+                        }
+                        catch {
+                            // Best-effort cleanup of a failed exclusive create.
+                        }
+                        const current = context.held.get(normalizedTargetPath);
+                        if (current?.handle === handle) {
+                            context.held.delete(normalizedTargetPath);
+                        }
+                        await handle.close().catch(() => undefined);
+                        // Root-created records retain the creator's byte/token receipt;
+                        // partial direct writes use the exclusive descriptor's identity.
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
+                    }
+                    else if (createdSnapshot) {
+                        await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
+                    }
+                }
+                catch (cleanupError) {
+                    throw createSuppressedError(cleanupError, err, "file lock acquisition and cleanup both failed");
+                }
+                if (lockFileCreateDenied && withinDenialBudget()) {
+                    await retryOrRethrowDenial(err);
+                    continue;
+                }
+                if (err.code !== "EEXIST") {
+                    throw err;
+                }
+                if (ownsReclaimGuard) {
+                    await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
+                    ownsReclaimGuard = false;
+                    await waitForRetry();
+                    continue;
+                }
+                const nowMs = Date.now();
+                let rawSnapshot;
+                let lockFileOpenDenied = false;
+                try {
+                    rawSnapshot = await readSidecarLockRawSnapshot(lockPath, {
+                        lockRoot: options.lockRoot,
+                        rejectNonFile: true,
+                        discardObservation: "changed",
+                        onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
+                    });
+                }
+                catch (readErr) {
+                    if (!lockFileOpenDenied || !withinDenialBudget())
+                        throw readErr;
+                    await retryOrRethrowDenial(readErr);
+                    continue;
+                }
+                const snapshot = parseSidecarLockSnapshot(rawSnapshot, options.parsePayload);
+                if (!snapshot) {
+                    await waitForRetry();
+                    continue;
+                }
+                if (context.held.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+                const shouldReclaim = options.shouldReclaim ?? defaultSidecarLockShouldReclaim;
+                if (await shouldReclaim({
+                    lockPath,
+                    normalizedTargetPath,
+                    payload: snapshot?.payload ?? null,
+                    staleMs: options.staleMs,
+                    nowMs,
+                    heldByThisProcess: context.held.has(normalizedTargetPath),
+                })) {
+                    if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
+                        lockRoot: options.lockRoot,
+                        parsePayload: options.parsePayload,
+                    }))) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    const staleRecovery = options.staleRecovery ?? "fail-closed";
+                    if (staleRecovery === "remove-if-unchanged") {
+                        if (!(await tryAcquireSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath))) {
+                            await waitForRetry();
+                            continue;
+                        }
+                        ownsReclaimGuard = true;
+                        const removal = await removeStaleSidecarLockIfAllowed({
+                            lockPath,
+                            normalizedTargetPath,
+                            snapshot,
+                            shouldRemoveStaleLock: options.shouldRemoveStaleLock,
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
+                        if (removal === "removed" || removal === "changed") {
+                            if (removal === "changed")
+                                await waitForRetry();
+                            continue;
+                        }
+                        await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
+                        ownsReclaimGuard = false;
+                    }
+                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                        code: "file_lock_stale",
+                        lockPath,
+                        normalizedTargetPath,
+                    });
+                }
+                await waitForRetry();
+            }
+        }
+    }
+    finally {
+        if (ownsReclaimGuard) {
+            await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath).catch(() => undefined);
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { Root } from "./root-impl.js";
+import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import type { SidecarLockHandle } from "./sidecar-lock-types.js";
+export declare function createSidecarLockHandle(params: {
+    lockPath: string;
+    normalizedTargetPath: string;
+    verifyStillHeld: () => Promise<boolean>;
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
+}): SidecarLockHandle;
+export declare function createHeldSidecarLockHandle(params: {
+    normalizedTargetPath: string;
+    held: {
+        lockPath: string;
+        snapshot: SidecarLockSnapshot;
+        lockRoot?: Root;
+        parsePayload?: (raw: string) => unknown;
+    };
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
+}): SidecarLockHandle;
+//# sourceMappingURL=sidecar-lock-handle.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-handle.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CA2BpB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IACF,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CAWpB"}