@openclaw/fs-safe 0.18.2 → 0.20.0

package/dist/file-lock-sync-root-held.d.ts

@@ -1,5 +1,6 @@
+import { type SyncHeldLock } from "./file-lock-sync-admission.js";
+import type { SidecarLockOptionFields } from "./sidecar-lock-types.js";
 import type { FileLockSyncHandle } from "./file-lock-sync.js";
-import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
 import { type FileLockSyncRootAuthority, type FileLockSyncRootPath } from "./file-lock-sync-root.js";
 import { type FileLockSyncRootFileReceipt, type FileLockSyncRootSnapshot } from "./file-lock-sync-root-io.js";
 type RootSyncHeldLockReleaseState = "active" | "releasing" | "exit-cleaning" | "released";
@@ -7,22 +8,14 @@ type RootSyncHeldLockHandleDisposition = {
     held: RootSyncHeldLock;
     released: boolean;
 };
-export type RootSyncHeldLock = {
+export type RootSyncHeldLock = SidecarLockOptionFields<SyncHeldLock & {
     deferredExitReleases?: Set<RootSyncHeldLockHandleDisposition>;
-    fd: number | undefined;
-    lockPath: string;
-    normalizedTargetPath: string;
-    parsePayload?: (raw: string) => unknown;
-    refCount: number;
-    reentrantOwner?: string;
     releaseState: RootSyncHeldLockReleaseState;
     revision: number;
     rootAuthority: FileLockSyncRootAuthority;
     rootPath: FileLockSyncRootPath;
     rootReceipt: FileLockSyncRootFileReceipt;
-    snapshot: SidecarLockSnapshot;
-    timer?: NodeJS.Timeout;
-};
+}>;
 export declare function readRootSidecarSnapshotSync(rootPath: FileLockSyncRootPath, parsePayload?: (raw: string) => unknown, onOpenFailure?: (error: unknown) => void, expectedReceipt?: FileLockSyncRootFileReceipt): FileLockSyncRootSnapshot | null;
 export declare function getRootSyncHeldLocks(): Map<string, RootSyncHeldLock>;
 export declare function ensureRootSyncExitCleanupRegistered(): void;

package/dist/file-lock-sync-root-held.js

@@ -53,9 +53,6 @@ export function getRootSyncHeldLocks() {
     }
     return globalWithState[ROOT_SYNC_HELD_LOCKS_KEY];
 }
-function existingRootSyncHeldLocks() {
-    return globalThis[ROOT_SYNC_HELD_LOCKS_KEY];
-}
 function reactivateExactHeldLock(heldLocks, held, restoreConsumedReference) {
     if (heldLocks.get(held.normalizedTargetPath) !== held || held.releaseState === "released") {
         return false;
@@ -123,7 +120,7 @@ function releaseAllRootSyncHeldLocks() {
     try {
         // A newListener callback can invoke the candidate handler before
         // registration succeeds. Do not create acquisition state in that window.
-        const heldLocks = existingRootSyncHeldLocks();
+        const heldLocks = globalThis[ROOT_SYNC_HELD_LOCKS_KEY];
         if (!heldLocks)
             return;
         getSyncLockAdmissions().clear();

package/dist/file-lock-sync-root-io.d.ts

@@ -14,10 +14,7 @@ export type FileLockSyncRootFileReceipt = Readonly<{
     identity: ExactIdentity;
     parent: DirectoryReceipt;
 }>;
-export type FileLockSyncRootDirectoryReceipt = Readonly<{
-    identity: ExactIdentity;
-    parent: DirectoryReceipt;
-}>;
+export type FileLockSyncRootDirectoryReceipt = FileLockSyncRootFileReceipt;
 export type FileLockSyncRootDiskSnapshot = {
     ownershipToken?: never;
     payload: unknown;

package/dist/file-lock-sync-root.d.ts

@@ -1,3 +1,4 @@
+import { type DenyMutationPolicy } from "./deny-mutations.js";
 import { type RootContext } from "./root-context.js";
 import type { Root } from "./root-impl.js";
 import type { RootDefaults } from "./root-options.js";
@@ -7,10 +8,7 @@ export type FileLockSyncRootAuthority = Readonly<{
     adapter: object;
     context: RootContext;
     assertBeforeMutation?: () => void;
-    denyMutations?: Readonly<{
-        paths?: readonly string[];
-        prefixes?: readonly string[];
-    }>;
+    denyMutations?: Readonly<DenyMutationPolicy>;
     hardlinks?: RootDefaults["hardlinks"];
     mutationPolicy: RootPathResolutionPolicy;
     readPolicy: RootPathResolutionPolicy;

package/dist/file-store-boundary.d.ts

@@ -1,5 +1,5 @@
 import type { Readable } from "node:stream";
-import { type SyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
+import { ensureSyncStoreDirectory, type SyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
 import { type Root } from "./root.js";
 import { prepareSecretFileWrite } from "./secret-file.js";
 export type SyncParentGuard = SyncStoreDirectoryReceipt;
@@ -23,12 +23,8 @@ export declare function ensureParentSync(params: {
     filePath: string;
     mode: number;
 }): SyncParentGuard;
-export declare function ensureStoreDirectorySync(params: {
-    rootDir: string;
-    targetDir: string;
-    mode: number;
-    messagePrefix: "private store" | "store";
-}): SyncParentGuard;
+export declare function ensureStoreDirectorySync(params: Parameters<typeof ensureSyncStoreDirectory>[0]): SyncParentGuard;
+export declare function literalStoreRootPath(relativePath: string): string;
 export declare function assertRelativePath(relativePath: string): string;
 export declare function resolveStorePath(rootDir: string, relativePath: string): string;
 export declare function assertFileStoreMaxBytes(size: number, limit: number | undefined): void;

package/dist/file-store-boundary.js

@@ -7,8 +7,7 @@ import { FsSafeError } from "./errors.js";
 import { assertSyncStoreDirectoryReceipt, ensureSyncStoreDirectory, } from "./file-store-sync-directory.js";
 import { isPathInside, splitSafeRelativePath } from "./path.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
-import { ensureTrailingSep } from "./root-context.js";
-import { RootHandle } from "./root-impl.js";
+import { rootFromDirectoryGuard } from "./root-impl.js";
 import { prepareSecretFileWrite } from "./secret-file.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
@@ -16,7 +15,7 @@ import { readRegularFile } from "./regular-file.js";
 import { errorCauseOptions } from "./root-errors.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
-    const parent = path.posix.dirname(relativePath);
+    const parent = literalStoreRootPath(path.posix.dirname(relativePath));
     if (parent === ".") {
         return;
     }
@@ -32,13 +31,7 @@ export async function openWritableStoreRoot(params) {
 export async function openPrivateStoreLockRoot(params) {
     const { parentGuard } = await prepareSecretFileWrite(params);
     // Bind to the admitted parent, never resolve a replacement into a fresh capability.
-    return new RootHandle({
-        rootDir: parentGuard.dir,
-        rootGuard: { dir: parentGuard.realPath, realPath: parentGuard.realPath, stat: parentGuard.stat },
-        rootReal: parentGuard.realPath,
-        rootWithSep: ensureTrailingSep(parentGuard.realPath),
-        rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
-    }, { hardlinks: "reject" });
+    return rootFromDirectoryGuard(parentGuard, { hardlinks: "reject" });
 }
 async function chmodDirectoryInRootBestEffort(scopedRoot, relativePath, mode) {
     const dirPath = await scopedRoot.resolve(relativePath);
@@ -120,6 +113,10 @@ export function ensureStoreDirectorySync(params) {
     assertSyncStoreDirectoryReceipt(guard);
     return guard;
 }
+// Store keys and directory-entry names are literal, unlike Root's home syntax.
+export function literalStoreRootPath(relativePath) {
+    return relativePath === "~" || relativePath.startsWith("~/") ? `./${relativePath}` : relativePath;
+}
 export function assertRelativePath(relativePath) {
     const raw = relativePath.trim();
     if (!raw || raw !== relativePath) {

package/dist/file-store-prune.js

@@ -2,6 +2,7 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { literalStoreRootPath } from "./file-store-boundary.js";
 import { isPathInside } from "./path.js";
 import { realpathSync } from "./realpath.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
@@ -74,13 +75,13 @@ export async function pruneExpiredStoreEntries(params) {
                     await assertRootGuard();
                     // Keep empty-dir pruning on the same root-bounded remove path as files;
                     // the Root fallback handles empty directories without recursive delete.
-                    await scopedRoot.remove(relativePath, REMOVE_EMPTY_DIRECTORY_OPTIONS).catch(() => undefined);
+                    await scopedRoot.remove(literalStoreRootPath(relativePath), REMOVE_EMPTY_DIRECTORY_OPTIONS).catch(() => undefined);
                 }
                 continue;
             }
             if (stat.isFile() && now - stat.mtimeMs > params.options.ttlMs) {
                 await assertRootGuard();
-                await scopedRoot.remove(relativePath, {
+                await scopedRoot.remove(literalStoreRootPath(relativePath), {
                     assertBeforeMutation: () => {
                         // Removal preparation can outlive the expiry observation above.
                         const current = fsSync.lstatSync(fullPath);

package/dist/file-store.d.ts

@@ -12,14 +12,11 @@ export type FileStoreOptions = {
     mode?: number;
     maxBytes?: number;
 };
-export type FileStoreWriteOptions = {
+export type FileStoreWriteOptions = Partial<Pick<FileStoreOptions, "dirMode" | "mode" | "maxBytes"> & {
     /** Override store durability; defaults to the store option, then true. */
-    durable?: boolean;
-    dirMode?: number;
-    mode?: number;
-    maxBytes?: number;
-    tempPrefix?: string;
-};
+    durable: boolean;
+    tempPrefix: string;
+}>;
 export type FileStoreReadOptions = RootReadOptions & {
     encoding?: BufferEncoding;
 };

package/dist/file-store.js

@@ -3,7 +3,7 @@ import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { pruneExpiredStoreEntries } from "./file-store-prune.js";
-import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, literalStoreRootPath, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { writeFileSyncAtomic } from "./file-store-sync-write.js";
 import { createJsonStore } from "./json-document-store.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -61,7 +61,7 @@ function handleSyncStoreReadOpenFailure(opened) {
     });
 }
 async function copyIntoRoot(params) {
-    const relativePath = assertRelativePath(params.relativePath);
+    const relativePath = params.relativePath;
     const destination = resolveStorePath(params.rootDir, relativePath);
     assertNoWindowsPathAlias(params.sourcePath, "filesystem", "source path uses a Windows filesystem namespace alias");
     const sourceStat = syncFs.lstatSync(params.sourcePath);
@@ -75,7 +75,7 @@ async function copyIntoRoot(params) {
         maxBytes: params.maxBytes,
     });
     await ensureParentInRoot(scopedRoot, relativePath, params.dirMode);
-    await scopedRoot.copyIn(relativePath, params.sourcePath, {
+    await scopedRoot.copyIn(literalStoreRootPath(relativePath), params.sourcePath, {
         durable: params.durable,
         maxBytes: params.maxBytes,
         mkdir: false,
@@ -97,8 +97,7 @@ export function fileStore(options) {
         return await root(rootDir, { hardlinks: "reject", maxBytes });
     }
     async function write(relativePath, data, writeOptions) {
-        const safeRelativePath = assertRelativePath(relativePath);
-        const destination = resolveStorePath(rootDir, safeRelativePath);
+        const destination = resolveStorePath(rootDir, relativePath);
         const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
         const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
         assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
@@ -121,8 +120,8 @@ export function fileStore(options) {
             dirMode: writeDirMode,
             maxBytes: writeMaxBytes,
         });
-        await ensureParentInRoot(scopedRoot, safeRelativePath, writeDirMode);
-        await scopedRoot.write(safeRelativePath, content, {
+        await ensureParentInRoot(scopedRoot, relativePath, writeDirMode);
+        await scopedRoot.write(literalStoreRootPath(relativePath), content, {
             mkdir: false,
             mode: writeMode,
             durable: writeDurable,
@@ -135,8 +134,7 @@ export function fileStore(options) {
         root: openRoot,
         write,
         writeStream: async (relativePath, stream, writeOptions) => {
-            const safeRelativePath = assertRelativePath(relativePath);
-            const destination = resolveStorePath(rootDir, safeRelativePath);
+            const destination = resolveStorePath(rootDir, relativePath);
             const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
             const limit = configuredLimit ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
             if (privateMode) {
@@ -172,7 +170,7 @@ export function fileStore(options) {
             try {
                 await copyIntoRoot({
                     rootDir,
-                    relativePath: safeRelativePath,
+                    relativePath,
                     sourcePath: staged.path,
                     durable: writeDurable,
                     maxBytes: limit,
@@ -214,17 +212,17 @@ export function fileStore(options) {
                 tempPrefix: writeOptions?.tempPrefix,
             });
         },
-        open: async (relativePath, readOptions) => await (await openRoot()).open(assertRelativePath(relativePath), readOptions),
-        read: async (relativePath, readOptions) => await (await openRoot()).read(assertRelativePath(relativePath), readOptions),
-        readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(assertRelativePath(relativePath), readOptions),
+        open: async (relativePath, readOptions) => await (await openRoot()).open(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
+        read: async (relativePath, readOptions) => await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
+        readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
         readText: async (relativePath, readOptions) => {
             const { encoding = "utf8", ...options } = readOptions ?? {};
-            return (await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+            return (await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), options)).buffer
                 .toString(encoding);
         },
         readTextIfExists: async (relativePath, readOptions) => {
             try {
-                return await (await openRoot()).readText(assertRelativePath(relativePath), readOptions);
+                return await (await openRoot()).readText(literalStoreRootPath(assertRelativePath(relativePath)), readOptions);
             }
             catch (error) {
                 if (isNotFound(error)) {
@@ -235,12 +233,12 @@ export function fileStore(options) {
         },
         readJson: async (relativePath, readOptions) => {
             const { encoding = "utf8", ...options } = readOptions ?? {};
-            return JSON.parse((await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+            return JSON.parse((await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), options)).buffer
                 .toString(encoding));
         },
         readJsonIfExists: async (relativePath, readOptions) => {
             try {
-                return await (await openRoot()).readJson(assertRelativePath(relativePath), readOptions);
+                return await (await openRoot()).readJson(literalStoreRootPath(assertRelativePath(relativePath)), readOptions);
             }
             catch (error) {
                 if (isNotFound(error)) {
@@ -250,9 +248,9 @@ export function fileStore(options) {
             }
         },
         remove: async (relativePath) => {
-            await (await openRoot()).remove(assertRelativePath(relativePath));
+            await (await openRoot()).remove(literalStoreRootPath(assertRelativePath(relativePath)));
         },
-        exists: async (relativePath) => await (await openRoot()).exists(assertRelativePath(relativePath)),
+        exists: async (relativePath) => await (await openRoot()).exists(literalStoreRootPath(assertRelativePath(relativePath))),
         writeText: async (relativePath, data, writeOptions) => await write(relativePath, data, writeOptions),
         writeJson: async (relativePath, data, writeOptions) => {
             const trailingNewline = writeOptions?.trailingNewline;
@@ -269,7 +267,7 @@ export function fileStore(options) {
                 } : {}),
                 readIfExists: async () => {
                     try {
-                        return await (await openRoot()).readJson(assertRelativePath(relativePath));
+                        return await (await openRoot()).readJson(literalStoreRootPath(relativePath));
                     }
                     catch (error) {
                         if (isNotFound(error)) {
@@ -278,7 +276,7 @@ export function fileStore(options) {
                         throw error;
                     }
                 },
-                readRequired: async () => await (await openRoot()).readJson(assertRelativePath(relativePath)),
+                readRequired: async () => await (await openRoot()).readJson(literalStoreRootPath(relativePath)),
                 write: async (value, options) => {
                     const json = stringifyJsonDocument(value, null, 2);
                     await write(relativePath, options?.trailingNewline === false ? json : `${json}\n`, { durable: options?.durable });

package/dist/guest-native-python.js

@@ -36,15 +36,6 @@ export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
     "    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)",
@@ -52,32 +43,33 @@ export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
     "    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:",
+    "    if rename_fn is not None:",
+    "        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:",
+    "            return",
     "        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)",
+    "        if not is_linux or error_code not in unsupported_codes:",
+    "            raise OSError(error_code, os.strerror(error_code), dst_basename)",
+    "    elif not is_linux:",
+    "        raise OSError(errno.ENOSYS, 'atomic no-replace rename is unavailable')",
+    "    os.link(",
+    "        src_basename,",
+    "        dst_basename,",
+    "        src_dir_fd=src_parent_fd,",
+    "        dst_dir_fd=dst_parent_fd,",
+    "        follow_symlinks=False,",
+    "    )",
 ].join("\n");
 export const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON = [
     "def create_exclusive(parent_fd, basename, stdin_buffer):",

package/dist/guest.js

@@ -270,13 +270,15 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "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",
+    "        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)))",
@@ -284,10 +286,11 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "            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",
+    "            if destination_created:",
+    "                try:",
+    "                    remove_tree(dst_parent_fd, dst_basename)",
+    "                except FileNotFoundError:",
+    "                    pass",
     "            raise",
     "        finally:",
     "            if src_dir_fd is not None:",
@@ -328,30 +331,36 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "            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)",
+    "        temp_dir_name = None",
     "        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)",
+    "            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",
-    "            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",
+    "            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)",

package/dist/json-document-store.d.ts

@@ -1,13 +1,8 @@
-import type { FileLockRetryOptions } from "./file-lock.js";
+import { type FsSafeLockConfig } from "./lock-config.js";
 import type { Root } from "./root.js";
-import type { SidecarLockStaleRecovery } from "./sidecar-lock.js";
-export type JsonStoreLockOptions = {
-    staleMs?: number;
-    timeoutMs?: number;
-    retry?: FileLockRetryOptions;
-    staleRecovery?: SidecarLockStaleRecovery;
-    managerKey?: string;
-};
+export type JsonStoreLockOptions = Partial<FsSafeLockConfig & {
+    managerKey: string;
+}>;
 export type JsonFileStoreOptions = {
     /** Overrides the parent store's durability for every JSON mutation. */
     durable?: boolean;

package/dist/json-durable-queue.js

@@ -145,8 +145,7 @@ export async function loadPendingJsonDurableQueueEntries(options) {
             await unlinkStaleTmpBestEffort(path.join(queueDir, file), now, options.cleanupTmpMaxAgeMs);
         }
     }
-    const ids = [];
-    const seenIds = new Set();
+    const ids = new Set();
     for (const file of files) {
         const suffix = file.endsWith(".processing")
             ? ".processing"
@@ -162,10 +161,7 @@ export async function loadPendingJsonDurableQueueEntries(options) {
         catch {
             continue;
         }
-        if (seenIds.has(id))
-            continue;
-        seenIds.add(id);
-        ids.push(id);
+        ids.add(id);
     }
     const entries = [];
     for (const id of ids) {

package/dist/local-file-access.js

@@ -8,10 +8,6 @@ const FILE_URL_PREFIX_RE = /^file:\/\//i;
 export function isFileUrl(input) {
     return FILE_URL_PREFIX_RE.test(input);
 }
-function isLocalFileUrlHost(hostname) {
-    const normalized = normalizeLowercaseStringOrEmpty(hostname);
-    return normalized === "" || normalized === "localhost";
-}
 export function hasEncodedFileUrlSeparator(pathname) {
     return ENCODED_FILE_URL_SEPARATOR_RE.test(pathname);
 }
@@ -41,7 +37,8 @@ export function safeFileURLToPath(fileUrl, platform = process.platform) {
     if (parsed.protocol !== "file:") {
         throw new Error(`Invalid file:// URL: ${fileUrl}`);
     }
-    if (!isLocalFileUrlHost(parsed.hostname)) {
+    const normalizedHost = normalizeLowercaseStringOrEmpty(parsed.hostname);
+    if (!(normalizedHost === "" || normalizedHost === "localhost")) {
         throw new Error(`file:// URLs with remote hosts are not allowed: ${fileUrl}`);
     }
     if (hasEncodedFileUrlSeparator(parsed.pathname)) {

package/dist/local-file-descriptor.d.ts

@@ -1,16 +1,13 @@
 import type { BigIntStats, Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
-import type { HardlinkPolicy } from "./root-options.js";
-import type { SymlinkPolicy } from "./root-symlink-policy.js";
+import type { RootReadOptions } from "./root-options.js";
 type OwnedLocalFile = {
     handle: FileHandle;
     stat: Stats;
     identity: BigIntStats;
     preOpenStat: BigIntStats | undefined;
 };
-export declare function openLocalFileDescriptor(filePath: string, options?: {
-    hardlinks?: HardlinkPolicy;
-    symlinks?: SymlinkPolicy;
+export declare function openLocalFileDescriptor(filePath: string, options?: Pick<RootReadOptions, "hardlinks" | "symlinks"> & {
     readWrite?: true;
 }): Promise<OwnedLocalFile>;
 export {};

package/dist/local-roots.d.ts

@@ -1,4 +1,4 @@
-import { type HardlinkPolicy, type ReadResult, type SymlinkPolicy } from "./root.js";
+import { type ReadResult, type RootReadOptions } from "./root.js";
 export type LocalRootsPathResult = {
     path: string;
     root: string;
@@ -15,11 +15,6 @@ export type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
     allowMissing?: boolean;
     requireFile?: boolean;
 };
-export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
-    hardlinks?: HardlinkPolicy;
-    maxBytes?: number;
-    nonBlockingRead?: boolean;
-    symlinks?: SymlinkPolicy;
-};
+export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & RootReadOptions;
 export declare function resolveLocalPathFromRootsSync(options: ResolveLocalPathFromRootsSyncOptions): LocalRootsPathResult | null;
 export declare function readLocalFileFromRoots(options: ReadLocalFileFromRootsOptions): Promise<LocalRootsReadResult | null>;

package/dist/move-path-cleanup.js

@@ -135,9 +135,6 @@ async function observeOwnedAliasUnlink(sourcePath, group) {
     group.expected = entryIdentity(observed);
     return "removed";
 }
-function mergeCleanupResults(a, b) {
-    return a === "stale" || b === "stale" ? "stale" : "removed";
-}
 export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBeforeMutation) {
     if (manifest.kind === "directory") {
         let currentStat;
@@ -162,7 +159,10 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBefo
             inspectSourceDirectory(sourcePath, manifest.directoryIdentity);
         } : undefined;
         for (const child of manifest.children) {
-            result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state, assertBeforeChildMutation));
+            const childResult = await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state, assertBeforeChildMutation);
+            if (childResult === "stale") {
+                result = "stale";
+            }
         }
         // Child cleanup and the caller's authority check can replace the directory.
         // Keep the final exact observation after both, immediately before removal.