@openclaw/signal 2026.9.4 → 2026.9.6

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

@@ -0,0 +1,110 @@
+import fs, {} from "node:fs";
+export function captureSecureTempRepairAdapter(supplied, hasLegacyFsHooks) {
+    if (supplied === undefined && hasLegacyFsHooks)
+        return undefined;
+    if (supplied !== undefined && (supplied === null || (typeof supplied !== "object" && typeof supplied !== "function")))
+        return undefined;
+    const source = supplied === undefined ? fs : supplied;
+    const { lstatSync, fstatSync, openSync, fchmodSync, closeSync, constants } = source;
+    const { O_RDONLY, O_DIRECTORY, O_NOFOLLOW, O_NONBLOCK } = constants ?? {};
+    if ([lstatSync, fstatSync, openSync, fchmodSync, closeSync].some((fn) => typeof fn !== "function") ||
+        O_RDONLY !== 0 || [O_DIRECTORY, O_NOFOLLOW, O_NONBLOCK].some((flag) => !Number.isSafeInteger(flag) || flag <= 0 || flag > 0x7fff_ffff) ||
+        (O_DIRECTORY & O_NOFOLLOW) !== 0 || (O_DIRECTORY & O_NONBLOCK) !== 0 || (O_NOFOLLOW & O_NONBLOCK) !== 0) {
+        return undefined;
+    }
+    return { lstatSync, fstatSync, openSync, fchmodSync, closeSync, flags: O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK };
+}
+// Node exposes stat identity through BigInt64Array; a high OS bit can be negative.
+// Preserve raw values and existing positive adapter receipts, never normalize them.
+const MIN_NODE_STAT_IDENTITY = -(1n << 63n);
+export function secureTempDirectoryReceipt(stat, uid) {
+    const { dev, ino, uid: owner, mode } = stat;
+    if (typeof dev !== "bigint" || dev < MIN_NODE_STAT_IDENTITY ||
+        typeof ino !== "bigint" || ino < MIN_NODE_STAT_IDENTITY || ino === 0n ||
+        typeof owner !== "bigint" || owner !== BigInt(uid) || typeof mode !== "bigint" ||
+        mode < 0n || mode > 0xffffffffn || (mode & 61440n) !== 16384n ||
+        stat.isDirectory() !== true || stat.isSymbolicLink() !== false) {
+        throw new Error("Secure temp directory identity, owner, or type could not be verified.");
+    }
+    return { dev, ino, uid: owner, mode };
+}
+function assertSameDirectory(stat, expected, uid) {
+    const observed = secureTempDirectoryReceipt(stat, uid);
+    if (observed.dev !== expected.dev || observed.ino !== expected.ino || observed.uid !== expected.uid) {
+        throw new Error("Secure temp directory changed during repair.");
+    }
+    return observed;
+}
+function mayHaveConcurrentRepair(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    const code = error.code;
+    return code === "EPERM" || code === "EACCES" || code === "ENOENT";
+}
+/** No pathname chmod, search-only descriptors, procfs, or reopening fallback. */
+export function repairSecureTempDirectory(candidate, expected, uid, adapter, access, repaired, finalize = false) {
+    assertSameDirectory(adapter.lstatSync(candidate, { bigint: true }), expected, uid);
+    const fd = adapter.openSync(candidate, adapter.flags);
+    if (!Number.isSafeInteger(fd) || fd < 0)
+        throw new Error("Secure temp directory descriptor is invalid.");
+    const errors = [];
+    try {
+        const inspect = () => {
+            const opened = assertSameDirectory(adapter.fstatSync(fd, { bigint: true }), expected, uid);
+            const named = assertSameDirectory(adapter.lstatSync(candidate, { bigint: true }), expected, uid);
+            return { opened, named };
+        };
+        const verify = (requireExactMode) => {
+            const check = () => {
+                const { opened, named } = inspect();
+                for (const stat of [opened, named]) {
+                    if ((stat.mode & 18n) !== 0n || (requireExactMode && (stat.mode & 4095n) !== 448n)) {
+                        throw new Error("Secure temp directory permissions remain unsafe.");
+                    }
+                }
+            };
+            check();
+            access();
+            check();
+        };
+        const { opened } = inspect();
+        const needsChmod = finalize ? (opened.mode & 4095n) !== 448n :
+            (opened.mode & 18n) !== 0n || (opened.mode & 448n) !== 448n;
+        let chmodError;
+        let chmodFailed = false;
+        if (needsChmod) {
+            try {
+                adapter.fchmodSync(fd, 0o700);
+            }
+            catch (error) {
+                if (!mayHaveConcurrentRepair(error))
+                    throw error;
+                chmodFailed = true;
+                chmodError = error;
+            }
+            if (!chmodFailed)
+                repaired();
+        }
+        try {
+            verify(finalize || (needsChmod && !chmodFailed));
+        }
+        catch (error) {
+            if (chmodFailed)
+                throw new AggregateError([chmodError, error], "Secure temp directory chmod and verification failed.");
+            throw error;
+        }
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    try {
+        adapter.closeSync(fd);
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    if (errors.length > 1)
+        throw new AggregateError(errors, "Secure temp directory repair and close failed.");
+    if (errors.length === 1)
+        throw errors[0];
+}

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

@@ -0,0 +1,17 @@
+export declare function resolveCallbackTempPath(workspaceDir: string, component: string): string;
+export declare function writeCallbackSibling<T>(params: {
+    tempDir: string;
+    tempName: string;
+    write: (tempPath: string) => Promise<T>;
+    producerIsolation?: "private-directory";
+    resolveFinalPath: (result: T) => string;
+    mode?: number;
+    /** Preserve the caller's historical best-effort mode behavior. */
+    ignoreModeError?: boolean;
+    maxBytes?: number;
+    syncTempFile: boolean;
+    syncParentDir: boolean;
+}): Promise<{
+    filePath: string;
+    result: T;
+}>;

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

@@ -0,0 +1,301 @@
+import { syncFileBestEffort } from "./file-sync.js";
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { assertDirectoryIdentitySync, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { isWindowsReservedDeviceName } from "./device-path.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { handoffPrivateProducerFile, } from "./private-producer-handoff.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { rootFromDirectoryGuard } from "./root-impl.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+import { createOwnedTempFile } from "./temp-target.js";
+import { serializePathWrite } from "./write-queue.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const INVALID_CALLBACK_COMPONENT_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
+function resolveCallbackTempDirectory(workspaceDir) {
+    assertNoWindowsPathAlias(workspaceDir, "filesystem", "sibling temp parent uses a Windows filesystem namespace alias");
+    const dir = resolvePathPreservingWindowsRoot(workspaceDir);
+    assertNoWindowsPathAlias(dir, "filesystem", "sibling temp parent uses a Windows filesystem namespace alias");
+    return dir;
+}
+export function resolveCallbackTempPath(workspaceDir, component) {
+    const dir = resolveCallbackTempDirectory(workspaceDir);
+    if (typeof component !== "string" ||
+        component === "" ||
+        component === "." ||
+        component === ".." ||
+        INVALID_CALLBACK_COMPONENT_CHARACTERS.test(component) ||
+        component.endsWith(".") ||
+        component.endsWith(" ") ||
+        isWindowsReservedDeviceName(component)) {
+        throw new FsSafeError("invalid-path", "callback temp name must be one path component");
+    }
+    const joined = path.join(dir, component);
+    assertNoWindowsPathAlias(joined, "filesystem", "sibling temp path uses a Windows filesystem namespace alias");
+    if (path.dirname(joined) !== dir) {
+        throw new FsSafeError("invalid-path", "callback temp path must be a direct workspace child");
+    }
+    return joined;
+}
+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");
+    }
+}
+function inspectStage(inspect, expected) {
+    return inspectFileIdentitySync(() => {
+        const stat = inspect();
+        assertRegularFile(stat);
+        return stat;
+    }, expected);
+}
+function aggregateErrors(errors, message) {
+    if (errors.length === 1)
+        return errors[0];
+    return new AggregateError(errors, message);
+}
+// Own the workspace before the producer can leave partial output. The finished
+// file still enters the ordinary sibling admission and publication lifecycle.
+async function writeIsolatedProducer(params) {
+    const { tempPath, write, writeReceiver, parentGuard, assertParent, syncTempFile } = params;
+    assertParent();
+    const targetRoot = rootFromDirectoryGuard(parentGuard);
+    // Select the handoff before invoking the producer. Missing required native
+    // support must not leave producer output behind as a discovery side effect.
+    const native = getNativeBinding();
+    const cleanupErrors = [];
+    const { target, identity } = await createOwnedTempFile({
+        rootDir: targetRoot.rootReal,
+        prefix: "fs-safe-output",
+        fileName: path.basename(tempPath),
+        onCleanupError: (error) => cleanupErrors.push(error),
+    });
+    let cleanupStarted = false;
+    const cleanupWorkspace = async () => {
+        if (cleanupStarted)
+            return;
+        cleanupStarted = true;
+        try {
+            await target.cleanup();
+        }
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+        if (cleanupErrors.length > 0) {
+            throw aggregateErrors(cleanupErrors, "isolated producer workspace cleanup failed");
+        }
+    };
+    const assertWorkspace = () => {
+        assertDirectoryIdentitySync(target.dir, { ...identity, realPath: target.dir });
+    };
+    const assertCurrent = () => {
+        assertParent();
+        assertWorkspace();
+    };
+    try {
+        const producerPath = resolveCallbackTempPath(target.dir, path.basename(target.path));
+        assertCurrent();
+        const result = await Reflect.apply(write, writeReceiver, [producerPath]);
+        assertCurrent();
+        if (native) {
+            await targetRoot.move(path.relative(targetRoot.rootReal, producerPath), path.basename(tempPath), { assertBeforeMutation: assertCurrent });
+            return { cleanupWorkspace, result };
+        }
+        const handoff = await handoffPrivateProducerFile({
+            sourcePath: producerPath,
+            targetPath: tempPath,
+            assertSourceParent: assertWorkspace,
+            assertTargetParent: assertParent,
+            readWrite: syncTempFile,
+        });
+        return { cleanupWorkspace, handoff, result };
+    }
+    catch (error) {
+        try {
+            await cleanupWorkspace();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "isolated producer operation and workspace cleanup failed");
+        }
+        throw error;
+    }
+}
+// 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 = resolveCallbackTempDirectory(params.tempDir);
+    const tempPath = resolveCallbackTempPath(parent, params.tempName);
+    const write = params.write;
+    const producerIsolation = params.producerIsolation;
+    const resolveFinalPath = params.resolveFinalPath;
+    const mode = params.mode;
+    const ignoreModeError = params.ignoreModeError;
+    const maxBytes = params.maxBytes;
+    const syncTempFile = params.syncTempFile;
+    const syncParentDir = params.syncParentDir;
+    const guard = await createAsyncDirectoryGuard(parent, { bigint: true });
+    const assertParent = () => assertDirectoryIdentitySync(parent, {
+        dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath,
+    });
+    let handle;
+    let identity;
+    let unregister;
+    let cleanupWorkspace;
+    let renamed = false;
+    let failure;
+    const inspectPath = (pathname, expected) => inspectStage(() => fsSync.lstatSync(pathname, { bigint: true }), expected);
+    const assertCurrent = (pathname) => {
+        assertParent();
+        const opened = inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
+        const current = inspectPath(pathname, opened);
+        if (maxBytes !== undefined &&
+            (opened.size > maxBytes || current.size > maxBytes)) {
+            throw new FsSafeError("too-large", `sibling temp exceeds maxBytes (${maxBytes})`);
+        }
+    };
+    try {
+        let result;
+        if (producerIsolation === "private-directory") {
+            const isolated = await writeIsolatedProducer({
+                tempPath: tempPath,
+                write,
+                writeReceiver: params,
+                parentGuard: guard,
+                syncTempFile: syncTempFile,
+                assertParent,
+            });
+            result = isolated.result;
+            cleanupWorkspace = isolated.cleanupWorkspace;
+            if (isolated.handoff) {
+                handle = isolated.handoff.handle;
+                identity = isolated.handoff.identity;
+                unregister = isolated.handoff.unregister;
+            }
+        }
+        else {
+            result = await Reflect.apply(write, params, [tempPath]);
+        }
+        assertParent();
+        let expected = identity;
+        if (!handle) {
+            expected = inspectPath(tempPath);
+            try {
+                // No create/truncate flags; O_NONBLOCK also bounds a FIFO swap during open.
+                const access = syncTempFile ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
+                handle = await fs.open(tempPath, access | resolveReadOpenFlags());
+            }
+            catch (error) {
+                if (error?.code === "ELOOP") {
+                    throw new FsSafeError("symlink", "symlink sibling temp not allowed", { cause: error });
+                }
+                throw error;
+            }
+        }
+        const opened = inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
+        inspectPath(tempPath, opened);
+        if (!identity) {
+            identity = opened;
+            unregister = registerTempPathForExit(tempPath, { identity, singleLinkFile: true });
+        }
+        assertParent();
+        if (cleanupWorkspace) {
+            const cleanup = cleanupWorkspace;
+            cleanupWorkspace = undefined;
+            await cleanup();
+        }
+        const rawFilePath = Reflect.apply(resolveFinalPath, params, [result]);
+        assertNoWindowsPathAlias(rawFilePath, "filesystem", "final path uses a Windows filesystem namespace alias");
+        const filePath = path.resolve(rawFilePath);
+        assertNoWindowsPathAlias(filePath, "filesystem", "final path uses a Windows filesystem namespace alias");
+        if (path.dirname(filePath) !== parent) {
+            throw new Error("Final path must be in the sibling temp directory.");
+        }
+        if (filePath === tempPath) {
+            throw new FsSafeError("invalid-path", "final path must differ from the sibling temp path");
+        }
+        await serializePathWrite(filePath, async () => {
+            assertCurrent(tempPath);
+            if (mode !== undefined) {
+                try {
+                    await handle.chmod(mode);
+                }
+                catch (error) {
+                    if (!ignoreModeError)
+                        throw error;
+                }
+                assertCurrent(tempPath);
+            }
+            if (syncTempFile) {
+                await syncFileBestEffort(handle);
+                assertCurrent(tempPath);
+            }
+            await fs.rename(tempPath, filePath);
+            // A later verification failure never authorizes rollback of the final name.
+            renamed = true;
+            unregister();
+            assertCurrent(filePath);
+            if (syncParentDir) {
+                await syncDirectoryBestEffort(parent);
+                assertCurrent(filePath);
+            }
+        });
+        return { filePath, result };
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        const settlementErrors = [];
+        if (cleanupWorkspace) {
+            try {
+                await cleanupWorkspace();
+            }
+            catch (error) {
+                settlementErrors.push(error);
+            }
+        }
+        try {
+            if (!renamed && identity) {
+                try {
+                    assertParent();
+                    inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
+                    inspectPath(tempPath, identity);
+                    await fs.unlink(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) {
+                settlementErrors.push(error);
+            }
+            if (settlementErrors.length > 0) {
+                if (failure) {
+                    throw new AggregateError([failure.error, ...settlementErrors], "sibling publication and settlement failed");
+                }
+                throw aggregateErrors(settlementErrors, "sibling publication settlement failed");
+            }
+        }
+    }
+}

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

@@ -0,0 +1,28 @@
+export type WriteSiblingTempFileOptions<T> = {
+    dir: string;
+    writeTemp: (tempPath: string) => Promise<T>;
+    /** Own a private sibling workspace before invoking the producer. */
+    producerIsolation?: "private-directory";
+    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>;

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

@@ -0,0 +1,132 @@
+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 { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { root } from "./root.js";
+import { assertSafePathPrefix } from "./safe-path-segment.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { resolveCallbackTempPath, writeCallbackSibling } from "./sibling-staged-file.js";
+import { tempFile } from "./temp-target.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function buildTempName(tempPrefix) {
+    const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-stream", {
+        label: "sibling temp prefix",
+    });
+    return `${safePrefix}.${process.pid}.${randomUUID()}.tmp`;
+}
+export async function writeSiblingTempFile(options) {
+    const dirInput = options.dir;
+    assertNoWindowsPathAlias(dirInput, "filesystem", "sibling temp directory uses a Windows filesystem namespace alias");
+    const dir = resolvePathPreservingWindowsRoot(dirInput);
+    assertNoWindowsPathAlias(dir, "filesystem", "sibling temp directory uses a Windows filesystem namespace alias");
+    const producerIsolation = options.producerIsolation;
+    const dirMode = options.dirMode ?? 0o700;
+    const chmodDir = options.chmodDir !== false;
+    const tempPrefix = options.tempPrefix;
+    const writeTemp = options.writeTemp;
+    const resolveFinalPath = options.resolveFinalPath;
+    const mode = options.mode;
+    const syncTempFile = options.syncTempFile === true;
+    const syncParentDir = options.syncParentDir === true;
+    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true, mode: dirMode });
+    if (chmodDir) {
+        await applyDirectoryMode({
+            fsModule: fs,
+            dirPath: dir,
+            mode: dirMode,
+            ignoreChmodError: true,
+        });
+    }
+    return await writeCallbackSibling({
+        tempDir: dir,
+        tempName: buildTempName(tempPrefix),
+        write: writeTemp,
+        producerIsolation,
+        resolveFinalPath,
+        mode,
+        ignoreModeError: true,
+        syncTempFile,
+        syncParentDir,
+    });
+}
+function buildSiblingTempName(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 `${prefix}${safeTail}${suffix}`;
+}
+export async function writeViaSiblingTempPath(params) {
+    const rootDirInput = params.rootDir;
+    const targetPathInput = params.targetPath;
+    assertNoWindowsPathAlias(rootDirInput, "filesystem", "sibling temp root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(targetPathInput, "filesystem", "sibling temp target uses a Windows filesystem namespace alias");
+    let rootDir;
+    try {
+        rootDir = realpathSync.native(resolvePathPreservingWindowsRoot(rootDirInput));
+    }
+    catch {
+        rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+    }
+    assertNoWindowsPathAlias(rootDir, "filesystem", "sibling temp root uses a Windows filesystem namespace alias");
+    const requestedTargetPath = path.resolve(targetPathInput);
+    assertNoWindowsPathAlias(requestedTargetPath, "filesystem", "sibling temp target uses a Windows filesystem namespace alias");
+    let targetPath;
+    try {
+        const realDir = realpathSync.native(path.dirname(requestedTargetPath));
+        targetPath = path.join(realDir, path.basename(requestedTargetPath));
+    }
+    catch {
+        targetPath = requestedTargetPath;
+    }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "sibling temp target uses a Windows filesystem namespace alias");
+    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 writeTemp = params.writeTemp;
+    const fallbackFileName = params.fallbackFileName;
+    const tempPrefix = params.tempPrefix;
+    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",
+    });
+    assertNoWindowsPathAlias(workspace.dir, "filesystem", "sibling temp workspace uses a Windows filesystem namespace alias");
+    try {
+        const tempName = buildSiblingTempName({
+            targetPath: path.join(workspace.dir, path.basename(targetPath)),
+            fallbackFileName: fallbackFileName ?? "output.bin",
+            tempPrefix: tempPrefix ?? ".fs-safe-output-",
+        });
+        const tempPath = resolveCallbackTempPath(workspace.dir, tempName);
+        await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
+        await Function.prototype.call.call(writeTemp, params, 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,4 @@
+import type { SidecarLockAcquireOptions, SidecarLockHandle } from "./sidecar-lock-types.js";
+import type { SidecarLockAcquisitionContext } from "./sidecar-lock-admission.js";
+export type { HeldSidecarLock } from "./sidecar-lock-admission.js";
+export declare function acquireSidecarLock<TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>, context: SidecarLockAcquisitionContext): Promise<SidecarLockHandle>;