@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,433 @@
+// Adapted from OpenClaw's guest filesystem program. Copyright OpenClaw Foundation; MIT.
+import { GUEST_FILESYSTEM_DISPATCH_PYTHON } from "./guest-dispatch-python.js";
+import { GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON, GUEST_FILESYSTEM_CREATE_STAGING_PYTHON, GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON, } from "./guest-native-python.js";
+/** Exclusive create found an existing destination, including a lost publication race. */
+export const GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE = 17;
+/** Read found a missing parent or file after the admitted root was opened. */
+export const GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE = 2;
+/** Python 3 source for the descriptor-relative guest filesystem protocol. See docs/guest.md. */
+export const GUEST_FILESYSTEM_PYTHON = [
+    `SANDBOX_CREATE_EXISTS_EXIT_CODE = ${GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE}`,
+    `SANDBOX_READ_NOT_FOUND_EXIT_CODE = ${GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE}`,
+    "import ctypes",
+    "import errno",
+    "import json",
+    "import os",
+    "import secrets",
+    "import stat",
+    "import sys",
+    "",
+    "operation = sys.argv[1]",
+    "",
+    "DIR_FLAGS = os.O_RDONLY",
+    "if hasattr(os, 'O_DIRECTORY'):",
+    "    DIR_FLAGS |= os.O_DIRECTORY",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    DIR_FLAGS |= os.O_NOFOLLOW",
+    "",
+    "READ_FLAGS = os.O_RDONLY",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    READ_FLAGS |= os.O_NOFOLLOW",
+    "if hasattr(os, 'O_NONBLOCK'):",
+    "    READ_FLAGS |= os.O_NONBLOCK",
+    "",
+    "WRITE_FLAGS = os.O_WRONLY | os.O_CREAT | os.O_EXCL",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    WRITE_FLAGS |= os.O_NOFOLLOW",
+    "",
+    "def split_relative(path_value):",
+    "    segments = []",
+    "    for segment in path_value.split('/'):",
+    "        if not segment or segment == '.':",
+    "            continue",
+    "        if segment == '..':",
+    "            raise OSError(errno.EPERM, 'path traversal is not allowed', segment)",
+    "        segments.append(segment)",
+    "    return segments",
+    "",
+    "def open_dir(path_value, dir_fd=None):",
+    "    return os.open(path_value, DIR_FLAGS, dir_fd=dir_fd)",
+    "",
+    "def walk_dir(root_fd, rel_path, mkdir_enabled):",
+    "    current_fd = os.dup(root_fd)",
+    "    try:",
+    "        for segment in split_relative(rel_path):",
+    "            try:",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            except FileNotFoundError:",
+    "                if not mkdir_enabled:",
+    "                    raise",
+    "                try:",
+    "                    os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                except FileExistsError:",
+    "                    pass  # The competing entry must still pass the no-follow directory open.",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            os.close(current_fd)",
+    "            current_fd = next_fd",
+    "        return current_fd",
+    "    except Exception:",
+    "        os.close(current_fd)",
+    "        raise",
+    "",
+    "def create_temp_file(parent_fd):",
+    "    prefix = '.openclaw-write-'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6)",
+    "        try:",
+    "            fd = os.open(candidate, WRITE_FLAGS, 0o600, dir_fd=parent_fd)",
+    "            return candidate, fd",
+    "        except FileExistsError:",
+    "            continue",
+    "    raise RuntimeError('failed to allocate sandbox temp file')",
+    "",
+    "def create_temp_dir(parent_fd, mode):",
+    "    prefix = '.openclaw-move-'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6)",
+    "        try:",
+    "            os.mkdir(candidate, mode, dir_fd=parent_fd)",
+    "            return candidate",
+    "        except FileExistsError:",
+    "            continue",
+    "    raise RuntimeError('failed to allocate sandbox temp directory')",
+    "",
+    GUEST_FILESYSTEM_CREATE_STAGING_PYTHON,
+    "",
+    "def existing_regular_file_mode(parent_fd, basename):",
+    "    try:",
+    "        target_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "    except FileNotFoundError:",
+    "        return None",
+    "    if stat.S_ISREG(target_stat.st_mode):",
+    "        return stat.S_IMODE(target_stat.st_mode)",
+    "    return None",
+    "",
+    "def write_all(file_fd, data):",
+    "    view = memoryview(data)",
+    "    while view:",
+    "        written = os.write(file_fd, view)",
+    "        if written <= 0:",
+    "            raise OSError(errno.EIO, 'failed to write copied file')",
+    "        view = view[written:]",
+    "",
+    GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON,
+    "",
+    "def copy_regular_file(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    src_fd = os.open(src_basename, READ_FLAGS, dir_fd=src_parent_fd)",
+    "    dst_fd = None",
+    "    destination_created = False",
+    "    copy_completed = False",
+    "    try:",
+    "        src_stat = os.fstat(src_fd)",
+    "        if not stat.S_ISREG(src_stat.st_mode):",
+    "            raise OSError(errno.EPERM, 'only regular files are allowed', src_basename)",
+    "        if src_stat.st_nlink > 1:",
+    "            raise OSError(errno.EPERM, 'hardlinked file is not allowed', src_basename)",
+    "        dst_fd = os.open(dst_basename, WRITE_FLAGS, stat.S_IMODE(src_stat.st_mode), dir_fd=dst_parent_fd)",
+    "        destination_created = True",
+    "        while True:",
+    "            chunk = os.read(src_fd, 65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(dst_fd, chunk)",
+    "        try:",
+    "            os.fchmod(dst_fd, stat.S_IMODE(src_stat.st_mode))",
+    "        except AttributeError:",
+    "            pass",
+    "        os.fsync(dst_fd)",
+    "        copy_completed = True",
+    "        return entry_identity(src_stat)",
+    "    finally:",
+    "        if dst_fd is not None:",
+    "            os.close(dst_fd)",
+    "        if destination_created and not copy_completed:",
+    "            try:",
+    "                os.unlink(dst_basename, dir_fd=dst_parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "        os.close(src_fd)",
+    "",
+    "def copy_file_atomic(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    prefix = '.openclaw-copy-'",
+    "    temp_name = None",
+    "    try:",
+    "        for _ in range(128):",
+    "            candidate = prefix + secrets.token_hex(6)",
+    "            try:",
+    "                copy_regular_file(src_parent_fd, src_basename, dst_parent_fd, candidate)",
+    "                temp_name = candidate",
+    "                break",
+    "            except FileExistsError:",
+    "                continue",
+    "        if temp_name is None:",
+    "            raise RuntimeError('failed to allocate sandbox copy temp file')",
+    "        os.replace(temp_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        temp_name = None",
+    "        os.fsync(dst_parent_fd)",
+    "    finally:",
+    "        if temp_name is not None:",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=dst_parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "",
+    "def write_atomic(parent_fd, basename, stdin_buffer):",
+    "    target_mode = existing_regular_file_mode(parent_fd, basename)",
+    "    temp_fd = None",
+    "    temp_name = None",
+    "    try:",
+    "        temp_name, temp_fd = create_temp_file(parent_fd)",
+    "        while True:",
+    "            chunk = stdin_buffer.read(65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(temp_fd, chunk)",
+    "        if target_mode is not None:",
+    "            try:",
+    "                os.fchmod(temp_fd, target_mode)",
+    "            except AttributeError:",
+    "                pass",
+    "        os.fsync(temp_fd)",
+    "        os.close(temp_fd)",
+    "        temp_fd = None",
+    "        os.replace(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)",
+    "        temp_name = None",
+    "        os.fsync(parent_fd)",
+    "    finally:",
+    "        if temp_fd is not None:",
+    "            os.close(temp_fd)",
+    "        if temp_name is not None:",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "",
+    GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON,
+    "",
+    "def read_file_impl(parent_fd, basename, max_bytes):",
+    "    file_fd = os.open(basename, READ_FLAGS, dir_fd=parent_fd)",
+    "    try:",
+    "        file_stat = os.fstat(file_fd)",
+    "        if not stat.S_ISREG(file_stat.st_mode):",
+    "            raise OSError(errno.EPERM, 'only regular files are allowed', basename)",
+    "        if file_stat.st_nlink > 1:",
+    "            raise OSError(errno.EPERM, 'hardlinked file is not allowed', basename)",
+    "        if max_bytes is not None and file_stat.st_size > max_bytes:",
+    "            raise OSError(errno.EFBIG, 'file exceeds bounded read limit', basename)",
+    "        bytes_read = 0",
+    "        while True:",
+    "            read_size = 65536 if max_bytes is None else min(65536, max_bytes - bytes_read + 1)",
+    "            chunk = os.read(file_fd, read_size)",
+    "            if not chunk:",
+    "                break",
+    "            bytes_read += len(chunk)",
+    "            if max_bytes is not None and bytes_read > max_bytes:",
+    "                raise OSError(errno.EFBIG, 'file exceeds bounded read limit', basename)",
+    "            write_all(1, chunk)",
+    "    finally:",
+    "        os.close(file_fd)",
+    "",
+    "def read_file(parent_fd, basename):",
+    "    read_file_impl(parent_fd, basename, None)",
+    "",
+    "def read_file_bounded(parent_fd, basename, max_bytes):",
+    "    if max_bytes < 0:",
+    "        raise OSError(errno.EINVAL, 'read limit must be non-negative', basename)",
+    "    read_file_impl(parent_fd, basename, max_bytes)",
+    "",
+    "def remove_tree(parent_fd, basename):",
+    "    entry_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "    if not stat.S_ISDIR(entry_stat.st_mode) or stat.S_ISLNK(entry_stat.st_mode):",
+    "        os.unlink(basename, dir_fd=parent_fd)",
+    "        return",
+    "    dir_fd = open_dir(basename, dir_fd=parent_fd)",
+    "    try:",
+    "        for child in os.listdir(dir_fd):",
+    "            remove_tree(dir_fd, child)",
+    "    finally:",
+    "        os.close(dir_fd)",
+    "    os.rmdir(basename, dir_fd=parent_fd)",
+    "",
+    "def entry_identity(entry_stat):",
+    "    return (",
+    "        entry_stat.st_dev,",
+    "        entry_stat.st_ino,",
+    "        entry_stat.st_mode,",
+    "        entry_stat.st_size,",
+    "        getattr(entry_stat, 'st_mtime_ns', int(entry_stat.st_mtime * 1000000000)),",
+    "        getattr(entry_stat, 'st_ctime_ns', int(entry_stat.st_ctime * 1000000000)),",
+    "    )",
+    "",
+    "def inode_identity(entry_stat):",
+    "    return (entry_stat.st_dev, entry_stat.st_ino)",
+    "",
+    "def same_identity(expected, entry_stat):",
+    "    return expected == entry_identity(entry_stat)",
+    "",
+    "def source_changed_error(basename):",
+    "    return OSError(getattr(errno, 'ESTALE', errno.EIO), 'source changed during move fallback cleanup', basename)",
+    "",
+    "def copy_entry(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    src_stat = os.lstat(src_basename, dir_fd=src_parent_fd)",
+    "    if stat.S_ISDIR(src_stat.st_mode) and not stat.S_ISLNK(src_stat.st_mode):",
+    "        copied_children = []",
+    "        src_dir_fd = None",
+    "        dst_dir_fd = None",
+    "        destination_created = False",
+    "        try:",
+    "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
+    "            src_stat = os.fstat(src_dir_fd)",
+    "            os.mkdir(dst_basename, stat.S_IMODE(src_stat.st_mode), dir_fd=dst_parent_fd)",
+    "            destination_created = True",
+    "            dst_dir_fd = open_dir(dst_basename, dir_fd=dst_parent_fd)",
+    "            for child in os.listdir(src_dir_fd):",
+    "                copied_children.append((child, copy_entry(src_dir_fd, child, dst_dir_fd, child)))",
+    "        except Exception:",
+    "            if dst_dir_fd is not None:",
+    "                os.close(dst_dir_fd)",
+    "                dst_dir_fd = None",
+    "            if destination_created:",
+    "                try:",
+    "                    remove_tree(dst_parent_fd, dst_basename)",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            raise",
+    "        finally:",
+    "            if src_dir_fd is not None:",
+    "                os.close(src_dir_fd)",
+    "            if dst_dir_fd is not None:",
+    "                os.close(dst_dir_fd)",
+    "        return ('dir', entry_identity(src_stat), copied_children)",
+    "    if stat.S_ISLNK(src_stat.st_mode):",
+    "        link_target = os.readlink(src_basename, dir_fd=src_parent_fd)",
+    "        os.symlink(link_target, dst_basename, dir_fd=dst_parent_fd)",
+    "        return ('leaf', entry_identity(src_stat), None)",
+    "    return ('leaf', copy_regular_file(src_parent_fd, src_basename, dst_parent_fd, dst_basename), None)",
+    "",
+    "def remove_copied_entry(parent_fd, basename, manifest):",
+    "    kind, expected_identity, children = manifest",
+    "    current_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "    if not same_identity(expected_identity, current_stat):",
+    "        raise source_changed_error(basename)",
+    "    if kind != 'dir':",
+    "        os.unlink(basename, dir_fd=parent_fd)",
+    "        return",
+    "    dir_fd = open_dir(basename, dir_fd=parent_fd)",
+    "    try:",
+    "        for child, child_manifest in children:",
+    "            remove_copied_entry(dir_fd, child, child_manifest)",
+    "    finally:",
+    "        os.close(dir_fd)",
+    "    os.rmdir(basename, dir_fd=parent_fd)",
+    "",
+    "def move_entry(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    try:",
+    "        os.rename(src_basename, dst_basename, src_dir_fd=src_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "        return",
+    "    except OSError as err:",
+    "        if err.errno != errno.EXDEV:",
+    "            raise",
+    "    src_stat = os.lstat(src_basename, dir_fd=src_parent_fd)",
+    "    if stat.S_ISDIR(src_stat.st_mode) and not stat.S_ISLNK(src_stat.st_mode):",
+    "        temp_dir_name = None",
+    "        copied_children = []",
+    "        temp_dir_fd = None",
+    "        src_dir_fd = None",
+    "        try:",
+    "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
+    "            src_stat = os.fstat(src_dir_fd)",
+    "            source_mode = stat.S_IMODE(src_stat.st_mode)",
+    "            temp_dir_name = create_temp_dir(dst_parent_fd, source_mode or 0o700)",
+    "            temp_dir_fd = open_dir(temp_dir_name, dir_fd=dst_parent_fd)",
+    "            for child in os.listdir(src_dir_fd):",
+    "                copied_children.append((child, copy_entry(src_dir_fd, child, temp_dir_fd, child)))",
+    "            os.close(src_dir_fd)",
+    "            src_dir_fd = None",
+    "            os.rename(temp_dir_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "            temp_dir_name = None",
+    "            if source_mode == 0:",
+    "                os.fchmod(temp_dir_fd, 0)",
+    "            os.close(temp_dir_fd)",
+    "            temp_dir_fd = None",
+    "        except Exception:",
+    "            if src_dir_fd is not None:",
+    "                os.close(src_dir_fd)",
+    "            if temp_dir_fd is not None:",
+    "                os.close(temp_dir_fd)",
+    "            if temp_dir_name is not None:",
+    "                try:",
+    "                    remove_tree(dst_parent_fd, temp_dir_name)",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            raise",
+    "        remove_copied_entry(src_parent_fd, src_basename, ('dir', entry_identity(src_stat), copied_children))",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "        return",
+    "    if stat.S_ISLNK(src_stat.st_mode):",
+    "        link_target = os.readlink(src_basename, dir_fd=src_parent_fd)",
+    "        temp_dir_name, temp_dir_fd = create_staging_dir(dst_parent_fd)",
+    "        try:",
+    "            os.symlink(link_target, 'link', dir_fd=temp_dir_fd)",
+    "            os.replace('link', dst_basename, src_dir_fd=temp_dir_fd, dst_dir_fd=dst_parent_fd)",
+    "        finally:",
+    "            try:",
+    "                try:",
+    "                    os.unlink('link', dir_fd=temp_dir_fd)",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            finally:",
+    "                os.close(temp_dir_fd)",
+    "            os.rmdir(temp_dir_name, dir_fd=dst_parent_fd)",
+    "        os.unlink(src_basename, dir_fd=src_parent_fd)",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "        return",
+    "    src_fd = os.open(src_basename, READ_FLAGS, dir_fd=src_parent_fd)",
+    "    temp_fd = None",
+    "    temp_name = None",
+    "    try:",
+    "        src_file_stat = os.fstat(src_fd)",
+    "        if not stat.S_ISREG(src_file_stat.st_mode):",
+    "            raise OSError(errno.EPERM, 'only regular files are allowed', src_basename)",
+    "        if src_file_stat.st_nlink > 1:",
+    "            raise OSError(errno.EPERM, 'hardlinked file is not allowed', src_basename)",
+    "        temp_name, temp_fd = create_temp_file(dst_parent_fd)",
+    "        while True:",
+    "            chunk = os.read(src_fd, 65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(temp_fd, chunk)",
+    "        try:",
+    "            os.fchmod(temp_fd, stat.S_IMODE(src_stat.st_mode))",
+    "        except AttributeError:",
+    "            pass",
+    "        os.fsync(temp_fd)",
+    "        os.close(temp_fd)",
+    "        temp_fd = None",
+    "        os.replace(temp_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        temp_name = None",
+    "        os.unlink(src_basename, dir_fd=src_parent_fd)",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "    finally:",
+    "        if temp_fd is not None:",
+    "            os.close(temp_fd)",
+    "        if temp_name is not None:",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=dst_parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "        os.close(src_fd)",
+    "",
+    "basename_indexes = (4, 7) if operation in ('copy', 'rename') else (4,) if operation in ('read', 'write', 'create', 'remove') else ()",
+    "for basename_index in basename_indexes:",
+    "    basename = sys.argv[basename_index]",
+    "    if not basename or basename in ('.', '..') or '/' in basename or '\\x00' in basename:",
+    "        raise OSError(errno.EINVAL, 'invalid basename', basename)",
+    "",
+    GUEST_FILESYSTEM_DISPATCH_PYTHON,
+].join("\n");
+export { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON };

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

@@ -0,0 +1,11 @@
+export declare function resolveEffectiveHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string | undefined;
+export declare function resolveRequiredHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+export declare function expandHomePrefix(input: string, opts?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+}): string;
+export declare function resolveHomeRelativePath(input: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+}): string;

package/node_modules/@openclaw/fs-safe/dist/home-dir.js

@@ -0,0 +1,149 @@
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { normalizeOptionalString } from "./string-coerce.js";
+import { assertNoWindowsPathAlias, assertNoWindowsPathAliasForPlatform, repairResolvedWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const PATH_ALIAS_MESSAGE = "path uses a Windows filesystem namespace alias";
+function isOrdinaryRootedWindowsDrivePath(input) {
+    const drive = input.charCodeAt(0);
+    return input.length >= 3 &&
+        ((drive >= 0x41 && drive <= 0x5a) || (drive >= 0x61 && drive <= 0x7a)) &&
+        input.charCodeAt(1) === 0x3a &&
+        (input.charCodeAt(2) === 0x5c || input.charCodeAt(2) === 0x2f) &&
+        input.indexOf(":", 2) === -1;
+}
+function hasHomePrefix(input) {
+    return input === "~" || input.startsWith("~/") ||
+        (path.sep === "\\" && input.startsWith("~\\"));
+}
+function normalize(value) {
+    const trimmed = normalizeOptionalString(value);
+    if (!trimmed) {
+        return undefined;
+    }
+    if (trimmed === "undefined" || trimmed === "null") {
+        return undefined;
+    }
+    return trimmed;
+}
+export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir) {
+    const raw = resolveRawHomeDir(env, homedir);
+    if (!raw)
+        return undefined;
+    assertNoWindowsPathAlias(raw, "filesystem", "home path uses a Windows filesystem namespace alias");
+    const resolved = resolvePathPreservingWindowsRoot(raw);
+    assertNoWindowsPathAlias(resolved, "filesystem", "home path uses a Windows filesystem namespace alias");
+    return resolved;
+}
+function resolveRawHomeDir(env, homedir) {
+    const explicitHome = normalize(env.OPENCLAW_HOME);
+    if (!explicitHome) {
+        return resolveRawOsHomeDir(env, homedir);
+    }
+    if (!hasHomePrefix(explicitHome)) {
+        return explicitHome;
+    }
+    // OPENCLAW_HOME starts with "~"; expand against the os home dir. Fall
+    // back to undefined when there is no os home to expand against rather
+    // than returning a raw "~"-prefixed path the caller cannot use.
+    const fallbackHome = resolveRawOsHomeDir(env, homedir);
+    if (!fallbackHome) {
+        return undefined;
+    }
+    return expandHomePrefix(explicitHome, { home: fallbackHome });
+}
+function resolveRawOsHomeDir(env, homedir) {
+    const envHome = normalize(env.HOME);
+    if (envHome) {
+        return envHome;
+    }
+    const userProfile = normalize(env.USERPROFILE);
+    if (userProfile) {
+        return userProfile;
+    }
+    return normalizeSafe(homedir);
+}
+function normalizeSafe(homedir) {
+    try {
+        return normalize(homedir());
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir) {
+    const resolved = resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+    assertNoWindowsPathAlias(resolved, "filesystem", "home path uses a Windows filesystem namespace alias");
+    return resolved;
+}
+export function expandHomePrefix(input, opts) {
+    if (!hasHomePrefix(input)) {
+        return input;
+    }
+    const home = normalize(opts?.home) ??
+        resolveEffectiveHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir);
+    if (!home) {
+        return input;
+    }
+    // Expand before normalizing so a following .. traverses the actual home.
+    return path.join(home, input.slice(2));
+}
+function resolveExpandedHomePath(input, opts) {
+    const expanded = expandHomePrefix(input, {
+        home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+        env: opts?.env,
+        homedir: opts?.homedir,
+    });
+    const resolved = resolvePathPreservingWindowsRoot(expanded);
+    assertNoWindowsPathAlias(resolved, "filesystem", PATH_ALIAS_MESSAGE);
+    return resolved;
+}
+function admitFinalHomePath(resolved, platform) {
+    assertNoWindowsPathAliasForPlatform(resolved, "filesystem", PATH_ALIAS_MESSAGE, platform);
+    return resolved;
+}
+function finishOrdinaryHomePath(input, resolved) {
+    const resolvedPlatform = process.platform;
+    if (resolved === input && resolvedPlatform !== undefined)
+        return resolved;
+    return admitFinalHomePath(resolved, resolvedPlatform);
+}
+function repairAndFinishOrdinaryHomePath(input, resolved) {
+    return finishOrdinaryHomePath(input, repairResolvedWindowsRoot(input, resolved));
+}
+function resolveHomePathCold(input, opts, rawPlatform, ordinaryRawAdmitted) {
+    if (ordinaryRawAdmitted) {
+        return finishOrdinaryHomePath(input, resolvePathPreservingWindowsRoot(input));
+    }
+    assertNoWindowsPathAliasForPlatform(input, "filesystem", PATH_ALIAS_MESSAGE, rawPlatform);
+    if (!hasHomePrefix(input)) {
+        const resolved = resolvePathPreservingWindowsRoot(input);
+        // This cold branch was not admitted as an ordinary rooted drive. Recheck
+        // even an unchanged result because the live platform can change between
+        // raw admission and resolved-path admission. Passing undefined preserves
+        // the classifier's default process.platform read.
+        return admitFinalHomePath(resolved, process.platform);
+    }
+    return resolveExpandedHomePath(input, opts);
+}
+export function resolveHomeRelativePath(input, opts) {
+    if (!input) {
+        return input;
+    }
+    const rawPlatform = process.platform;
+    // Primitive ordinary drive paths have exactly one structural colon. Record
+    // that admission so an unchanged resolved string does not need rescanning.
+    const ordinaryRawAdmitted = rawPlatform === "win32" &&
+        typeof input === "string" &&
+        isOrdinaryRootedWindowsDrivePath(input);
+    // Keep the overwhelmingly common rooted-drive path close to path.resolve
+    // itself. Seven-byte inputs retain the general helper's observable
+    // namespace-root preflight; a rare six-byte result retains its repair.
+    if (!ordinaryRawAdmitted || input.length === 7) {
+        return resolveHomePathCold(input, opts, rawPlatform, ordinaryRawAdmitted);
+    }
+    const resolved = path.resolve(input);
+    return resolved.length === 6
+        ? repairAndFinishOrdinaryHomePath(input, resolved)
+        : finishOrdinaryHomePath(input, resolved);
+}

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

@@ -0,0 +1,9 @@
+export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
+export type * from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type Root, } from "./root.js";
+export type * from "./root-public-types.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export type * from "./config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export type * from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/node_modules/@openclaw/fs-safe/dist/index.js

@@ -0,0 +1,5 @@
+export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, } from "./root.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

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

@@ -0,0 +1,25 @@
+export declare function safeDirName(input: string): string;
+/** Legacy readable encoding; distinct IDs can share a result. Use V2 for untrusted IDs. */
+export declare function safePathSegmentHashed(input: string): string;
+/**
+ * Versioned install-ID encoding: every trimmed ID receives a domain-separated
+ * SHA-256 digest. Only surrounding whitespace is intentionally equivalent.
+ */
+export declare function safePathSegmentHashedV2(input: string): string;
+export declare function resolveSafeInstallDir(params: {
+    baseDir: string;
+    id: string;
+    invalidNameMessage: string;
+    nameEncoder?: (id: string) => string;
+}): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function assertCanonicalPathWithinBase(params: {
+    baseDir: string;
+    candidatePath: string;
+    boundaryLabel: string;
+}): Promise<void>;