@openclaw/fs-safe 0.9.0 → 0.11.0

package/dist/guest.js

@@ -0,0 +1,413 @@
+// 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",
+    "                os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                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):",
+    "        os.mkdir(dst_basename, stat.S_IMODE(src_stat.st_mode) or 0o755, dir_fd=dst_parent_fd)",
+    "        copied_children = []",
+    "        src_dir_fd = None",
+    "        dst_dir_fd = None",
+    "        try:",
+    "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
+    "            src_stat = os.fstat(src_dir_fd)",
+    "            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",
+    "            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 = create_temp_dir(dst_parent_fd, stat.S_IMODE(src_stat.st_mode) or 0o755)",
+    "        copied_children = []",
+    "        temp_dir_fd = None",
+    "        src_dir_fd = None",
+    "        try:",
+    "            temp_dir_fd = open_dir(temp_dir_name, dir_fd=dst_parent_fd)",
+    "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
+    "            src_stat = os.fstat(src_dir_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.close(temp_dir_fd)",
+    "            temp_dir_fd = None",
+    "            os.rename(temp_dir_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        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)",
+    "            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)",
+    "        try:",
+    "            os.unlink(dst_basename, dir_fd=dst_parent_fd)",
+    "        except FileNotFoundError:",
+    "            pass",
+    "        os.symlink(link_target, dst_basename, 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/dist/home-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAyCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}
+{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAoBA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAwCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAaR"}

package/dist/home-dir.js

@@ -1,6 +1,10 @@
 import os from "node:os";
 import path from "node:path";
 import { normalizeOptionalString } from "./string-coerce.js";
+function hasHomePrefix(input) {
+    return input === "~" || input.startsWith("~/") ||
+        (path.sep === "\\" && input.startsWith("~\\"));
+}
 function normalize(value) {
     const trimmed = normalizeOptionalString(value);
     if (!trimmed) {
@@ -20,8 +24,7 @@ function resolveRawHomeDir(env, homedir) {
     if (!explicitHome) {
         return resolveRawOsHomeDir(env, homedir);
     }
-    const segments = path.normalize(explicitHome).split(path.sep);
-    if (segments[0] !== "~") {
+    if (!hasHomePrefix(explicitHome)) {
         return explicitHome;
     }
     // OPENCLAW_HOME starts with "~"; expand against the os home dir. Fall
@@ -56,8 +59,7 @@ export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir)
     return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
 }
 export function expandHomePrefix(input, opts) {
-    const segments = path.normalize(input).split(path.sep);
-    if (segments[0] !== "~") {
+    if (!hasHomePrefix(input)) {
         return input;
     }
     const home = normalize(opts?.home) ??
@@ -65,14 +67,14 @@ export function expandHomePrefix(input, opts) {
     if (!home) {
         return input;
     }
-    return path.join(home, ...segments.slice(1));
+    // Expand before normalizing so a following .. traverses the actual home.
+    return path.join(home, input.slice(2));
 }
 export function resolveHomeRelativePath(input, opts) {
     if (!input) {
         return input;
     }
-    const segments = path.normalize(input).split(path.sep);
-    if (segments[0] !== "~") {
+    if (!hasHomePrefix(input)) {
         return path.resolve(input);
     }
     const expanded = expandHomePrefix(input, {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, type FsSafeErrorDetails, } from "./errors.js";
-export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type RootWalkDataEntry, type RootWalkDataEntryKind, type RootWalkDirectoryErrorBehavior, type RootWalkEntry, type RootWalkEntryFilter, type RootWalkEntryFilterResult, type RootWalkEntryKind, type RootWalkLimitBehavior, type RootWalkOptions, type RootWalkSymlinkPolicy, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCopyPublicationReceipt, type CopyCloneMode, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootEntriesOptions, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type RootWalkDataEntry, type RootWalkDataEntryKind, type RootWalkDirectoryErrorBehavior, type RootWalkEntry, type RootWalkEntryFilter, type RootWalkEntryFilterResult, type RootWalkEntryKind, type RootWalkLimitBehavior, type RootWalkOptions, type RootWalkSymlinkPolicy, type SymlinkPolicy, type MutationSymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
 export type { ContainmentGuarantee } from "./containment.js";
 export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
 export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/install-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAsB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}
+{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAMA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}

package/dist/install-path.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import fsSync from "node:fs";
 import path from "node:path";
 import { isPathInside } from "./path.js";
+import { realpathSync } from "./realpath.js";
 export function safeDirName(input) {
     const trimmed = input.trim();
     if (!trimmed) {
@@ -19,12 +20,8 @@ export function safePathSegmentHashed(input) {
         .replaceAll(/-+$/g, "");
     const normalized = base.length > 0 ? base : "skill";
     const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
-    const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
-    if (safe !== trimmed) {
-        const prefix = safe.length > 50 ? safe.slice(0, 50) : safe;
-        return `${prefix}-${hash}`;
-    }
-    if (safe.length > 60) {
+    if (safe !== trimmed || safe.length > 60) {
+        const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
         return `${safe.slice(0, 50)}-${hash}`;
     }
     return safe;
@@ -59,7 +56,7 @@ export async function assertCanonicalPathWithinBase(params) {
     else if (!baseLstat.isDirectory()) {
         throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
     }
-    const baseRealPath = fsSync.realpathSync.native(baseDir);
+    const baseRealPath = realpathSync.native(baseDir);
     const validateDirectory = async (dirPath) => {
         const resolvedDirPath = path.resolve(dirPath);
         const dirLstat = fsSync.lstatSync(dirPath);
@@ -75,7 +72,7 @@ export async function assertCanonicalPathWithinBase(params) {
         else if (!dirLstat.isDirectory()) {
             throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
         }
-        const dirRealPath = fsSync.realpathSync.native(dirPath);
+        const dirRealPath = realpathSync.native(dirPath);
         if (!isPathInside(baseRealPath, dirRealPath)) {
             throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
         }

package/dist/json-durable-queue-directory.js

@@ -1,10 +1,10 @@
-import fsSync from "node:fs";
 import path from "node:path";
 import { syncDirectory } from "./directory-durability.js";
 import { isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
 export async function syncQueueDirectoryCreation(dir, validationBase) {
-    const baseReal = fsSync.realpathSync.native(validationBase);
-    const targetReal = fsSync.realpathSync.native(dir);
+    const baseReal = realpathSync.native(validationBase);
+    const targetReal = realpathSync.native(dir);
     const relative = path.relative(baseReal, targetReal);
     if (isPathRelativeEscape(relative)) {
         throw new Error(`durable queue directory escapes validation base: ${dir}`);

package/dist/json-durable-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAM3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAO5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAiLD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhB;AA6DD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CASZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CA8Dd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}
+{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAM3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAO5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAiLD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhB;AAyDD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CASZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CA+Dd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}

package/dist/json-durable-queue.js

@@ -1,11 +1,14 @@
 import fs, {} from "node:fs";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
+import { readBoundedAsync } from "./bounded-read.js";
 import { syncDirectory } from "./directory-durability.js";
 import { syncQueueDirectoryCreation } from "./json-durable-queue-directory.js";
 import { getErrorCode, acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, moveDurableQueueEntryToFailed, } from "./json-durable-queue-ownership.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { replaceFileAtomicWithDirectorySync } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
@@ -59,7 +62,7 @@ async function ensureJsonDurableQueueDir(dir, validationRoot) {
         ? validationRoot
         : queueValidationRoot(dir);
     await assertNoSymlinkDirectorySegments(root, dir, true);
-    await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.promises.mkdir(recursiveMkdirPath(dir), { recursive: true, mode: 0o700 });
     await assertNoSymlinkDirectorySegments(root, dir, false);
     await chmodQueueDirectory(dir);
     await syncQueueDirectoryCreation(dir, root.path);
@@ -114,7 +117,7 @@ async function isDarwinSystemAlias(dir, stat) {
         return false;
     }
     try {
-        return fs.realpathSync.native(resolved) === `/private${resolved}`;
+        return realpathSync.native(resolved) === `/private${resolved}`;
     }
     catch {
         return false;
@@ -130,7 +133,7 @@ async function assertNoSymlinkDirectorySegments(validationRoot, dir, allowMissin
         if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
             throw new Error(`durable queue path is not a directory: ${dir}`);
         }
-        base = fs.realpathSync.native(base);
+        base = realpathSync.native(base);
         target = path.join(base, ...relative.split(path.sep).filter(Boolean));
         current = base;
         baseStat = fs.lstatSync(base);
@@ -158,7 +161,7 @@ async function assertNoSymlinkDirectorySegments(validationRoot, dir, allowMissin
         if (stat.isSymbolicLink() || !stat.isDirectory()) {
             if (stat.isSymbolicLink() && validationRoot.allowSymlinkBase) {
                 if (await isDarwinSystemAlias(current, stat)) {
-                    current = fs.realpathSync.native(current);
+                    current = realpathSync.native(current);
                     continue;
                 }
             }
@@ -253,20 +256,12 @@ async function readBoundedUtf8File(params) {
     try {
         const openedStat = await inspectQueueEntry(() => fs.fstatSync(handle.fd, { bigint: true }), params.maxBytes, initialStat);
         await inspectQueueEntry(inspectPath, params.maxBytes, openedStat);
-        const chunks = [];
-        const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, params.maxBytes + 1));
-        let total = 0;
-        while (true) {
-            const { bytesRead } = await handle.read(scratch, 0, scratch.length, null);
-            if (bytesRead === 0) {
-                return Buffer.concat(chunks, total).toString("utf8");
-            }
-            total += bytesRead;
-            if (total > params.maxBytes) {
-                throw new Error(`queue entry exceeds ${params.maxBytes} bytes`);
-            }
-            chunks.push(Buffer.from(scratch.subarray(0, bytesRead)));
-        }
+        const bytes = await readBoundedAsync(params.maxBytes, async (buffer, length) => (await handle.read(buffer, 0, length, null)).bytesRead, {
+            initialSize: openedStat.size >= 0n && Number.isSafeInteger(Number(openedStat.size))
+                ? Number(openedStat.size) : undefined,
+            createLimitError: () => new Error(`queue entry exceeds ${params.maxBytes} bytes`),
+        });
+        return bytes.toString("utf8");
     }
     finally {
         await handle.close();
@@ -323,6 +318,12 @@ export async function loadPendingJsonDurableQueueEntries(options) {
     for (const file of files) {
         if (file.endsWith(".delivered")) {
             const id = file.slice(0, -".delivered".length);
+            try {
+                assertSafeQueueEntryId(id);
+            }
+            catch {
+                continue;
+            }
             await completeDeliveredQueueEntry(resolveJsonDurableQueueEntryPaths(options.queueDir, id));
         }
         else if (options.cleanupTmpMaxAgeMs !== undefined && file.endsWith(".tmp")) {