@openclaw/fs-safe 0.1.1 → 0.2.0

package/dist/{safe-root.js → root-impl.js}

@@ -1,19 +1,27 @@
 import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
+import { createBoundedReadStream } from "./bounded-read-stream.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { isPinnedPathHelperSpawnError, runPinnedPathHelper } from "./pinned-path.js";
-import { runPinnedWriteHelper } from "./pinned-write.js";
-import { expandHomePrefix } from "./home-dir.js";
+import { runPinnedCopyHelper, runPinnedWriteHelper } from "./pinned-write.js";
+import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
 import { assertNoPathAliasEscape, PATH_ALIAS_POLICIES } from "./path-policy.js";
-import { hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
-import { helperReaddir, helperStat, runPinnedHelper } from "./pinned-helper.js";
+import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
+import { helperReaddir, helperStat, runPinnedHelper, } from "./pinned-helper.js";
+import { pathStatFromStats } from "./path-stat.js";
 import { resolveRootPath } from "./root-path.js";
+import { assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, } from "./root-context.js";
+import { isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+import { serializePathWrite } from "./write-queue.js";
 function logWarn(message) {
     if (process.env.FS_SAFE_DEBUG_WARNINGS === "1") {
         console.warn(message);
@@ -36,21 +44,19 @@ const OPEN_APPEND_CREATE_FLAGS = fsConstants.O_RDWR |
     fsConstants.O_CREAT |
     fsConstants.O_EXCL |
     (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-const ensureTrailingSep = (value) => (value.endsWith(path.sep) ? value : value + path.sep);
-let cachedHomePath;
-async function expandRelativePathWithHome(relativePath) {
-    const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
-    if (cachedHomePath?.raw !== rawHome) {
-        let realHome = rawHome;
-        try {
-            realHome = await fs.realpath(rawHome);
-        }
-        catch {
-            // If the home dir cannot be canonicalized, keep lexical expansion behavior.
-        }
-        cachedHomePath = { raw: rawHome, real: realHome };
-    }
-    return expandHomePrefix(relativePath, { home: cachedHomePath.real });
+export const DEFAULT_ROOT_MAX_BYTES = 16 * 1024 * 1024;
+function closeHandleForDispose(handle) {
+    return handle.close().catch(() => undefined);
+}
+function openResult(params) {
+    return {
+        handle: params.handle,
+        realPath: params.realPath,
+        stat: params.stat,
+        [Symbol.asyncDispose]: async () => {
+            await closeHandleForDispose(params.handle);
+        },
+    };
 }
 async function openVerifiedLocalFile(filePath, options) {
     const fsSafeTestHooks = getFsSafeTestHooks();
@@ -71,7 +77,7 @@ async function openVerifiedLocalFile(filePath, options) {
     }
     let handle;
     try {
-        const openFlags = options?.symlinkPolicy === "follow-within-root"
+        const openFlags = options?.symlinks === "follow-within-root"
             ? options?.nonBlockingRead
                 ? OPEN_READ_FOLLOW_NONBLOCK_FLAGS
                 : OPEN_READ_FOLLOW_FLAGS
@@ -106,10 +112,10 @@ async function openVerifiedLocalFile(filePath, options) {
         if (!stat.isFile()) {
             throw new FsSafeError("not-file", "not a file");
         }
-        if (options?.rejectHardlinks && stat.nlink > 1) {
+        if (options?.hardlinks === "reject" && stat.nlink > 1) {
             throw new FsSafeError("hardlink", "hardlinked path not allowed");
         }
-        if (options?.symlinkPolicy === "follow-within-root") {
+        if (options?.symlinks === "follow-within-root") {
             const pathStat = await fs.stat(filePath);
             if (!sameFileIdentity(stat, pathStat)) {
                 throw new FsSafeError("path-mismatch", "path changed during read");
@@ -126,13 +132,13 @@ async function openVerifiedLocalFile(filePath, options) {
         }
         const realPath = await resolveOpenedFileRealPathForHandle(handle, filePath);
         const realStat = await fs.stat(realPath);
-        if (options?.rejectHardlinks && realStat.nlink > 1) {
+        if (options?.hardlinks === "reject" && realStat.nlink > 1) {
             throw new FsSafeError("hardlink", "hardlinked path not allowed");
         }
         if (!sameFileIdentity(stat, realStat)) {
             throw new FsSafeError("path-mismatch", "path mismatch");
         }
-        return { handle, realPath, stat };
+        return openResult({ handle, realPath, stat });
     }
     catch (err) {
         await handle.close().catch(() => { });
@@ -145,35 +151,7 @@ async function openVerifiedLocalFile(filePath, options) {
         throw err;
     }
 }
-async function resolveSafeRootContext(rootDir) {
-    let rootReal;
-    try {
-        rootReal = await fs.realpath(rootDir);
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "root dir not found");
-        }
-        throw err;
-    }
-    return {
-        rootDir: path.resolve(rootDir),
-        rootReal,
-        rootWithSep: ensureTrailingSep(rootReal),
-    };
-}
-async function resolvePathInSafeRoot(root, relativePath) {
-    const expanded = await expandRelativePathWithHome(relativePath);
-    const resolved = path.resolve(root.rootWithSep, expanded);
-    if (!isPathInside(root.rootWithSep, resolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
-}
-async function resolvePathWithinRoot(params) {
-    return await resolvePathInSafeRoot(await resolveSafeRootContext(params.rootDir), params.relativePath);
-}
-export class SafeRoot {
+class RootHandle {
     rootDir;
     rootReal;
     rootWithSep;
@@ -192,75 +170,90 @@ export class SafeRoot {
         };
     }
     async resolve(relativePath) {
-        return (await resolvePathInSafeRoot(this.context, relativePath)).resolved;
+        return (await resolvePathInRoot(this.context, relativePath)).resolved;
     }
-    async openFile(relativePath, options = {}) {
-        return await openFileInSafeRoot(this.context, {
+    async open(relativePath, options = {}) {
+        return await openFileInRoot(this.context, {
             relativePath,
-            ...this.defaults.read,
-            ...this.defaults.open,
+            ...readDefaults(this.defaults),
             ...options,
         });
     }
-    async readFile(relativePath, options = {}) {
-        return await readFileInSafeRoot(this.context, {
+    async read(relativePath, options = {}) {
+        return await readFileInRoot(this.context, {
             relativePath,
-            ...this.defaults.read,
+            ...readDefaults(this.defaults),
             ...options,
         });
     }
-    async readFileBytes(relativePath, options = {}) {
-        return (await this.readFile(relativePath, options)).buffer;
+    async readBytes(relativePath, options = {}) {
+        return (await this.read(relativePath, options)).buffer;
     }
     async readText(relativePath, options = {}) {
         const { encoding = "utf8", ...readOptions } = options;
-        return (await this.readFile(relativePath, readOptions)).buffer.toString(encoding);
+        return (await this.read(relativePath, readOptions)).buffer.toString(encoding);
     }
     async readJson(relativePath, options = {}) {
         return JSON.parse(await this.readText(relativePath, options));
     }
-    async readPath(filePath, options = {}) {
-        return await readPathInSafeRoot(this.context, { filePath, ...this.defaults.read, ...options });
+    async readAbsolute(filePath, options = {}) {
+        return await readPathInRoot(this.context, {
+            filePath,
+            ...readDefaults(this.defaults),
+            ...options,
+        });
     }
     reader(options = {}) {
         return async (filePath) => {
-            return (await this.readPath(filePath, options)).buffer;
+            return (await this.readAbsolute(filePath, options)).buffer;
         };
     }
     async openWritable(relativePath, options = {}) {
-        return await openWritableFileInSafeRoot(this.context, {
+        const writeMode = options.writeMode ?? "replace";
+        return await openWritableFileInRoot(this.context, {
             relativePath,
-            ...this.defaults.openWritable,
+            mkdir: this.defaults.mkdir,
+            mode: this.defaults.mode,
             ...options,
+            append: writeMode === "append",
+            truncateExisting: writeMode === "replace",
         });
     }
     async append(relativePath, data, options = {}) {
-        await appendFileInSafeRoot(this.context, {
+        await appendFileInRoot(this.context, {
             relativePath,
             data,
-            ...this.defaults.append,
+            mkdir: this.defaults.mkdir,
+            mode: this.defaults.mode,
             ...options,
         });
     }
-    async removeFile(relativePath) {
-        await removePathInSafeRoot(this.context, relativePath);
+    async remove(relativePath) {
+        assertValidRootRelativePath(relativePath);
+        await removePathInRoot(this.context, relativePath);
+    }
+    async mkdir(relativePath) {
+        assertValidRootRelativePath(relativePath);
+        await mkdirPathInRoot(this.context, { relativePath });
     }
-    async mkdirp(relativePath, options = {}) {
-        await mkdirPathInSafeRoot(this.context, { relativePath, ...options });
+    async ensureRoot() {
+        await mkdirPathInRoot(this.context, { relativePath: "", allowRoot: true });
     }
-    async writeFile(relativePath, data, options = {}) {
-        await writeFileInSafeRoot(this.context, {
+    async write(relativePath, data, options = {}) {
+        await writeFileInRoot(this.context, {
             relativePath,
             data,
-            ...this.defaults.write,
+            mkdir: this.defaults.mkdir,
+            mode: this.defaults.mode,
             ...options,
         });
     }
-    async createFile(relativePath, data, options = {}) {
-        return await writeFileInSafeRoot(this.context, {
+    async create(relativePath, data, options = {}) {
+        await writeFileInRoot(this.context, {
             relativePath,
             data,
-            ...this.defaults.write,
+            mkdir: this.defaults.mkdir,
+            mode: this.defaults.mode,
             ...options,
             overwrite: false,
         });
@@ -268,47 +261,103 @@ export class SafeRoot {
     async writeJson(relativePath, data, options = {}) {
         const { replacer, space, trailingNewline = true, ...writeOptions } = options;
         const json = JSON.stringify(data, replacer, space);
-        await this.writeFile(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
+        await this.write(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
     }
     async createJson(relativePath, data, options = {}) {
         const { replacer, space, trailingNewline = true, ...writeOptions } = options;
         const json = JSON.stringify(data, replacer, space);
-        return await this.createFile(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
+        await this.create(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
     }
-    async copyFileFrom(sourcePath, relativePath, options = {}) {
-        await copyFileInSafeRoot(this.context, {
+    async copyIn(relativePath, sourcePath, options = {}) {
+        assertValidRootRelativePath(relativePath);
+        await copyFileInRoot(this.context, {
             sourcePath,
             relativePath,
-            ...this.defaults.copy,
+            maxBytes: this.defaults.maxBytes,
+            mkdir: this.defaults.mkdir,
+            mode: this.defaults.mode,
             ...options,
         });
     }
-    async statPath(relativePath) {
-        return await helperStat(this.rootReal, relativePath);
+    async exists(relativePath) {
+        try {
+            await this.stat(relativePath);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof FsSafeError && err.code === "not-found") {
+                return false;
+            }
+            throw err;
+        }
     }
-    async listDir(relativePath, options = {}) {
-        return options.withFileTypes === true
-            ? await helperReaddir(this.rootReal, relativePath, true)
-            : await helperReaddir(this.rootReal, relativePath, false);
+    async stat(relativePath) {
+        assertValidRootRelativePath(relativePath);
+        try {
+            return await helperStat(this.rootReal, relativePath);
+        }
+        catch (error) {
+            if (canFallbackFromPythonError(error)) {
+                return await statPathFallback(this.context, relativePath);
+            }
+            throw error;
+        }
     }
-    async move(from, to, options = {}) {
-        await runPinnedHelper("rename", this.rootReal, {
-            from,
-            overwrite: options.overwrite ?? true,
-            to,
-        });
+    async list(relativePath, options = {}) {
+        assertValidRootRelativePath(relativePath);
+        try {
+            return options.withFileTypes === true
+                ? await helperReaddir(this.rootReal, relativePath, true)
+                : await helperReaddir(this.rootReal, relativePath, false);
+        }
+        catch (error) {
+            if (canFallbackFromPythonError(error)) {
+                return await listPathFallback(this.context, relativePath, options.withFileTypes === true);
+            }
+            throw error;
+        }
+    }
+    async move(fromRelative, toRelative, options = {}) {
+        assertValidRootRelativePath(fromRelative);
+        assertValidRootRelativePath(toRelative);
+        try {
+            await runPinnedHelper("rename", this.rootReal, {
+                from: fromRelative,
+                overwrite: options.overwrite ?? false,
+                to: toRelative,
+            });
+        }
+        catch (error) {
+            if (canFallbackFromPythonError(error)) {
+                await movePathFallback(this.context, {
+                    fromRelative,
+                    overwrite: options.overwrite ?? false,
+                    toRelative,
+                });
+                return;
+            }
+            throw error;
+        }
     }
 }
-export async function safeRoot(rootDir, defaults = {}) {
-    return new SafeRoot(await resolveSafeRootContext(rootDir), defaults);
+function readDefaults(defaults) {
+    return {
+        hardlinks: defaults.hardlinks,
+        maxBytes: defaults.maxBytes ?? DEFAULT_ROOT_MAX_BYTES,
+        nonBlockingRead: defaults.nonBlockingRead,
+        symlinks: defaults.symlinks,
+    };
+}
+export async function root(rootDir, defaults = {}) {
+    return new RootHandle(await resolveRootContext(rootDir), defaults);
 }
-async function openFileInSafeRoot(root, params) {
-    const { rootWithSep, resolved } = await resolvePathInSafeRoot(root, params.relativePath);
+async function openFileInRoot(root, params) {
+    const { rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath);
     let opened;
     try {
         opened = await openVerifiedLocalFile(resolved, {
             nonBlockingRead: params.nonBlockingRead,
-            symlinkPolicy: params.symlinkPolicy,
+            symlinks: params.symlinks,
         });
     }
     catch (err) {
@@ -317,7 +366,7 @@ async function openFileInSafeRoot(root, params) {
         }
         throw err;
     }
-    if (params.rejectHardlinks !== false && opened.stat.nlink > 1) {
+    if (params.hardlinks !== "allow" && opened.stat.nlink > 1) {
         await opened.handle.close().catch(() => { });
         throw new FsSafeError("hardlink", "hardlinked path not allowed");
     }
@@ -327,8 +376,8 @@ async function openFileInSafeRoot(root, params) {
     }
     return opened;
 }
-async function readFileInSafeRoot(root, params) {
-    const opened = await openFileInSafeRoot(root, params);
+async function readFileInRoot(root, params) {
+    const opened = await openFileInRoot(root, params);
     try {
         return await readOpenedFileSafely({ opened, maxBytes: params.maxBytes });
     }
@@ -336,16 +385,18 @@ async function readFileInSafeRoot(root, params) {
         await opened.handle.close().catch(() => { });
     }
 }
-async function readPathInSafeRoot(root, params) {
+async function readPathInRoot(root, params) {
     const rootDir = root.rootDir;
     const candidatePath = path.isAbsolute(params.filePath)
         ? path.resolve(params.filePath)
         : path.resolve(rootDir, params.filePath);
     const relativePath = path.relative(rootDir, candidatePath);
-    return await readFileInSafeRoot(root, {
+    return await readFileInRoot(root, {
         relativePath,
-        rejectHardlinks: params.rejectHardlinks,
+        hardlinks: params.hardlinks,
         maxBytes: params.maxBytes,
+        nonBlockingRead: params.nonBlockingRead,
+        symlinks: params.symlinks,
     });
 }
 export async function readLocalFileSafely(params) {
@@ -358,6 +409,7 @@ export async function readLocalFileSafely(params) {
     }
 }
 export async function openLocalFileSafely(params) {
+    assertNoNulPathInput(params.filePath, "file path contains a NUL byte");
     return await openVerifiedLocalFile(params.filePath);
 }
 async function readOpenedFileSafely(params) {
@@ -365,6 +417,9 @@ async function readOpenedFileSafely(params) {
         throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${params.opened.stat.size})`);
     }
     const buffer = await params.opened.handle.readFile();
+    if (params.maxBytes !== undefined && buffer.byteLength > params.maxBytes) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${buffer.byteLength})`);
+    }
     return {
         buffer,
         realPath: params.opened.realPath,
@@ -379,6 +434,9 @@ function buildAtomicWriteTempPath(targetPath) {
     const base = path.basename(targetPath);
     return path.join(dir, `.${base}.${process.pid}.${randomUUID()}.tmp`);
 }
+function rootWriteQueueKey(root, relativePath) {
+    return `${root.rootReal}\0${relativePath}`;
+}
 async function writeTempFileForAtomicReplace(params) {
     const tempHandle = await fs.open(params.tempPath, OPEN_WRITE_CREATE_FLAGS, params.mode);
     try {
@@ -395,7 +453,7 @@ async function writeTempFileForAtomicReplace(params) {
     }
 }
 async function verifyAtomicWriteResult(params) {
-    const opened = await openVerifiedLocalFile(params.targetPath, { rejectHardlinks: true });
+    const opened = await openVerifiedLocalFile(params.targetPath, { hardlinks: "reject" });
     try {
         if (!sameFileIdentity(opened.stat, params.expectedIdentity)) {
             throw new FsSafeError("path-mismatch", "path changed during write");
@@ -482,8 +540,8 @@ async function resolveOpenedFileRealPathFromParent(handleStat, ioPath) {
     }
     return null;
 }
-async function openWritableFileInSafeRoot(root, params) {
-    const { rootReal, rootWithSep, resolved } = await resolvePathInSafeRoot(root, params.relativePath);
+async function openWritableFileInRoot(root, params) {
+    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath);
     try {
         await assertNoPathAliasEscape({
             absolutePath: resolved,
@@ -495,7 +553,10 @@ async function openWritableFileInSafeRoot(root, params) {
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
     if (params.mkdir !== false) {
-        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        const parentGuard = await createNearestExistingDirectoryGuard(rootReal, path.dirname(resolved));
+        await withAsyncDirectoryGuards([parentGuard], async () => {
+            await fs.mkdir(path.dirname(resolved), { recursive: true });
+        });
     }
     let ioPath = resolved;
     try {
@@ -513,20 +574,20 @@ async function openWritableFileInSafeRoot(root, params) {
             throw err;
         }
     }
-    const fileMode = params.mode ?? 0o600;
+    const mode = params.mode ?? 0o600;
     let handle;
     let createdForWrite = false;
     const existingFlags = params.append ? OPEN_APPEND_EXISTING_FLAGS : OPEN_WRITE_EXISTING_FLAGS;
     const createFlags = params.append ? OPEN_APPEND_CREATE_FLAGS : OPEN_WRITE_CREATE_FLAGS;
     try {
         try {
-            handle = await fs.open(ioPath, existingFlags, fileMode);
+            handle = await fs.open(ioPath, existingFlags, mode);
         }
         catch (err) {
             if (!isNotFoundPathError(err)) {
                 throw err;
             }
-            handle = await fs.open(ioPath, createFlags, fileMode);
+            handle = await fs.open(ioPath, createFlags, mode);
             createdForWrite = true;
         }
     }
@@ -537,6 +598,9 @@ async function openWritableFileInSafeRoot(root, params) {
         if (isSymlinkOpenError(err)) {
             throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
         }
+        if (hasNodeErrorCode(err, "EISDIR")) {
+            throw new FsSafeError("not-file", "not a file", { cause: err });
+        }
         throw err;
     }
     let realPathForCleanup = null;
@@ -584,6 +648,9 @@ async function openWritableFileInSafeRoot(root, params) {
             createdForWrite,
             realPath,
             stat,
+            [Symbol.asyncDispose]: async () => {
+                await closeHandleForDispose(handle);
+            },
         };
     }
     catch (err) {
@@ -596,10 +663,11 @@ async function openWritableFileInSafeRoot(root, params) {
         throw err;
     }
 }
-async function appendFileInSafeRoot(root, params) {
-    const target = await openWritableFileInSafeRoot(root, {
+async function appendFileInRoot(root, params) {
+    const target = await openWritableFileInRoot(root, {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
+        mode: params.mode,
         truncateExisting: false,
         append: true,
     });
@@ -627,8 +695,8 @@ async function appendFileInSafeRoot(root, params) {
         await target.handle.close().catch(() => { });
     }
 }
-async function removePathInSafeRoot(root, relativePath) {
-    const resolved = await resolvePinnedRemovePathInSafeRoot(root, relativePath);
+async function removePathInRoot(root, relativePath) {
+    const resolved = await resolvePinnedRemovePathInRoot(root, relativePath);
     if (process.platform === "win32") {
         await removePathFallback(resolved);
         return;
@@ -648,8 +716,8 @@ async function removePathInSafeRoot(root, relativePath) {
         throw normalizePinnedPathError(error);
     }
 }
-async function mkdirPathInSafeRoot(root, params) {
-    const resolved = await resolvePinnedPathInSafeRoot(root, params);
+async function mkdirPathInRoot(root, params) {
+    const resolved = await resolvePinnedPathInRoot(root, params);
     if (process.platform === "win32") {
         await mkdirPathFallback(resolved);
         return;
@@ -669,49 +737,57 @@ async function mkdirPathInSafeRoot(root, params) {
         throw normalizePinnedPathError(error);
     }
 }
-async function writeFileInSafeRoot(root, params) {
+async function writeFileInRoot(root, params) {
     if (process.platform === "win32") {
-        return await writeFileFallback(root, params);
-    }
-    const pinned = await resolvePinnedWriteTargetInSafeRoot(root, params.relativePath);
-    let identity;
-    try {
-        identity = await runPinnedWriteHelper({
-            rootPath: pinned.rootReal,
-            relativeParentPath: pinned.relativeParentPath,
-            basename: pinned.basename,
-            mkdir: params.mkdir !== false,
-            mode: pinned.mode,
-            overwrite: params.overwrite,
-            input: {
-                kind: "buffer",
-                data: params.data,
-                encoding: params.encoding,
-            },
+        await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
+            await writeFileFallback(root, params);
         });
+        return;
     }
-    catch (error) {
-        if (params.overwrite === false && isAlreadyExistsError(error)) {
-            return false;
+    const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode);
+    await serializePathWrite(pinned.targetPath, async () => {
+        let identity;
+        try {
+            identity = await runPinnedWriteHelper({
+                rootPath: pinned.rootReal,
+                relativeParentPath: pinned.relativeParentPath,
+                basename: pinned.basename,
+                mkdir: params.mkdir !== false,
+                mode: params.mode ?? pinned.mode,
+                overwrite: params.overwrite,
+                input: {
+                    kind: "buffer",
+                    data: params.data,
+                    encoding: params.encoding,
+                },
+            });
         }
-        throw normalizePinnedWriteError(error);
-    }
-    try {
-        await verifyAtomicWriteResult({
-            root,
-            targetPath: pinned.targetPath,
-            expectedIdentity: identity,
-        });
-    }
-    catch (err) {
-        emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
-        throw err;
-    }
-    return true;
+        catch (error) {
+            if (params.overwrite === false && isAlreadyExistsError(error)) {
+                throw new FsSafeError("already-exists", "file already exists", {
+                    cause: error instanceof Error ? error : undefined,
+                });
+            }
+            throw normalizePinnedWriteError(error);
+        }
+        try {
+            await verifyAtomicWriteResult({
+                root,
+                targetPath: pinned.targetPath,
+                expectedIdentity: identity,
+            });
+        }
+        catch (err) {
+            emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
+            throw err;
+        }
+    });
 }
-async function copyFileInSafeRoot(root, params) {
+async function copyFileInRoot(root, params) {
+    assertValidRootRelativePath(params.relativePath);
+    assertNoNulPathInput(params.sourcePath, "source path contains a NUL byte");
     const source = await openVerifiedLocalFile(params.sourcePath, {
-        rejectHardlinks: params.rejectSourceHardlinks,
+        hardlinks: params.sourceHardlinks,
     });
     if (params.maxBytes !== undefined && source.stat.size > params.maxBytes) {
         await source.handle.close().catch(() => { });
@@ -719,43 +795,57 @@ async function copyFileInSafeRoot(root, params) {
     }
     try {
         if (process.platform === "win32") {
-            await copyFileFallback(root, params, source);
+            await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
+                await copyFileFallback(root, params, source);
+            });
             return;
         }
-        const pinned = await resolvePinnedWriteTargetInSafeRoot(root, params.relativePath);
-        const sourceStream = source.handle.createReadStream();
-        const identity = await runPinnedWriteHelper({
-            rootPath: pinned.rootReal,
-            relativeParentPath: pinned.relativeParentPath,
-            basename: pinned.basename,
-            mkdir: params.mkdir !== false,
-            mode: pinned.mode,
-            overwrite: true,
-            input: {
-                kind: "stream",
-                stream: sourceStream,
-            },
-        }).catch((error) => {
-            throw normalizePinnedWriteError(error);
+        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode);
+        await serializePathWrite(pinned.targetPath, async () => {
+            let identity;
+            try {
+                if (getFsSafePythonConfig().mode === "off") {
+                    await copyFileFallback(root, params, source);
+                    return;
+                }
+                identity = await runPinnedCopyHelper({
+                    rootPath: pinned.rootReal,
+                    relativeParentPath: pinned.relativeParentPath,
+                    basename: pinned.basename,
+                    mkdir: params.mkdir !== false,
+                    mode: pinned.mode,
+                    overwrite: true,
+                    maxBytes: params.maxBytes,
+                    sourcePath: source.realPath,
+                    sourceIdentity: { dev: source.stat.dev, ino: source.stat.ino },
+                });
+            }
+            catch (error) {
+                if (canFallbackFromPythonError(error)) {
+                    await copyFileFallback(root, params, source);
+                    return;
+                }
+                throw normalizePinnedWriteError(error);
+            }
+            try {
+                await verifyAtomicWriteResult({
+                    root,
+                    targetPath: pinned.targetPath,
+                    expectedIdentity: identity,
+                });
+            }
+            catch (err) {
+                emitWriteBoundaryWarning(`post-copy verification failed: ${String(err)}`);
+                throw err;
+            }
         });
-        try {
-            await verifyAtomicWriteResult({
-                root,
-                targetPath: pinned.targetPath,
-                expectedIdentity: identity,
-            });
-        }
-        catch (err) {
-            emitWriteBoundaryWarning(`post-copy verification failed: ${String(err)}`);
-            throw err;
-        }
     }
     finally {
         await source.handle.close().catch(() => { });
     }
 }
-async function resolvePinnedWriteTargetInSafeRoot(root, relativePath) {
-    const { rootReal, rootWithSep, resolved } = await resolvePathInSafeRoot(root, relativePath);
+async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode) {
+    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, relativePath);
     try {
         await assertNoPathAliasEscape({
             absolutePath: resolved,
@@ -777,15 +867,15 @@ async function resolvePinnedWriteTargetInSafeRoot(root, relativePath) {
     if (!basename || basename === "." || basename === "/") {
         throw new FsSafeError("invalid-path", "invalid target path");
     }
-    let mode = 0o600;
+    let mode = requestedMode ?? 0o600;
     try {
-        const opened = await openFileInSafeRoot(root, {
+        const opened = await openFileInRoot(root, {
             relativePath,
-            rejectHardlinks: true,
+            hardlinks: "reject",
             nonBlockingRead: true,
         });
         try {
-            mode = opened.stat.mode & 0o777;
+            mode = requestedMode ?? (opened.stat.mode & 0o777);
             if (!isPathInside(rootWithSep, opened.realPath)) {
                 throw new FsSafeError("outside-workspace", "file is outside workspace root");
             }
@@ -807,33 +897,28 @@ async function resolvePinnedWriteTargetInSafeRoot(root, relativePath) {
         mode: mode || 0o600,
     };
 }
-async function resolvePinnedPathInSafeRoot(root, params) {
-    const resolved = await resolvePinnedRootPathInSafeRoot(root, {
+async function resolvePinnedPathInRoot(root, params) {
+    return await resolvePinnedOperationPathInRoot(root, {
+        allowRoot: params.allowRoot,
         relativePath: params.relativePath,
         policy: PATH_ALIAS_POLICIES.strict,
     });
-    const relativeResolved = path.relative(resolved.rootReal, resolved.canonicalPath);
-    if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
-        return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
-    }
-    if (relativeResolved === "" ||
-        relativeResolved === "." ||
-        relativeResolved.startsWith("..") ||
-        path.isAbsolute(relativeResolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    const relativePosix = relativeResolved.split(path.sep).join(path.posix.sep);
-    if (!isPathInside(resolved.rootWithSep, resolved.canonicalPath)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
 }
-async function resolvePinnedRemovePathInSafeRoot(root, relativePath) {
-    const resolved = await resolvePinnedRootPathInSafeRoot(root, {
+async function resolvePinnedRemovePathInRoot(root, relativePath) {
+    return await resolvePinnedOperationPathInRoot(root, {
         relativePath,
         policy: PATH_ALIAS_POLICIES.unlinkTarget,
     });
+}
+async function resolvePinnedOperationPathInRoot(root, params) {
+    const resolved = await resolvePinnedRootPathInRoot(root, {
+        relativePath: params.relativePath,
+        policy: params.policy,
+    });
     const relativeResolved = path.relative(resolved.rootReal, resolved.canonicalPath);
+    if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
+        return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
+    }
     if (relativeResolved === "" ||
         relativeResolved === "." ||
         relativeResolved.startsWith("..") ||
@@ -844,13 +929,9 @@ async function resolvePinnedRemovePathInSafeRoot(root, relativePath) {
     if (!isPathInside(resolved.rootWithSep, resolved.canonicalPath)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }
-    const parentRelative = path.posix.dirname(relativePosix);
-    if (parentRelative === "." || parentRelative === "") {
-        return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
-    }
     return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
 }
-async function resolvePinnedRootPathInSafeRoot(root, params) {
+async function resolvePinnedRootPathInRoot(root, params) {
     const rootReal = root.rootReal;
     let resolved;
     try {
@@ -872,54 +953,170 @@ async function resolvePinnedRootPathInSafeRoot(root, params) {
         canonicalPath: resolved.canonicalPath,
     };
 }
-function normalizePinnedWriteError(error) {
-    if (error instanceof FsSafeError) {
-        return error;
-    }
-    return new FsSafeError("invalid-path", "path is not a regular file under root", {
-        cause: error instanceof Error ? error : undefined,
-    });
+async function removePathFallback(resolved) {
+    const guard = await createAsyncDirectoryGuard(path.dirname(resolved.resolved));
+    await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("remove", resolved.resolved);
+    await assertAsyncDirectoryGuard(guard);
+    await ((await fs.lstat(resolved.resolved)).isDirectory() ? fs.rmdir(resolved.resolved) : fs.rm(resolved.resolved));
+    await assertAsyncDirectoryGuard(guard).catch(() => undefined);
 }
-function isAlreadyExistsError(error) {
-    return hasNodeErrorCode(error, "EEXIST") || /File exists|EEXIST/i.test(String(error));
+async function mkdirPathFallback(resolved) {
+    await mkdirPathComponentsWithGuards({
+        rootReal: resolved.rootReal, targetPath: resolved.resolved,
+        beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
+    });
 }
-function normalizePinnedPathError(error) {
-    if (error instanceof FsSafeError) {
-        return error;
+async function statPathFallback(root, relativePath) {
+    const resolved = await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
+    try {
+        return pathStatFromStats(await fs.lstat(resolved.resolved));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("not-found", "file not found", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        throw error;
     }
-    return new FsSafeError("path-alias", "path is not under root", {
-        cause: error instanceof Error ? error : undefined,
-    });
 }
-async function removePathFallback(resolved) {
-    await fs.rm(resolved.resolved);
+async function listPathFallback(root, relativePath, withFileTypes) {
+    const resolved = await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
+    try {
+        const names = await fs.readdir(resolved.resolved);
+        const sortedNames = names.toSorted();
+        if (!withFileTypes) {
+            return sortedNames;
+        }
+        const entries = [];
+        for (const name of sortedNames) {
+            entries.push({
+                name,
+                ...pathStatFromStats(await fs.lstat(path.join(resolved.resolved, name))),
+            });
+        }
+        return entries;
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("not-found", "directory not found", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        throw error;
+    }
 }
-async function mkdirPathFallback(resolved) {
-    await fs.mkdir(resolved.resolved, { recursive: true });
+async function movePathFallback(root, params) {
+    const source = await resolvePathInRoot(root, params.fromRelative);
+    await resolvePinnedRootPathInRoot(root, {
+        relativePath: params.fromRelative,
+        policy: PATH_ALIAS_POLICIES.strict,
+    });
+    const target = await resolvePathInRoot(root, params.toRelative);
+    await resolvePinnedRootPathInRoot(root, {
+        relativePath: params.toRelative,
+        policy: PATH_ALIAS_POLICIES.unlinkTarget,
+    });
+    try {
+        await assertNoPathAliasEscape({
+            absolutePath: target.resolved,
+            rootPath: target.rootReal,
+            boundaryLabel: "root",
+        });
+    }
+    catch (error) {
+        throw new FsSafeError("path-alias", "path alias escape blocked", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    let sourceStat;
+    try {
+        sourceStat = await fs.lstat(source.resolved);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("not-found", "file not found", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        throw error;
+    }
+    if (sourceStat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "symlink not allowed");
+    }
+    if (sourceStat.isFile() && sourceStat.nlink > 1) {
+        throw new FsSafeError("hardlink", "hardlinked path not allowed");
+    }
+    if (!params.overwrite) {
+        try {
+            await fs.lstat(target.resolved);
+            throw new FsSafeError("already-exists", "destination exists");
+        }
+        catch (error) {
+            if (error instanceof FsSafeError) {
+                throw error;
+            }
+            if (!isNotFoundPathError(error)) {
+                throw error;
+            }
+        }
+    }
+    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved));
+    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved));
+    await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("move", target.resolved);
+    await assertAsyncDirectoryGuard(sourceParentGuard);
+    await assertAsyncDirectoryGuard(targetParentGuard);
+    try {
+        await fs.rename(source.resolved, target.resolved);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("not-found", "file not found", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        if (hasNodeErrorCode(error, "EEXIST")) {
+            throw new FsSafeError("already-exists", "destination exists", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        throw error;
+    }
+    await assertAsyncDirectoryGuard(targetParentGuard).catch(() => undefined);
 }
 async function writeFileFallback(root, params) {
     if (params.overwrite === false) {
-        return await writeMissingFileFallback(root, params);
+        await writeMissingFileFallback(root, params);
+        return;
     }
-    const target = await openWritableFileInSafeRoot(root, {
+    const target = await openWritableFileInRoot(root, {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
+        mode: params.mode,
         truncateExisting: false,
     });
     const destinationPath = target.realPath;
-    const targetMode = target.stat.mode & 0o777;
+    const mode = params.mode ?? (target.stat.mode & 0o777);
     await target.handle.close().catch(() => { });
+    const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
     let tempPath = null;
+    let unregisterTempPath = null;
     try {
         tempPath = buildAtomicWriteTempPath(destinationPath);
+        unregisterTempPath = registerTempPathForExit(tempPath);
         const writtenStat = await writeTempFileForAtomicReplace({
             tempPath,
             data: params.data,
             encoding: params.encoding,
-            mode: targetMode || 0o600,
+            mode: mode || 0o600,
+        });
+        const commitTempPath = tempPath;
+        await withAsyncDirectoryGuards([destinationGuard], async () => {
+            await fs.rename(commitTempPath, destinationPath);
         });
-        await fs.rename(tempPath, destinationPath);
         tempPath = null;
+        unregisterTempPath();
+        unregisterTempPath = null;
         try {
             await verifyAtomicWriteResult({
                 root,
@@ -936,11 +1133,11 @@ async function writeFileFallback(root, params) {
         if (tempPath) {
             await fs.rm(tempPath, { force: true }).catch(() => { });
         }
+        unregisterTempPath?.();
     }
-    return true;
 }
 async function writeMissingFileFallback(root, params) {
-    const { rootReal, resolved } = await resolvePathInSafeRoot(root, params.relativePath);
+    const { rootReal, resolved } = await resolvePathInRoot(root, params.relativePath);
     try {
         await assertNoPathAliasEscape({
             absolutePath: resolved,
@@ -954,36 +1151,48 @@ async function writeMissingFileFallback(root, params) {
     if (params.mkdir !== false) {
         await fs.mkdir(path.dirname(resolved), { recursive: true });
     }
-    let handle = null;
+    const parentGuard = await createAsyncDirectoryGuard(path.dirname(resolved));
     let created = false;
     try {
-        handle = await fs.open(resolved, OPEN_WRITE_CREATE_FLAGS, 0o600);
-        created = true;
-        if (typeof params.data === "string") {
-            await handle.writeFile(params.data, params.encoding ?? "utf8");
-        }
-        else {
-            await handle.writeFile(params.data);
-        }
-        const writtenStat = await handle.stat();
+        const { handle, writtenStat } = await withAsyncDirectoryGuards([parentGuard], async () => {
+            const handle = await fs.open(resolved, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600);
+            created = true;
+            try {
+                if (typeof params.data === "string") {
+                    await handle.writeFile(params.data, params.encoding ?? "utf8");
+                }
+                else {
+                    await handle.writeFile(params.data);
+                }
+                return { handle, writtenStat: await handle.stat() };
+            }
+            catch (error) {
+                await handle.close().catch(() => undefined);
+                throw error;
+            }
+        }, {
+            onPostGuardFailure: async ({ handle }) => {
+                created = false; // Parent is untrusted now; skip outer path cleanup by name.
+                await handle.close().catch(() => undefined);
+            },
+        });
         await handle.close();
-        handle = null;
         await verifyAtomicWriteResult({
             root,
             targetPath: resolved,
             expectedIdentity: writtenStat,
         });
         created = false;
-        return true;
     }
     catch (err) {
         if (hasNodeErrorCode(err, "EEXIST")) {
-            return false;
+            throw new FsSafeError("already-exists", "file already exists", {
+                cause: err instanceof Error ? err : undefined,
+            });
         }
         throw err;
     }
     finally {
-        await handle?.close().catch(() => undefined);
         if (created) {
             await fs.rm(resolved, { force: true }).catch(() => undefined);
         }
@@ -995,20 +1204,24 @@ async function copyFileFallback(root, params, source) {
     let targetClosedByUs = false;
     let tempHandle = null;
     let tempPath = null;
+    let unregisterTempPath = null;
     let tempClosedByStream = false;
     try {
-        target = await openWritableFileInSafeRoot(root, {
+        target = await openWritableFileInRoot(root, {
             relativePath: params.relativePath,
             mkdir: params.mkdir,
+            mode: params.mode,
             truncateExisting: false,
         });
         const destinationPath = target.realPath;
-        const targetMode = target.stat.mode & 0o777;
+        const mode = params.mode ?? (target.stat.mode & 0o777);
         await target.handle.close().catch(() => { });
         targetClosedByUs = true;
+        const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
         tempPath = buildAtomicWriteTempPath(destinationPath);
-        tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, targetMode || 0o600);
-        const sourceStream = source.handle.createReadStream();
+        unregisterTempPath = registerTempPathForExit(tempPath);
+        tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, mode || 0o600);
+        const sourceStream = createBoundedReadStream(source, params.maxBytes);
         const targetStream = tempHandle.createWriteStream();
         sourceStream.once("close", () => {
             sourceClosedByStream = true;
@@ -1023,8 +1236,13 @@ async function copyFileFallback(root, params, source) {
             tempClosedByStream = true;
         }
         tempHandle = null;
-        await fs.rename(tempPath, destinationPath);
+        const commitTempPath = tempPath;
+        await withAsyncDirectoryGuards([destinationGuard], async () => {
+            await fs.rename(commitTempPath, destinationPath);
+        });
         tempPath = null;
+        unregisterTempPath();
+        unregisterTempPath = null;
         try {
             await verifyAtomicWriteResult({
                 root,
@@ -1044,15 +1262,16 @@ async function copyFileFallback(root, params, source) {
         throw err;
     }
     finally {
-        if (tempPath) {
-            await fs.rm(tempPath, { force: true }).catch(() => { });
-        }
         if (!sourceClosedByStream) {
             await source.handle.close().catch(() => { });
         }
         if (tempHandle && !tempClosedByStream) {
             await tempHandle.close().catch(() => { });
         }
+        if (tempPath) {
+            await fs.rm(tempPath, { force: true }).catch(() => { });
+        }
+        unregisterTempPath?.();
         if (target && !targetClosedByUs) {
             await target.handle.close().catch(() => { });
         }