@openclaw/signal 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/guarded-mkdir.js

@@ -0,0 +1,281 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createDirectoryWithAdmission } from "./create.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { hasNodeErrorCode, isNotFoundPathError, isPathRelativeEscape } from "./path.js";
+import { directoryComponentNotDirectoryError, rootPathChangedError } from "./root-errors.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { checkedMutationDirectory } from "./pinned-mutation-observation.js";
+import { createPathSegmentRoute, joinPathSegmentRoute, } from "./path-segment-route.js";
+function sameDirectoryFacts(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+function isDirectoryCollision(error) {
+    return hasNodeErrorCode(error, "EEXIST") ||
+        (error instanceof FsSafeError && error.code === "already-exists");
+}
+function inspectGuardCurrent(parent) {
+    const stat = inspectDirectoryIdentitySync(parent.dir, parent.stat);
+    if (realpathSync.native(parent.dir) !== parent.realPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+    return stat;
+}
+function observedGuard(parent) {
+    return checkedMutationDirectory(parent.dir, parent.realPath, parent.stat);
+}
+function createdDirectoryEvidence(admission, parent, childPath) {
+    try {
+        const parentAfter = inspectGuardCurrent(parent);
+        const childBefore = inspectDirectoryIdentitySync(childPath);
+        const realPath = realpathSync.native(childPath);
+        if (realPath !== childPath)
+            return undefined;
+        const childAfter = inspectDirectoryIdentitySync(childPath, childBefore);
+        if (!sameDirectoryFacts(childBefore, childAfter))
+            return undefined;
+        const child = checkedMutationDirectory(childPath, realPath, childAfter);
+        const receipt = Object.freeze({
+            admission,
+            parent: checkedMutationDirectory(parent.dir, parent.realPath, parentAfter),
+            child,
+        });
+        return Object.freeze({
+            receipt,
+            guard: Object.freeze({ dir: childPath, realPath, stat: childAfter }),
+        });
+    }
+    catch {
+        // Failed optional evidence leaves the existing ordered admission in charge.
+        return undefined;
+    }
+}
+function sameAbsolutePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+function suppliedExactRootIdentity(identity) {
+    return typeof identity?.dev === "bigint" && typeof identity.ino === "bigint"
+        ? { dev: identity.dev, ino: identity.ino }
+        : undefined;
+}
+function assertGuardMatchesRootIdentity(guard, expected) {
+    if (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino) {
+        throw rootPathChangedError();
+    }
+}
+function isPromiseLike(value) {
+    return typeof value?.then === "function";
+}
+async function realpathOrThrowNotFile(target) {
+    try {
+        const canonical = realpathSync.native(pathForWindowsFilesystem(target));
+        assertNoWindowsPathAlias(canonical, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
+        return resolvePathPreservingWindowsRoot(canonical);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            // A dangling symlink (or a component removed between lstat and
+            // realpath) is not a usable directory component.
+            throw directoryComponentNotDirectoryError(error instanceof Error ? error : undefined);
+        }
+        throw error;
+    }
+}
+/**
+ * Creates each missing path component from `rootReal` down to `targetPath`,
+ * guarding every step. Returns the real (symlink-resolved) path of the final
+ * component so callers can guard/use that path directly instead of
+ * re-deriving it from the original, possibly-symlinked, lexical path.
+ */
+export async function mkdirPathComponentsWithGuards(params) {
+    const rawRootReal = params.rootReal;
+    assertNoWindowsPathAlias(rawRootReal, "filesystem", "root directory uses a Windows filesystem namespace alias");
+    const rawTargetPath = params.targetPath;
+    assertNoWindowsPathAlias(rawTargetPath, "filesystem", "target directory uses a Windows filesystem namespace alias");
+    const root = resolvePathPreservingWindowsRoot(rawRootReal);
+    const target = resolvePathPreservingWindowsRoot(rawTargetPath);
+    const suppliedIdentity = suppliedExactRootIdentity(params.rootIdentity);
+    const configuredRootGuard = await createAsyncDirectoryGuard(root, { bigint: true });
+    const checkedRootIdentity = suppliedIdentity ?? {
+        dev: configuredRootGuard.stat.dev,
+        ino: configuredRootGuard.stat.ino,
+    };
+    assertGuardMatchesRootIdentity(configuredRootGuard, checkedRootIdentity);
+    assertNoWindowsPathAlias(configuredRootGuard.realPath);
+    const rootCanonical = resolvePathPreservingWindowsRoot(configuredRootGuard.realPath);
+    const rootGuard = rootCanonical === root
+        ? configuredRootGuard
+        : await createAsyncDirectoryGuard(rootCanonical, { bigint: true });
+    assertGuardMatchesRootIdentity(rootGuard, checkedRootIdentity);
+    const admissionParams = {
+        candidatePath: target,
+        rootIdentity: checkedRootIdentity,
+    };
+    // Derive the suffix from the caller's trusted root spelling first. The
+    // canonical spelling is also accepted after both names have been bound to
+    // the same exact root object above.
+    const admittedTarget = admitPathInsideRoot({ rootPath: root, ...admissionParams }) ??
+        (rootCanonical === root
+            ? undefined
+            : admitPathInsideRoot({ rootPath: rootCanonical, ...admissionParams }));
+    if (!admittedTarget || isPathRelativeEscape(admittedTarget.relativePath)) {
+        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
+    }
+    let current = rootCanonical;
+    let currentGuard = rootGuard;
+    const parts = admittedTarget.relativePath.split(path.sep).filter(Boolean);
+    let partRoute;
+    let retainedTargetPath = params.retainedTargetPath &&
+        sameAbsolutePath(path.dirname(params.retainedTargetPath), target)
+        ? params.retainedTargetPath
+        : undefined;
+    let retainedParentPath = retainedTargetPath ? path.dirname(retainedTargetPath) : undefined;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        const next = path.join(current, part);
+        const parentGuard = currentGuard;
+        assertNoWindowsPathAlias(parentGuard.realPath, "filesystem", "canonical parent directory uses a Windows filesystem namespace alias");
+        let created = false;
+        let createReceipt;
+        if (!params.revalidateParentAfterBeforeComponent) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        await params.beforeComponent?.(next);
+        if (params.revalidateParentAfterBeforeComponent) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        let shouldCreate = true;
+        if (params.beforeCreateComponent) {
+            let missing = false;
+            try {
+                fsSync.lstatSync(next);
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                missing = true;
+            }
+            shouldCreate = missing;
+            if (missing) {
+                let prospectiveParent = retainedParentPath;
+                if (!prospectiveParent) {
+                    partRoute ??= createPathSegmentRoute(parts);
+                    prospectiveParent = joinPathSegmentRoute(next, partRoute, index + 1);
+                }
+                const authorization = params.beforeCreateComponent(next, prospectiveParent, retainedTargetPath, observedGuard(parentGuard));
+                if (isPromiseLike(authorization)) {
+                    createReceipt = await authorization;
+                    await assertAsyncDirectoryGuard(parentGuard);
+                }
+                else {
+                    createReceipt = authorization;
+                    // A synchronous authorization must still end at a live pathname
+                    // fence immediately before the authority callback and mkdir.
+                    if (!params.synchronousAuthorizationIncludesFence)
+                        inspectGuardCurrent(parentGuard);
+                }
+            }
+        }
+        if (shouldCreate) {
+            params.assertBeforeMutation?.();
+            // Both policy and ordinary mkdir must renew the parent after callbacks.
+            inspectGuardCurrent(parentGuard);
+            try {
+                if (params.private) {
+                    await createDirectoryWithAdmission(next, {
+                        private: true,
+                        mode: params.mode,
+                        assertBeforeMutation: params.assertBeforeMutation,
+                    }, {
+                        expectedParentIdentity: {
+                            dev: parentGuard.stat.dev, ino: parentGuard.stat.ino, realPath: parentGuard.realPath,
+                        },
+                    });
+                }
+                else {
+                    await fs.mkdir(next, { mode: params.mode });
+                }
+                created = true;
+            }
+            catch (error) {
+                if (!isDirectoryCollision(error))
+                    throw error;
+            }
+        }
+        let createdAuthorization;
+        let createdEvidence;
+        if (created && createReceipt && params.afterCreateComponent) {
+            createdEvidence = createdDirectoryEvidence(createReceipt, parentGuard, next);
+            if (createdEvidence) {
+                createdAuthorization = params.afterCreateComponent(createdEvidence.receipt);
+            }
+        }
+        if (params.beforeUseComponent && !createdAuthorization) {
+            let prospectiveParent = retainedParentPath;
+            if (!prospectiveParent) {
+                partRoute ??= createPathSegmentRoute(parts);
+                prospectiveParent = joinPathSegmentRoute(next, partRoute, index + 1);
+            }
+            await params.beforeUseComponent(next, prospectiveParent, retainedTargetPath);
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        const stat = createdAuthorization ? undefined : fsSync.lstatSync(next);
+        if (stat && ((params.rejectSymlinks && stat.isSymbolicLink()) ||
+            (!stat.isSymbolicLink() && !stat.isDirectory()))) {
+            throw directoryComponentNotDirectoryError();
+        }
+        // Node's recursive mkdir follows symlinks in missing components. Build one
+        // segment at a time and realpath-check each segment before descending.
+        const nextReal = createdAuthorization && createdEvidence
+            ? createdEvidence.receipt.child.canonicalPath
+            : await realpathOrThrowNotFile(next);
+        const admittedNextReal = admitPathInsideRoot({
+            rootPath: rootCanonical,
+            candidatePath: nextReal,
+            rootIdentity: checkedRootIdentity,
+        });
+        if (!admittedNextReal) {
+            throw new FsSafeError("outside-workspace", "directory escaped workspace root");
+        }
+        const admittedNextPath = admittedNextReal.path;
+        if (stat?.isSymbolicLink()) {
+            // An existing path component may legitimately be a symlink to a real
+            // directory inside the root (e.g. a skill-bank layout). We already
+            // verified above that it resolves inside the root, so treat the
+            // resolved real path as the directory for the rest of this walk
+            // instead of rejecting it outright. Guard checks from here on operate
+            // on the real (non-symlink) path, preserving TOCTOU protection for
+            // every subsequent segment. Callers that need the final directory
+            // (e.g. to guard it themselves after this function returns) must use
+            // the returned resolved path, not their own lexical parent path.
+            const targetStat = fsSync.statSync(admittedNextPath);
+            if (!targetStat.isDirectory()) {
+                throw directoryComponentNotDirectoryError();
+            }
+            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+            assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
+            await assertAsyncDirectoryGuard(parentGuard);
+            retainedTargetPath = undefined;
+            retainedParentPath = undefined;
+            current = admittedNextPath;
+            continue;
+        }
+        if (createdAuthorization && createdEvidence) {
+            currentGuard = createdEvidence.guard;
+        }
+        else {
+            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+        }
+        assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
+        if (!createdAuthorization || !createdEvidence) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        current = admittedNextPath;
+    }
+    return current;
+}

package/node_modules/@openclaw/fs-safe/dist/guarded-mutation.d.ts

@@ -0,0 +1,32 @@
+import { type BigIntStats } from "node:fs";
+import { type AnyAsyncDirectoryGuard, type SyncDirectoryGuard } from "./directory-guard.js";
+export declare function withAsyncDirectoryGuards<T>(guards: readonly AnyAsyncDirectoryGuard[], mutate: () => Promise<T>, options?: {
+    verifyAfter?: boolean;
+    onPostGuardFailure?: (result: T, error: unknown) => Promise<void> | void;
+}): Promise<T>;
+export declare function withSyncDirectoryGuards<T>(guards: readonly SyncDirectoryGuard[], mutate: () => T, options?: {
+    verifyAfter?: boolean;
+}): T;
+export declare function guardedRename(params: {
+    assertBeforeRename?: () => void;
+    onSourceInspected?: (identity: Pick<BigIntStats, "dev" | "ino">) => void;
+    onRenamed?: () => void;
+    from: string;
+    to: string;
+}): Promise<void>;
+export declare function guardedRenameSync(params: {
+    from: string;
+    to: string;
+}): void;
+export declare function guardedRm(params: {
+    target: string;
+    assertBeforeMutation?: () => void;
+    recursive?: boolean;
+}): Promise<void>;
+export declare function guardedRmSync(params: {
+    target: string;
+    assertBeforeMutation?: () => void;
+    recursive?: boolean;
+    force?: boolean;
+    verifyAfter?: boolean;
+}): void;

package/node_modules/@openclaw/fs-safe/dist/guarded-mutation.js

@@ -0,0 +1,81 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createSyncDirectoryGuard, } from "./directory-guard.js";
+export async function withAsyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        await assertAsyncDirectoryGuard(guard);
+    }
+    const result = await mutate();
+    if (options.verifyAfter !== false) {
+        try {
+            for (const guard of guards) {
+                await assertAsyncDirectoryGuard(guard);
+            }
+        }
+        catch (error) {
+            if (options.onPostGuardFailure) {
+                try {
+                    // The mutation may have returned an owned resource before the post-guard
+                    // check detected a swapped directory. Give callers one chance to close
+                    // handles without letting cleanup hide the boundary failure.
+                    await options.onPostGuardFailure(result, error);
+                }
+                catch {
+                    // Preserve the boundary failure. Cleanup is best-effort.
+                }
+            }
+            throw error;
+        }
+    }
+    return result;
+}
+export function withSyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        assertSyncDirectoryGuard(guard);
+    }
+    const result = mutate();
+    if (options.verifyAfter !== false) {
+        for (const guard of guards) {
+            assertSyncDirectoryGuard(guard);
+        }
+    }
+    return result;
+}
+export async function guardedRename(params) {
+    const sourceGuard = await createAsyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = await createAsyncDirectoryGuard(path.dirname(params.to));
+    await withAsyncDirectoryGuards([sourceGuard, targetGuard], async () => {
+        if (params.onSourceInspected) {
+            params.onSourceInspected(fsSync.lstatSync(params.from, { bigint: true }));
+        }
+        // Authority must survive all awaited guards; do not yield before rename dispatch.
+        params.assertBeforeRename?.();
+        await fs.rename(params.from, params.to);
+        params.onRenamed?.();
+    });
+}
+export function guardedRenameSync(params) {
+    const sourceGuard = createSyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = createSyncDirectoryGuard(path.dirname(params.to));
+    withSyncDirectoryGuards([sourceGuard, targetGuard], () => fsSync.renameSync(params.from, params.to));
+}
+export async function guardedRm(params) {
+    const guard = await createAsyncDirectoryGuard(path.dirname(params.target));
+    await withAsyncDirectoryGuards([guard], async () => {
+        params.assertBeforeMutation?.();
+        await fs.rm(params.target, {
+            ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+        });
+    });
+}
+export function guardedRmSync(params) {
+    const guard = createSyncDirectoryGuard(path.dirname(params.target));
+    withSyncDirectoryGuards([guard], () => {
+        params.assertBeforeMutation?.();
+        fsSync.rmSync(params.target, {
+            ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+            ...(params.force !== undefined ? { force: params.force } : {}),
+        });
+    }, { verifyAfter: params.verifyAfter });
+}

package/node_modules/@openclaw/fs-safe/dist/guest-dispatch-python.d.ts

@@ -0,0 +1 @@
+export declare const GUEST_FILESYSTEM_DISPATCH_PYTHON: string;

package/node_modules/@openclaw/fs-safe/dist/guest-dispatch-python.js

@@ -0,0 +1,68 @@
+export const GUEST_FILESYSTEM_DISPATCH_PYTHON = [
+    "if operation in ('copy', 'rename'):",
+    "    src_root_fd = open_dir(sys.argv[2])",
+    "    dst_root_fd = open_dir(sys.argv[5])",
+    "    src_parent_fd = None",
+    "    dst_parent_fd = None",
+    "    try:",
+    "        src_parent_fd = walk_dir(src_root_fd, sys.argv[3], False)",
+    "        dst_parent_fd = walk_dir(dst_root_fd, sys.argv[6], sys.argv[8] == '1')",
+    "        if operation == 'copy':",
+    "            copy_file_atomic(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
+    "        else:",
+    "            move_entry(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
+    "    finally:",
+    "        if src_parent_fd is not None:",
+    "            os.close(src_parent_fd)",
+    "        if dst_parent_fd is not None:",
+    "            os.close(dst_parent_fd)",
+    "        os.close(src_root_fd)",
+    "        os.close(dst_root_fd)",
+    "elif operation in ('write', 'create', 'read', 'readdir', 'mkdirp', 'remove'):",
+    "    root_fd = open_dir(sys.argv[2])",
+    "    parent_fd = None",
+    "    try:",
+    "        mkdir_enabled = operation == 'mkdirp' or (operation in ('write', 'create') and sys.argv[5] == '1')",
+    "        parent_fd = walk_dir(root_fd, sys.argv[3], mkdir_enabled)",
+    "        if operation == 'write':",
+    "            write_atomic(parent_fd, sys.argv[4], sys.stdin.buffer)",
+    "        elif operation == 'create':",
+    "            try:",
+    "                create_exclusive(parent_fd, sys.argv[4], sys.stdin.buffer)",
+    "            except FileExistsError:",
+    "                sys.exit(SANDBOX_CREATE_EXISTS_EXIT_CODE)",
+    "        elif operation == 'read':",
+    "            if len(sys.argv) > 5:",
+    "                read_file_bounded(parent_fd, sys.argv[4], int(sys.argv[5]))",
+    "            else:",
+    "                read_file(parent_fd, sys.argv[4])",
+    "        elif operation == 'readdir':",
+    "            with os.scandir(parent_fd) as entries:",
+    "                print(json.dumps([{'name': entry.name, 'isDirectory': entry.is_dir(follow_symlinks=False), 'isFile': entry.is_file(follow_symlinks=False)} for entry in entries]))",
+    "        elif operation == 'mkdirp':",
+    "            os.fsync(parent_fd)",
+    "        elif operation == 'remove':",
+    "            try:",
+    "                if sys.argv[5] == '1':",
+    "                    remove_tree(parent_fd, sys.argv[4])",
+    "                else:",
+    "                    entry_stat = os.lstat(sys.argv[4], dir_fd=parent_fd)",
+    "                    if stat.S_ISDIR(entry_stat.st_mode) and not stat.S_ISLNK(entry_stat.st_mode):",
+    "                        os.rmdir(sys.argv[4], dir_fd=parent_fd)",
+    "                    else:",
+    "                        os.unlink(sys.argv[4], dir_fd=parent_fd)",
+    "                os.fsync(parent_fd)",
+    "            except FileNotFoundError:",
+    "                if sys.argv[6] != '1':",
+    "                    raise",
+    "    except FileNotFoundError:",
+    "        if operation == 'read':",
+    "            sys.exit(SANDBOX_READ_NOT_FOUND_EXIT_CODE)",
+    "        raise",
+    "    finally:",
+    "        if parent_fd is not None:",
+    "            os.close(parent_fd)",
+    "        os.close(root_fd)",
+    "else:",
+    "    raise RuntimeError('unknown sandbox mutation operation: ' + operation)",
+].join("\n");

package/node_modules/@openclaw/fs-safe/dist/guest-native-python.d.ts

@@ -0,0 +1,3 @@
+export declare const GUEST_FILESYSTEM_CREATE_STAGING_PYTHON: string;
+export declare const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON: string;
+export declare const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON: string;

package/node_modules/@openclaw/fs-safe/dist/guest-native-python.js

@@ -0,0 +1,135 @@
+export const GUEST_FILESYSTEM_CREATE_STAGING_PYTHON = [
+    "def create_staging_dir(parent_fd):",
+    "    # This helper guarantees descriptor-relative confinement and no-replace",
+    "    # publication, not content integrity against same-UID peers; they can",
+    "    # also rewrite the destination immediately after publication.",
+    "    prefix = '.openclaw-create-'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6)",
+    "        try:",
+    "            os.mkdir(candidate, 0o700, dir_fd=parent_fd)",
+    "        except FileExistsError:",
+    "            continue",
+    "        created_identity = entry_identity(os.lstat(candidate, dir_fd=parent_fd))",
+    "        staging_fd = None",
+    "        try:",
+    "            staging_fd = open_dir(candidate, dir_fd=parent_fd)",
+    "            if not same_identity(created_identity, os.fstat(staging_fd)):",
+    "                raise OSError(errno.ESTALE, 'create staging directory changed', candidate)",
+    "            return candidate, staging_fd",
+    "        except Exception:",
+    "            if staging_fd is not None:",
+    "                os.close(staging_fd)",
+    "            try:",
+    "                current = os.lstat(candidate, dir_fd=parent_fd)",
+    "                if same_identity(created_identity, current):",
+    "                    os.rmdir(candidate, dir_fd=parent_fd)",
+    "                    os.fsync(parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            raise",
+    "    raise RuntimeError('failed to allocate sandbox create staging directory')",
+].join("\n");
+export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
+    "def rename_no_replace(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    libc = ctypes.CDLL(None, use_errno=True)",
+    "    is_linux = sys.platform.startswith('linux')",
+    "    if is_linux:",
+    "        rename_fn = getattr(libc, 'renameat2', None)",
+    "        if rename_fn is None:",
+    "            os.link(",
+    "                src_basename,",
+    "                dst_basename,",
+    "                src_dir_fd=src_parent_fd,",
+    "                dst_dir_fd=dst_parent_fd,",
+    "                follow_symlinks=False,",
+    "            )",
+    "            return",
+    "        flags = 1  # RENAME_NOREPLACE",
+    "    elif sys.platform == 'darwin':",
+    "        rename_fn = getattr(libc, 'renameatx_np', None)",
+    "        flags = 0x00000004  # RENAME_EXCL",
+    "    else:",
+    "        rename_fn = None",
+    "        flags = 0",
+    "    if rename_fn is None:",
+    "        raise OSError(errno.ENOSYS, 'atomic no-replace rename is unavailable')",
+    "    rename_fn.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]",
+    "    rename_fn.restype = ctypes.c_int",
+    "    result = rename_fn(",
+    "        src_parent_fd,",
+    "        os.fsencode(src_basename),",
+    "        dst_parent_fd,",
+    "        os.fsencode(dst_basename),",
+    "        flags,",
+    "    )",
+    "    if result != 0:",
+    "        error_code = ctypes.get_errno()",
+    "        unsupported_codes = {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP}",
+    "        if hasattr(errno, 'EOPNOTSUPP'):",
+    "            unsupported_codes.add(errno.EOPNOTSUPP)",
+    "        if is_linux and error_code in unsupported_codes:",
+    "            os.link(",
+    "                src_basename,",
+    "                dst_basename,",
+    "                src_dir_fd=src_parent_fd,",
+    "                dst_dir_fd=dst_parent_fd,",
+    "                follow_symlinks=False,",
+    "            )",
+    "            return",
+    "        raise OSError(error_code, os.strerror(error_code), dst_basename)",
+].join("\n");
+export const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON = [
+    "def create_exclusive(parent_fd, basename, stdin_buffer):",
+    "    staging_fd = None",
+    "    staging_name = None",
+    "    temp_fd = None",
+    "    temp_name = 'payload'",
+    "    temp_inode = None",
+    "    try:",
+    "        try:",
+    "            os.lstat(basename, dir_fd=parent_fd)",
+    "        except FileNotFoundError:",
+    "            pass",
+    "        else:",
+    "            raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), basename)",
+    "        staging_name, staging_fd = create_staging_dir(parent_fd)",
+    "        temp_fd = os.open(temp_name, WRITE_FLAGS, 0o600, dir_fd=staging_fd)",
+    "        while True:",
+    "            chunk = stdin_buffer.read(65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(temp_fd, chunk)",
+    "        # exclusive create payload is durable before publication",
+    "        os.fsync(temp_fd)",
+    "        temp_inode = inode_identity(os.fstat(temp_fd))",
+    "        # Publish with a native atomic no-replace rename.",
+    "        rename_no_replace(staging_fd, temp_name, parent_fd, basename)",
+    "        target_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "        if temp_inode != inode_identity(target_stat):",
+    "            raise OSError(errno.ESTALE, 'exclusive publication source changed', basename)",
+    "        os.fsync(parent_fd)",
+    "    finally:",
+    "        if temp_fd is not None:",
+    "            os.close(temp_fd)",
+    "        if staging_fd is not None:",
+    "            # Cleanup stays relative to the private pinned directory, so a",
+    "            # parent-path substitution cannot redirect payload deletion.",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=staging_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            staging_identity = entry_identity(os.fstat(staging_fd))",
+    "            os.close(staging_fd)",
+    "            staging_removed = False",
+    "            if staging_name is not None:",
+    "                try:",
+    "                    current_staging = os.lstat(staging_name, dir_fd=parent_fd)",
+    "                    if same_identity(staging_identity, current_staging):",
+    "                        os.rmdir(staging_name, dir_fd=parent_fd)",
+    "                        staging_removed = True",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            if staging_removed:",
+    "                os.fsync(parent_fd)",
+].join("\n");

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

@@ -0,0 +1,8 @@
+import { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON } from "./guest-native-python.js";
+/** Exclusive create found an existing destination, including a lost publication race. */
+export declare const GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE = 17;
+/** Read found a missing parent or file after the admitted root was opened. */
+export declare const GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE = 2;
+/** Python 3 source for the descriptor-relative guest filesystem protocol. See docs/guest.md. */
+export declare const GUEST_FILESYSTEM_PYTHON: string;
+export { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON };