@openclaw/fs-safe 0.18.2 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.19.0 - 2026-09-24
+
+### Highlights
+
+- **Strict secret-file durability:** `createSecretFileAtomic()` accepts `durable: "file"` to require every file flush to succeed, including on `EPERM`; parent-directory synchronization remains best effort. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- **Literal `~` names:** keep FileStore keys, absolute Root reads, discovered walk entries, and ZIP/TAR entries literal instead of treating them as home-directory shorthand. Reads, writes, removal, pruning, extraction, and durable publication select the intended entry. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- **Native Unix descriptor safety:** reject negative descriptors in low-level root, query, hash, copy, clone, staging, and cleanup calls without Rust panics or working-directory operations. Modern macOS beneath opens report `EBADF` for negative roots instead of `EIO`. ([#640](https://github.com/openclaw/fs-safe/pull/640), [#643](https://github.com/openclaw/fs-safe/pull/643), [#646](https://github.com/openclaw/fs-safe/pull/646))
+
+### Fixes
+
+- **Guest directory permissions:** cross-device moves preserve mode `000`, including nested directories, without changing other modes' umask behavior. Restore top-level permissions through the retained directory descriptor and preserve published entries on failure. Thanks @SebTardif. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- **ReFS clone cleanup:** remove ordinary partial output when Windows rejects the ignore-readonly deletion flag. Keep readonly attributes intact and include cleanup failures in the original clone error; readonly files or other processes' open handles can still leave output behind. ([#648](https://github.com/openclaw/fs-safe/pull/648))
+
+### Compatibility and documentation
+
+- Secret creation's default and boolean durability options retain their behavior, and `writeSecretFileAtomic()` remains boolean-only. Strict file synchronization preserves existing publication and cleanup semantics: a failure after publication can leave a complete file present. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- `Root.walk("~")` and `Root.walk("~/dir")` expand home shorthand when iteration starts and return admitted canonical paths relative to the Root. Use `./~/dir` for a literal tilde directory, and prefix returned entry paths with `./` when passing them to another Root method. Relative Root `~/name` inputs still expand home; FileStore keys do not. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- Guest moves still require OS permission to read mode-000 source directories; they do not widen source permissions. If permission restoration fails after publication, the source and published copy remain for caller reconciliation. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- Clarify that `Root.append()` and `openWritable()` creation modes remain subject to the process umask and do not chmod existing files. This documents existing behavior. ([#636](https://github.com/openclaw/fs-safe/pull/636))
+
 ## 0.18.2 - 2026-09-22
 
 ### Fixes

package/dist/archive-durability.js

@@ -78,7 +78,7 @@ export async function finalizeArchivePublication(params) {
                     const env_1 = { stack: [], error: void 0, hasError: false };
                     try {
                         await assertGuards(file.guards);
-                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(file.relativePath, { hardlinks: "reject", symlinks: "reject" })
+                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(`./${file.relativePath}`, { hardlinks: "reject", symlinks: "reject" })
                             .catch((error) => {
                             if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
                                 throw createArchiveSymlinkTraversalError(file.relativePath);

package/dist/archive-merge.js

@@ -250,7 +250,7 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
                                 }
                             };
                         }
-                        await targetRoot.copyIn(relPath, sourcePath, options);
+                        await targetRoot.copyIn(`./${relPath}`, sourcePath, options);
                         check();
                         await assertGuards();
                         await assertResolvedInsideDestination({

package/dist/archive-staging.js

@@ -133,7 +133,9 @@ export async function assertResolvedInsideDestination(params) {
 }
 async function mkdirArchiveOutput(params) {
     try {
-        await params.targetRoot.mkdir(params.relativePath);
+        const relativePath = params.relativePath;
+        // Archive names are literal; retain Root.mkdir's admission without home expansion.
+        await params.targetRoot.mkdir(relativePath === "~" || relativePath.startsWith("~/") ? `./${relativePath}` : relativePath);
     }
     catch (error) {
         if (error instanceof FsSafeError) {

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-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.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-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-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/native-binding.d.ts

@@ -1,6 +1,7 @@
 import type { TarMeterLimits } from "./archive-limits.js";
 import type { ArchiveMemberKind } from "./archive-plan.js";
 import type { CopyCloneMode } from "./copy-policy.js";
+import type { WindowsAceFlags } from "./owner-dacl.js";
 export interface NativeFileHash {
     bytes: number;
     digest: string;
@@ -58,16 +59,7 @@ export interface NativeWindowsAccessControlEntry {
     sid: string;
     mask: number;
     aceType: string;
-    flags: {
-        raw: number;
-        objectInherit: boolean;
-        containerInherit: boolean;
-        noPropagateInherit: boolean;
-        inheritOnly: boolean;
-        inherited: boolean;
-        successfulAccess: boolean;
-        failedAccess: boolean;
-    };
+    flags: WindowsAceFlags;
 }
 export interface NativeWindowsSecurityFacts {
     ownerSid: string;
@@ -96,6 +88,12 @@ export interface NativeWindowsDirectoryReceipt {
 export interface NativeDarwinAclFacts {
     state: "absent" | "empty" | "present";
 }
+type NativeTwoPathArgs = [
+    sourceRootFd: number,
+    sourceRelPath: string,
+    targetRootFd: number,
+    targetRelPath: string
+];
 export interface NativeBinding {
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
@@ -141,7 +139,7 @@ export interface NativeBinding {
     extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
     fstatIdentity(fd: number): NativeFileIdentity;
     inspectArchiveNative(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
-    linkBeneath(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    linkBeneath(...args: NativeTwoPathArgs): void;
     /** Direct-child mkdir; true is receipt provenance only, never cleanup ownership. */
     mkdirChildBeneath?(parentFd: number, basename: string, mode: number): boolean;
     mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
@@ -153,10 +151,11 @@ export interface NativeBinding {
     ownedTreeRemovalAvailable?(parentFd: number): boolean;
     removeOwnedTree?(parentFd: number, basename: string, directoryFd: number): Promise<NativeOwnedTreeRemovalResult>;
     removeOwnedTreeSync?(parentFd: number, basename: string, directoryFd: number): NativeOwnedTreeRemovalResult;
-    renameNoReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    renameNoReplace(...args: NativeTwoPathArgs): void;
     /** Identity-fenced retained-directory rename capability. */
     renameNoReplaceWithIdentity?(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string, expectedSourceDev: bigint, expectedSourceIno: bigint): void;
-    renameReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    renameReplace(...args: NativeTwoPathArgs): void;
     sha256File(fd: number, maxBytes?: number, signal?: AbortSignal): Promise<NativeFileHash>;
 }
 export declare function captureNativeFdClose(binding: NativeBinding): (fd: number) => void;
+export {};

package/dist/pinned-mutation-shared-route.d.ts

@@ -1,14 +1,9 @@
-import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { PinnedMutationPolicySnapshot } from "./pinned-mutation-admission.js";
 import type { RootBoundaryIdentity } from "./root-boundary.js";
-import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export type ExactRootIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
 }>;
-type SharedMutationPolicy = Readonly<{
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}>;
 export declare function ordinaryWindowsSegments(relativePath: string): boolean;
 export declare function ordinarySharedAbsoluteInsideRoot(rootReal: string, candidatePath: string, rootIdentity: ExactRootIdentity): boolean;
 export declare function simpleSharedRoute(params: {
@@ -16,9 +11,8 @@ export declare function simpleSharedRoute(params: {
     rootIdentity?: RootBoundaryIdentity;
     originalPath?: string;
     selectedTarget: string;
-    policy: SharedMutationPolicy;
+    policy: PinnedMutationPolicySnapshot;
 }): {
     route: string;
     rootIdentity: ExactRootIdentity;
 } | undefined;
-export {};

package/dist/root-context.js

@@ -107,7 +107,7 @@ export function rootRelativeReadPath(root, filePath) {
                 resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
             });
             if (admitted)
-                return admitted.relativePath;
+                return `.${path.sep}${admitted.relativePath}`;
             continue;
         }
         const prefix = ensureTrailingSep(base);
@@ -116,7 +116,8 @@ export function rootRelativeReadPath(root, filePath) {
             let start = prefix.length;
             while (raw[start] === path.sep)
                 start += 1;
-            return raw.slice(start);
+            // An admitted absolute tail stays literal, including a leading home marker.
+            return `.${path.sep}${raw.slice(start)}`;
         }
     }
     return raw;

package/dist/root-move-noreplace.d.ts

@@ -1,13 +1,8 @@
 import { type BigIntStats, type Stats } from "node:fs";
-import { type DenyMutationPolicy } from "./deny-mutations.js";
+import type { RootMoveOptions } from "./root-options.js";
 import { type RootContext } from "./root-context.js";
-import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
-export declare function movePathNoReplaceNative(root: RootContext, params: {
-    assertBeforeMutation?: () => void;
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}, paths: {
+export declare function movePathNoReplaceNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
     sourcePath: string;
     sourceParentPath: string;
     targetPath: string;

package/dist/root-paths.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvePathWithinRootParams } from "./path-scope-lexical.js";
 import { type DirectoryResult } from "./root-directory.js";
 export { resolvePathWithinRoot } from "./root-paths-lexical.js";
 export { ensureDirectoryWithinRoot } from "./root-directory.js";
@@ -44,12 +45,7 @@ export type PathScope = {
         mode?: number;
     }): Promise<DirectoryResult>;
 };
-export declare function resolveWritablePathWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultFileName?: string;
-}): Promise<{
+export declare function resolveWritablePathWithinRoot(params: ResolvePathWithinRootParams): Promise<{
     ok: true;
     path: string;
 } | {

package/dist/root-remove-identity.d.ts

@@ -1,9 +1,7 @@
 import type { BigIntStats } from "node:fs";
 type ExactDirectoryIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
-export type RemovalDirectoryAssertion = Readonly<{
+export type RemovalDirectoryAssertion = ExactDirectoryIdentity & Readonly<{
     path: string;
-    dev: bigint;
-    ino: bigint;
     numericDev?: number;
     numericIno?: number;
     platform: NodeJS.Platform;

package/dist/root-walk.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { expandRelativePathWithHome } from "./root-context.js";
 import { resolveRootPath, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
 function validateBudget(name, value) {
@@ -65,9 +66,10 @@ export async function* walkRoot(root, relativePath, options) {
         options.signal?.throwIfAborted();
         let listing;
         try {
+            const expandedDirectory = depth === 0 ? await expandRelativePathWithHome(directory) : directory;
             const skipChildSymlinks = depth > 0 && options.symlinkPolicy === "skip";
             const resolvedDirectory = await resolveRootPath({
-                absolutePath: path.resolve(root.rootReal, directory),
+                absolutePath: path.resolve(root.rootReal, expandedDirectory),
                 rootPath: root.rootReal,
                 rootCanonicalPath: root.rootReal,
                 boundaryLabel: "root walk",
@@ -87,7 +89,10 @@ export async function* walkRoot(root, relativePath, options) {
                 .relative(root.rootReal, resolvedDirectory.canonicalPath)
                 .split(path.sep)
                 .join(path.posix.sep);
-            listing = await root.list(listingDirectory, {
+            if (depth === 0 && expandedDirectory !== directory)
+                directory = listingDirectory;
+            // Resolved filesystem names are literal, not caller home-directory shorthand.
+            listing = await root.list(`./${listingDirectory}`, {
                 order: options.order ?? "sorted",
                 signal: options.signal,
                 snapshot: maxEntries === Number.POSITIVE_INFINITY,
@@ -139,7 +144,7 @@ export async function* walkRoot(root, relativePath, options) {
                     if (!resolved.exists) {
                         continue;
                     }
-                    const target = await root.stat(path.relative(root.rootReal, resolved.canonicalPath));
+                    const target = await root.stat(`./${path.relative(root.rootReal, resolved.canonicalPath)}`);
                     kind = target.isDirectory ? "directory" : target.isFile ? "file" : "other";
                     size = target.size;
                 }

package/dist/root-write-admission.js

@@ -14,7 +14,7 @@ import { mutationSymlinkResolution, } from "./root-symlink-policy.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { assertPreparedRootWriteParentCurrent, } from "./root-write-complete-parent.js";
+import { assertPreparedRootWriteParentCurrent, writeSelectionChanged, } from "./root-write-complete-parent.js";
 export function createRootWriteSelectionForFd(selection, fd) {
     const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }));
     return Object.freeze({
@@ -22,9 +22,6 @@ export function createRootWriteSelectionForFd(selection, fd) {
         identity: Object.freeze({ dev: stat.dev, ino: stat.ino }),
     });
 }
-function writeSelectionChanged(cause) {
-    return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
-}
 function inspectRegularSelectionPath(pathname, expected, follow) {
     let observed;
     try {

package/dist/root-write-complete-parent.d.ts

@@ -1,5 +1,6 @@
 import type { BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
 import type { RootContext } from "./root-context.js";
 import type { GuardedRootWriteTarget } from "./root-write-admission.js";
 type PreparedWriteTargetObservation = Readonly<{
@@ -36,6 +37,7 @@ export type SharedRootWriteTarget = Readonly<{
     mutationAdmission: GuardedRootWriteTarget["mutationAdmission"];
     preparedParent?: PreparedRootWriteParent;
 }>;
+export declare function writeSelectionChanged(cause?: unknown): FsSafeError;
 export declare function assertPreparedRootWriteParentCurrent(prepared: PreparedRootWriteParent, verifyTarget?: boolean): void;
 export declare function prepareSharedRootWriteTarget(root: RootContext, params: SharedRootWriteTargetParams): Promise<SharedRootWriteTarget>;
 export {};

package/dist/root-write-complete-parent.js

@@ -12,7 +12,7 @@ import { errorCauseOptions } from "./root-errors.js";
 import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-function writeSelectionChanged(cause) {
+export function writeSelectionChanged(cause) {
     return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
 }
 function ordinarySharedWriteRoute(root, relativePath, operationTargetPath) {

package/dist/secret-file.d.ts

@@ -13,7 +13,11 @@ type SecretFileWriteParams = {
     dirMode?: number;
     durable?: boolean;
 };
-export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParams, "content">): Promise<{
+type SecretFileCreateParams = Omit<SecretFileWriteParams, "durable"> & {
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export declare function prepareSecretFileWrite(params: Pick<SecretFileWriteParams, "rootDir" | "filePath" | "mode" | "dirMode">): Promise<{
     mode: number;
     rootGuard: AsyncDirectoryGuard<BigIntStats>;
     parentGuard: AsyncDirectoryGuard<BigIntStats>;
@@ -21,5 +25,5 @@ export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParam
     finalFilePath: string;
 }>;
 export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
-export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
+export declare function createSecretFileAtomic(params: SecretFileCreateParams): Promise<void>;
 export {};

package/dist/secret-file.js

@@ -285,6 +285,7 @@ async function materializeSecretFileAtomic(params, createOnly) {
         mode,
         verifyPosixMode: true,
         sync: params.durable !== false,
+        strictFileSync: createOnly && params.durable === "file",
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },

package/dist/secure-file-windows.js

@@ -1,15 +1,11 @@
-import { FsSafeError } from "./errors.js";
 import { fileIdentityMismatchError } from "./strict-file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 import { warnNativeFallback } from "./native-fallback-warning.js";
 import { inspectWindowsDescriptorCommand } from "./windows-security-command.js";
-import { validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
+import { unverified as permissionUnverified, validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
 const IDENTITY_RE = /^([0-9a-f]{8}):([0-9a-f]{16})$/;
 const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators"]);
-function permissionUnverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }

package/dist/sidecar-lock-admission-parser.d.ts

@@ -1,7 +1,7 @@
 import type { Root } from "./root-impl.js";
 import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
 import { readSidecarLockRawSnapshot, type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
-type SidecarAdmissionRunner = {
+export type SidecarAdmissionRunner = {
     hasToken(): boolean;
     run<T>(callback: () => T): T;
 };
@@ -39,4 +39,3 @@ export declare function observeHeldSidecarParser(params: {
     parserAccessor(): ((raw: string) => unknown) | undefined;
     isTransientDenial(error: unknown): boolean;
 }): Promise<HeldSidecarParserObservation>;
-export {};

package/dist/sidecar-lock-handle.d.ts

@@ -1,5 +1,4 @@
-import type { Root } from "./root-impl.js";
-import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
 import type { SidecarLockHandle } from "./sidecar-lock-types.js";
 export declare function stopSidecarLockMonitoring(held: {
     compromiseTimer?: NodeJS.Timeout;
@@ -14,12 +13,7 @@ export declare function createSidecarLockHandle(params: {
 }): SidecarLockHandle;
 export declare function createHeldSidecarLockHandle(params: {
     normalizedTargetPath: string;
-    held: {
-        lockPath: string;
-        snapshot: SidecarLockSnapshot;
-        lockRoot?: Root;
-        parsePayload?: (raw: string) => unknown;
-    };
+    held: Pick<HeldSidecarLock, "lockPath" | "snapshot" | "lockRoot" | "parsePayload">;
     release: (options?: {
         retry?: boolean;
     }) => Promise<unknown>;

package/dist/sidecar-lock-policy.d.ts

@@ -1,4 +1,4 @@
-import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+import type { SidecarLockReclaimParams, SidecarLockRetryOptions } from "./sidecar-lock-types.js";
 export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
 export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
 export declare function validateSidecarLockStaleMs(staleMs: number | undefined): void;
@@ -11,9 +11,4 @@ export declare function sidecarLockRetryDelay(retry: SidecarLockRetryOptions, ti
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
 export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
-export declare function defaultSidecarLockShouldReclaim(params: {
-    lockPath: string;
-    payload: unknown;
-    staleMs: number;
-    nowMs: number;
-}): Promise<boolean>;
+export declare function defaultSidecarLockShouldReclaim(params: Pick<SidecarLockReclaimParams, "lockPath" | "payload" | "staleMs" | "nowMs">): Promise<boolean>;

package/dist/sidecar-lock-stale-admission.d.ts

@@ -1,11 +1,7 @@
 import { type SidecarReclaimGuard } from "./sidecar-lock-reclaim.js";
-import { type SidecarLockParserState } from "./sidecar-lock-admission-parser.js";
+import { type SidecarLockParserState, type SidecarAdmissionRunner } from "./sidecar-lock-admission-parser.js";
 import type { Root } from "./root-impl.js";
 import type { SidecarLockAcquireOptions } from "./sidecar-lock-types.js";
-type SidecarAdmissionRunner = {
-    hasToken(): boolean;
-    run<T>(callback: () => T): T;
-};
 type StaleOptions = Pick<SidecarLockAcquireOptions<Record<string, unknown>>, "shouldReclaim" | "shouldRemoveStaleLock" | "staleRecovery">;
 export type SidecarLockStaleOptionsState = {
     shouldReclaimObserved?: boolean;

package/dist/test-hooks.d.ts

@@ -25,7 +25,7 @@ export type FsSafeTestHooks = {
     beforeTempWorkspaceNativeRemovalSync?: (quarantinePath: string) => void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
     afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
-    beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
+    beforePublishDirectorySync?: NonNullable<FsSafeTestHooks["afterPublishTargetCreated"]>;
 };
 export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
 export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;

package/dist/windows-security-command.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { FsSafeError } from "./errors.js";
 import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
-import { parseWindowsSecurityCommandFacts } from "./windows-security-facts.js";
+import { parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TERMINATION_GRACE_MS = 1_000;
 const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
@@ -50,9 +50,6 @@ function command(operation, params) {
         },
     };
 }
-function unverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/dist/windows-security-facts.d.ts

@@ -1,4 +1,5 @@
 import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+export declare function unverified(message: string, cause?: unknown): never;
 /** Raw reporting retains unknown flag bits; secure admission validates them below. */
 export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
 /** Native and command observations share the same fail-closed admission policy. */

package/dist/windows-security-facts.js

@@ -6,8 +6,8 @@ const WORLD_SIDS = new Set([
     "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
     "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
 ]);
-function unverified(message) {
-    throw new FsSafeError("permission-unverified", message);
+export function unverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
 }
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);

package/docs/archive.md

@@ -238,6 +238,8 @@ directory paths. For example, `./pkg//state\cache/value` is presented as
 `pkg/state/cache/value`, even with `stripComponents: 1`. Case and Unicode
 spelling are preserved. Local PAX `path`, GNU long-name, and supported ZIP
 Unicode Path names use the same canonicalization.
+A leading `~` is a literal archive entry name and is never expanded to the
+user's home directory during extraction, publication, or durability checks.
 Callbacks follow physical archive order, including ZIP names that look like
 integer object keys. The public ZIP loader's `files` object retains ordinary
 JavaScript object enumeration and mutation behavior.

package/docs/copy.md

@@ -74,6 +74,8 @@ Native Windows byte copies can store large zero-filled chunks as sparse ranges w
 
 The ReFS backend rejects files with alternate data streams and unsupported reparse-point types instead of silently losing their contents. Symbolic links and junctions are preserved.
 
+Failed ReFS clones attempt to remove their partial output through the retained directory handles. On Windows versions that reject the ignore-readonly deletion flag, clone rollback retries without that flag so ordinary output can be removed. It never clears readonly attributes: readonly output can remain, and the original clone error includes the cleanup failure. Other processes retaining output handles can delay deletion beyond settlement; a failed call does not guarantee an absent destination.
+
 XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
 
 `readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.

package/docs/file-store.md

@@ -101,6 +101,11 @@ such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
 as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
 Windows rejects that spelling as stream syntax.
 
+Keys such as `~` and `~/state.json` name literal entries inside the store; they
+do not expand the user's home directory. Reads, writes, removal, and pruning
+all use that literal identity. The `Root` returned by `root()` retains its own
+home-expansion behavior.
+
 Validation retains each method's operation order. Async reads, `exists`, and
 `remove` open the root first: if the root is missing, strict methods report
 `not-found` and `readTextIfExists` / `readJsonIfExists` return `null`, even for an

package/docs/guest.md

@@ -119,7 +119,13 @@ publication failure preserves the existing destination and source link; ordinary
 failure cleanup removes the staging directory.
 
 Cross-device directory moves build a copy manifest and check it during source
-cleanup. Source changes can leave the published destination and some or all
+cleanup. Directory creation keeps the source mode subject to the guest's umask;
+mode `000` is not replaced with a default. A top-level mode-000 directory uses
+owner-only staging until publication, then restores zero through its retained
+descriptor. Reading a mode-000 source still requires sufficient OS privileges;
+the guest does not change source permissions to gain access. A permission error
+after publication preserves the source and published copy for reconciliation.
+Source changes can leave the published destination and some or all
 of the source. Regular-file and symlink move fallbacks unlink the source
 pathname after publication; they do not perform the directory manifest's
 identity checks. Directory cleanup also has check-to-unlink race windows.

package/docs/native-helper.md

@@ -107,6 +107,12 @@ normalization, and the decision to fall back.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
 - Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
 
+Linux root lookups reject negative descriptor sentinels before borrowing a handle or resolving a relative path; they never substitute the process working directory for an admitted root. Public Root operations already supply retained, admitted handles.
+
+On Linux and macOS, native asynchronous file-copy admission rejects negative source and parent descriptors before creating a stage, preserving source-before-parent error ordering. Callers must keep nonnegative source and parent descriptors open until the operation settles.
+
+Low-level Unix query, hash, copy, clone, staging, and owned-tree cleanup calls also reject negative descriptors before using them, preserving each operation's path-validation, cancellation, and cleanup order. Descriptor-relative mutations never accept a working-directory sentinel as a retained capability. On modern macOS, beneath opens reject negative roots with `EBADF` before calling `openat`, rather than returning `EIO` after an OS failure or working-directory operation. This check does not establish the validity of arbitrary nonnegative integers: callers must supply live descriptors and retain them until synchronous calls return or asynchronous operations settle.
+
 `replaceDirectoryAtomic()` requires `renameNoReplaceWithIdentity` before it
 creates a missing target parent. On POSIX the dedicated entry point keeps the
 existing pre-dispatch exact receipt fence but dispatches direct-child names

package/docs/root.md

@@ -24,7 +24,7 @@ type RootDefaults = {
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
   mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
-  mode?: number;                   // file mode applied to new writes; per-call override available
+  mode?: number;                   // requested file mode; per-call override available
   nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
   renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // read policy
@@ -117,6 +117,10 @@ created through a directory symlink or Windows junction. An absolute path
 outside the root is still rejected. On Windows, alternate casing is accepted
 only when the differently cased Root prefix has the Root's exact directory
 identity; the operation then continues under the trusted Root spelling.
+Absolute paths keep literal `~` components: `readAbsolute("/srv/root/~/file")`
+reads that entry under the root, without expanding the user's home directory.
+Relative `~/file` inputs still expand the home directory and must remain inside
+the Root; use `./~/file` for a literal relative `~` directory.
 
 ### Writes
 
@@ -153,6 +157,11 @@ await fs.create("private-data/credential", "synthetic credential", { private: tr
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+For `append` and `openWritable`, `mode` only affects new-file creation: POSIX
+permissions remain subject to the process umask. These methods do not chmod
+existing files. Replacement and create-only writes apply their final mode
+through the retained descriptor; see [Writing](writing.md#write-options).
+
 Buffered `create` and `createJson` also accept `atomic?: boolean`. With `true`,
 complete content is staged before exclusive publication even in native-off mode;
 the fallback requires hardlinks. Omitted or `false` keeps the existing buffered

package/docs/secret-file.md

@@ -228,6 +228,15 @@ if anything already occupies the target path it throws
 `FsSafeError("secret-exists")` without modifying that entry. Use the distinct
 name when first-writer-wins is part of the credential protocol.
 
+Its `durable` option also accepts `"file"`, matching `Root.create()`. This
+requires every file `fsync` to succeed, including on `EPERM`, while parent-directory
+synchronization remains best effort. The default and boolean options retain their
+existing behavior. `writeSecretFileAtomic()` continues to accept boolean durability.
+
+Strict file synchronization preserves the existing publication strategy and
+identity-checked cleanup. A failed file flush before staged publication prevents
+publication; a failure after publication can leave the complete file present.
+
 Distinct leaves can share missing-parent creation without a `secret-exists`
 error. Concurrent creates at the same leaf still have exactly one winner;
 the loser receives `secret-exists` and leaves the winner's bytes intact.
@@ -244,6 +253,7 @@ try {
     rootDir: "/var/lib/app/credentials",
     filePath: "/var/lib/app/credentials/provider.refresh-token",
     content: refreshToken,
+    durable: "file",
   });
 } catch (error) {
   if (!(error instanceof FsSafeError) || error.code !== "secret-exists") throw error;

package/docs/walk.md

@@ -113,6 +113,18 @@ typed `FsSafeError("too-large")` instead.
 
 For followed symlinks, both `kind` and `size` describe the resolved target.
 
+The caller's starting path retains Root home shorthand: `~` and `~/dir` expand
+the home directory when iteration starts and must resolve inside the Root.
+Home-started walks report actual Root-relative paths, such as `home/dir/file`,
+rather than `~/dir/file`. Use `./~/dir` to start at a literal `~` directory.
+An alias within a home-started path is reported under its admitted canonical
+target; ordinary non-home starting aliases retain their caller-supplied spelling.
+
+Entry names remain literal filesystem data, including a directory named `~`
+and its descendants. To reuse an entry path in another Root method without
+home-directory expansion, prefix it with `./`, as in
+`capability.open("./" + entry.relativePath)`.
+
 The default `order: "sorted"` visits each directory's names in lexicographic
 order before descending depth first. It reads and sorts all names in each
 visited directory. With `maxEntries`, it prepares small metadata batches capped

package/docs/writing.md

@@ -301,6 +301,12 @@ type RootWriteJsonOptions = RootWriteOptions & {
 
 Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. `durable: false` skips both syncs. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
 
+`mode` selects the creation mode, defaulting to `0o600` when neither the call nor
+the Root supplies it. On POSIX, the process umask can further restrict that mode;
+for example, `mode: 0o640` with umask `0o077` creates a `0o600` file. Existing
+files are not chmodded, even when an explicit `mode` is supplied. Empty appends
+use the same creation rules.
+
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);
 await fs.append("notes/scratch.md", "* new bullet", { prependNewlineIfNeeded: true });
@@ -522,6 +528,11 @@ destination — there is no atomic-rename step. For exclusive publication of a
 complete stream, use [`create()`](#streamed-creation). For streamed replacement,
 the [`atomic`](atomic.md) helpers provide a staged writer.
 
+For all three write modes, `mode` only selects new-file creation permissions,
+defaulting to `0o600` when neither the call nor the Root supplies it. POSIX
+permissions remain subject to the process umask; existing files are not chmodded.
+The returned numeric `stat` records the admitted descriptor before caller writes.
+
 On POSIX, existing-target opens use `O_NONBLOCK` as an admission safeguard so
 a no-reader FIFO cannot stall regular-file validation. This does not change
 ordinary regular-file write semantics. `replace` and `update` remain write-only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -169,13 +169,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.18.2",
-    "@openclaw/fs-safe-darwin-x64": "0.18.2",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.18.2",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.18.2",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.18.2",
-    "@openclaw/fs-safe-linux-x64-musl": "0.18.2",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.18.2",
+    "@openclaw/fs-safe-darwin-arm64": "0.19.0",
+    "@openclaw/fs-safe-darwin-x64": "0.19.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.19.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.19.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.19.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.19.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.19.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {