@openclaw/fs-safe 0.5.1 → 0.5.3

package/dist/root-impl.js

@@ -11,14 +11,14 @@ import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { assertMutationNotDenied, mergeDenyMutationPolicies, } from "./deny-mutations.js";
 import { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy, } from "./pinned-write.js";
+import { getNativeBinding } from "./native.js";
 import { validatePinnedOperationPayload } from "./pinned-operation.js";
 import { assertNoPathAliasEscape, PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
 import { readOpenedFileSafely } from "./read-opened-file.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 { assertRootIdentityCurrent, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, } from "./root-context.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, normalizeRemoveGuardError, normalizeRemovePathError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { walkRoot } from "./root-walk.js";
@@ -31,11 +31,11 @@ function logWarn(message) {
     }
 }
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
-const NONBLOCK_OPEN_FLAG = "O_NONBLOCK" in fsConstants ? fsConstants.O_NONBLOCK : 0;
-const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-const OPEN_READ_NONBLOCK_FLAGS = OPEN_READ_FLAGS | NONBLOCK_OPEN_FLAG;
-const OPEN_READ_FOLLOW_FLAGS = fsConstants.O_RDONLY;
-const OPEN_READ_FOLLOW_NONBLOCK_FLAGS = OPEN_READ_FOLLOW_FLAGS | NONBLOCK_OPEN_FLAG;
+const NONBLOCK_OPEN_FLAG = process.platform !== "win32" && "O_NONBLOCK" in fsConstants ? fsConstants.O_NONBLOCK : 0;
+const OPEN_READ_FLAGS = fsConstants.O_RDONLY |
+    (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0) |
+    NONBLOCK_OPEN_FLAG;
+const OPEN_READ_FOLLOW_FLAGS = fsConstants.O_RDONLY | NONBLOCK_OPEN_FLAG;
 const OPEN_WRITE_EXISTING_FLAGS = fsConstants.O_WRONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |
@@ -48,6 +48,21 @@ const OPEN_APPEND_CREATE_FLAGS = fsConstants.O_RDWR |
     fsConstants.O_EXCL |
     (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 export const DEFAULT_ROOT_MAX_BYTES = 16 * 1024 * 1024;
+function pathStatFromStats(stat) {
+    return {
+        dev: Number(stat.dev),
+        gid: Number(stat.gid),
+        ino: Number(stat.ino),
+        isDirectory: stat.isDirectory(),
+        isFile: stat.isFile(),
+        isSymbolicLink: stat.isSymbolicLink(),
+        mode: stat.mode,
+        mtimeMs: stat.mtimeMs,
+        nlink: stat.nlink,
+        size: stat.size,
+        uid: stat.uid,
+    };
+}
 function openResult(params) {
     return {
         handle: params.handle,
@@ -60,14 +75,17 @@ function openResult(params) {
 async function openVerifiedLocalFile(filePath, options) {
     assertNoUnsafeDeviceReadPath(filePath);
     const fsSafeTestHooks = getFsSafeTestHooks();
+    let preOpenStat;
     // Reject directories before opening so we never surface EISDIR to callers (e.g. tool
     // results that get sent to messaging channels). See openclaw/openclaw#31186.
     try {
-        const preStat = await fs.lstat(filePath);
-        if (preStat.isDirectory()) {
+        preOpenStat = await fs.lstat(filePath);
+        if (preOpenStat.isSymbolicLink() && options?.symlinks !== "follow-within-root") {
+            throw new FsSafeError("symlink", "symlink not allowed");
+        }
+        if (!preOpenStat.isFile() && !preOpenStat.isSymbolicLink()) {
             throw new FsSafeError("not-file", "not a file");
         }
-        await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
     }
     catch (err) {
         if (err instanceof FsSafeError) {
@@ -75,15 +93,14 @@ async function openVerifiedLocalFile(filePath, options) {
         }
         // ENOENT and other lstat errors: fall through and let fs.open handle.
     }
+    if (preOpenStat) {
+        await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
+    }
     let handle;
     try {
         const openFlags = options?.symlinks === "follow-within-root"
-            ? options?.nonBlockingRead
-                ? OPEN_READ_FOLLOW_NONBLOCK_FLAGS
-                : OPEN_READ_FOLLOW_FLAGS
-            : options?.nonBlockingRead
-                ? OPEN_READ_NONBLOCK_FLAGS
-                : OPEN_READ_FLAGS;
+            ? OPEN_READ_FOLLOW_FLAGS
+            : OPEN_READ_FLAGS;
         await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
         handle = await fs.open(filePath, openFlags);
         try {
@@ -96,7 +113,7 @@ async function openVerifiedLocalFile(filePath, options) {
     }
     catch (err) {
         if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "file not found");
+            throw fileNotFoundError();
         }
         if (isSymlinkOpenError(err)) {
             throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
@@ -112,8 +129,13 @@ async function openVerifiedLocalFile(filePath, options) {
         if (!stat.isFile()) {
             throw new FsSafeError("not-file", "not a file");
         }
+        if (preOpenStat &&
+            !preOpenStat.isSymbolicLink() &&
+            !sameFileIdentity(stat, preOpenStat)) {
+            throw new FsSafeError("path-mismatch", "path changed before open");
+        }
         if (options?.hardlinks === "reject" && stat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
+            throw hardlinkedPathNotAllowedError();
         }
         if (options?.symlinks === "follow-within-root") {
             const pathStat = await fs.stat(filePath);
@@ -133,7 +155,7 @@ async function openVerifiedLocalFile(filePath, options) {
         const realPath = await resolveOpenedFileRealPathForHandle(handle, filePath);
         const realStat = await fs.stat(realPath);
         if (options?.hardlinks === "reject" && realStat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
+            throw hardlinkedPathNotAllowedError();
         }
         if (!sameFileIdentity(stat, realStat)) {
             throw new FsSafeError("path-mismatch", "path mismatch");
@@ -146,17 +168,19 @@ async function openVerifiedLocalFile(filePath, options) {
             throw err;
         }
         if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "file not found");
+            throw fileNotFoundError();
         }
         throw err;
     }
 }
 class RootHandle {
+    rootIdentity;
     rootDir;
     rootReal;
     rootWithSep;
     defaults;
     constructor(context, defaults = {}) {
+        this.rootIdentity = context.rootIdentity;
         this.rootDir = context.rootDir;
         this.rootReal = context.rootReal;
         this.rootWithSep = context.rootWithSep;
@@ -165,11 +189,19 @@ class RootHandle {
     get context() {
         return {
             rootDir: this.rootDir,
+            rootIdentity: this.rootIdentity,
             rootReal: this.rootReal,
             rootWithSep: this.rootWithSep,
         };
     }
+    mutationOptions(options) {
+        return {
+            ...options,
+            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+        };
+    }
     async resolve(relativePath) {
+        assertValidRootDestinationPath(relativePath);
         return (await resolvePathInRoot(this.context, relativePath, { allowFinalSymlink: true })).resolved;
     }
     async open(relativePath, options = {}) {
@@ -209,67 +241,67 @@ class RootHandle {
         };
     }
     async openWritable(relativePath, options = {}) {
+        assertValidRootDestinationPath(relativePath);
         const writeMode = options.writeMode ?? "replace";
         return await openWritableFileInRoot(this.context, {
             relativePath,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
-            ...options,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
             append: writeMode === "append",
             truncateExisting: writeMode === "replace",
         });
     }
     async append(relativePath, data, options = {}) {
+        assertValidRootDestinationPath(relativePath);
         await appendFileInRoot(this.context, {
             relativePath,
             data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
-            ...options,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
         });
     }
     async remove(relativePath, options = {}) {
         assertValidRootRelativePath(relativePath);
         await removePathInRoot(this.context, {
             relativePath,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
         });
     }
     async mkdir(relativePath, options = {}) {
-        assertValidRootRelativePath(relativePath);
+        assertValidRootDestinationPath(relativePath);
         await mkdirPathInRoot(this.context, {
             relativePath,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
         });
     }
     async ensureRoot(options = {}) {
         await mkdirPathInRoot(this.context, {
             relativePath: "",
             allowRoot: true,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
         });
     }
     async write(relativePath, data, options = {}) {
+        assertValidRootDestinationPath(relativePath);
         await writeFileInRoot(this.context, {
             relativePath,
             data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             renameIdentity: this.defaults.renameIdentity,
-            ...options,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
         });
     }
     async create(relativePath, data, options = {}) {
+        assertValidRootDestinationPath(relativePath);
         await writeFileInRoot(this.context, {
             relativePath,
             data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
-            ...options,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
             overwrite: false,
         });
     }
@@ -284,15 +316,14 @@ class RootHandle {
         await this.create(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
     }
     async copyIn(relativePath, sourcePath, options = {}) {
-        assertValidRootRelativePath(relativePath);
+        assertValidRootDestinationPath(relativePath);
         await copyFileInRoot(this.context, {
             sourcePath,
             relativePath,
             maxBytes: this.defaults.maxBytes,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
-            ...options,
-            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
+            ...this.mutationOptions(options),
         });
     }
     async exists(relativePath) {
@@ -319,9 +350,9 @@ class RootHandle {
     }
     async move(fromRelative, toRelative, options = {}) {
         assertValidRootRelativePath(fromRelative);
-        assertValidRootRelativePath(toRelative);
+        assertValidRootDestinationPath(toRelative);
         validatePinnedOperationPayload({ from: fromRelative, to: toRelative });
-        const denyMutations = mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations);
+        const { denyMutations } = this.mutationOptions(options);
         await assertMoveMutationAllowed(this.context, {
             fromRelative,
             toRelative,
@@ -353,6 +384,8 @@ export async function root(rootDir, defaults = {}) {
 async function openFileInRoot(root, params) {
     const { rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath, {
         allowFinalSymlink: true,
+        rejectUnsafeDeviceReads: true,
+        rejectSymlinks: params.symlinks !== "follow-within-root",
     });
     let opened;
     try {
@@ -369,11 +402,11 @@ async function openFileInRoot(root, params) {
     }
     if (params.hardlinks !== "allow" && opened.stat.nlink > 1) {
         await opened.handle.close().catch(() => { });
-        throw new FsSafeError("hardlink", "hardlinked path not allowed");
+        throw hardlinkedPathNotAllowedError();
     }
     if (!isPathInside(rootWithSep, opened.realPath)) {
         await opened.handle.close().catch(() => { });
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
+        throw outsideWorkspaceError();
     }
     return opened;
 }
@@ -455,33 +488,47 @@ async function verifyAtomicWriteResult(params) {
             throw new FsSafeError("path-mismatch", "path changed during write");
         }
         if (!isPathInside(params.root.rootWithSep, opened.realPath)) {
-            throw new FsSafeError("outside-workspace", "file is outside workspace root");
+            throw outsideWorkspaceError();
         }
     }
     finally {
         await opened.handle.close().catch(() => { });
     }
 }
-async function openWritableFileInRoot(root, params) {
-    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath, { aliasErrorCode: "path-alias" });
-    await assertMutationNotDenied(resolved, params.denyMutations);
-    try {
-        await assertNoPathAliasEscape({
-            absolutePath: resolved,
-            rootPath: rootReal,
-            boundaryLabel: "root",
-        });
-    }
-    catch (err) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
+async function resolveGuardedWritePathInRoot(root, params) {
+    const resolvedPath = await resolvePathInRoot(root, params.relativePath, {
+        aliasErrorCode: "path-alias",
+        allowFinalSymlink: params.allowFinalSymlink,
+    });
+    await assertMutationNotDenied(resolvedPath.resolved, params.denyMutations, params.protectDeniedAncestors ? { protectAncestors: true } : undefined);
+    if (await (params.shouldAssertNoPathAlias?.(resolvedPath) ?? true)) {
+        try {
+            await assertNoPathAliasEscape({
+                absolutePath: resolvedPath.resolved,
+                rootPath: resolvedPath.rootReal,
+                boundaryLabel: "root",
+            });
+        }
+        catch (error) {
+            throw new FsSafeError("path-alias", "path alias escape blocked", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
     }
+    return resolvedPath;
+}
+async function openWritableFileInRoot(root, params) {
+    const { rootReal, rootWithSep, resolved } = await resolveGuardedWritePathInRoot(root, {
+        relativePath: params.relativePath,
+        denyMutations: params.denyMutations,
+    });
     let ioPath = params.mkdir === false
         ? resolved
         : await prepareRootWriteTarget(rootReal, resolved);
     try {
         const resolvedRealPath = await fs.realpath(ioPath);
         if (!isPathInside(rootWithSep, resolvedRealPath)) {
-            throw new FsSafeError("outside-workspace", "file is outside workspace root");
+            throw outsideWorkspaceError();
         }
         ioPath = resolvedRealPath;
     }
@@ -512,7 +559,7 @@ async function openWritableFileInRoot(root, params) {
     }
     catch (err) {
         if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "file not found");
+            throw fileNotFoundError();
         }
         if (isSymlinkOpenError(err)) {
             throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
@@ -523,13 +570,17 @@ async function openWritableFileInRoot(root, params) {
         throw err;
     }
     let realPathForCleanup = null;
+    let createdIdentity = null;
     try {
         const stat = await handle.stat();
+        if (createdForWrite) {
+            createdIdentity = stat;
+        }
         if (!stat.isFile()) {
-            throw new FsSafeError("invalid-path", "path is not a regular file under root");
+            throw new FsSafeError("not-file", "path is not a regular file under root");
         }
         if (stat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
+            throw hardlinkedPathNotAllowedError();
         }
         try {
             const lstat = await fs.lstat(ioPath);
@@ -552,10 +603,10 @@ async function openWritableFileInRoot(root, params) {
             throw new FsSafeError("path-mismatch", "path mismatch");
         }
         if (realStat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
+            throw hardlinkedPathNotAllowedError();
         }
         if (!isPathInside(rootWithSep, realPath)) {
-            throw new FsSafeError("outside-workspace", "file is outside workspace root");
+            throw outsideWorkspaceError();
         }
         // Truncate only after boundary and identity checks complete. This avoids
         // irreversible side effects if a symlink target changes before validation.
@@ -575,8 +626,8 @@ async function openWritableFileInRoot(root, params) {
         const cleanupCreatedPath = createdForWrite && err instanceof FsSafeError;
         const cleanupPath = realPathForCleanup ?? ioPath;
         await handle.close().catch(() => { });
-        if (cleanupCreatedPath) {
-            await fs.rm(cleanupPath, { force: true }).catch(() => { });
+        if (cleanupCreatedPath && createdIdentity) {
+            await removePathIfIdentityUnchanged(cleanupPath, createdIdentity).catch(() => { });
         }
         throw err;
     }
@@ -621,7 +672,11 @@ async function appendFileInRoot(root, params) {
 }
 async function removePathInRoot(root, params) {
     validatePinnedOperationPayload({ relativePath: params.relativePath });
-    const resolved = await resolvePinnedRemovePathInRoot(root, params.relativePath, params.denyMutations);
+    const resolved = await resolvePinnedPathInRoot(root, {
+        relativePath: params.relativePath,
+        denyMutations: params.denyMutations,
+        remove: true,
+    });
     try {
         await removePathFallback(resolved);
     }
@@ -640,15 +695,16 @@ async function mkdirPathInRoot(root, params) {
     }
 }
 async function writeFileInRoot(root, params) {
-    if (process.platform === "win32") {
-        await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
+    await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
+        if (process.platform === "win32" &&
+            (params.renameIdentity === "verify-content-with-lock" || !getNativeBinding())) {
             await writeFileFallback(root, params);
+            return;
+        }
+        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
+        await serializePathWrite(pinned.targetPath, async () => {
+            await commitPinnedWriteInRoot(root, pinned, params);
         });
-        return;
-    }
-    const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
-    await serializePathWrite(pinned.targetPath, async () => {
-        await commitPinnedWriteInRoot(root, pinned, params);
     });
 }
 async function commitPinnedWriteInRoot(root, pinned, params) {
@@ -664,6 +720,7 @@ async function commitPinnedWriteInRoot(root, pinned, params) {
             mode: params.mode ?? pinned.mode,
             overwrite: params.overwrite,
             input: { kind: "buffer", data: params.data, encoding: params.encoding },
+            rootIdentity: root.rootIdentity,
         });
     }
     catch (error) {
@@ -701,26 +758,35 @@ async function copyFileInRoot(root, params) {
         throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${source.stat.size})`);
     }
     try {
-        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
-        await serializePathWrite(pinned.targetPath, async () => {
-            await assertCopySourceCurrent(source);
-            const identity = await runPinnedWriteHelper({
-                rootPath: pinned.rootReal,
-                relativeParentPath: pinned.relativeParentPath,
-                basename: pinned.basename,
-                mkdir: params.mkdir !== false,
-                mode: pinned.mode,
-                overwrite: true,
-                maxBytes: params.maxBytes,
-                input: { kind: "stream", stream: source.handle.createReadStream() },
+        await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
+            const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
+            await serializePathWrite(pinned.targetPath, async () => {
+                await assertCopySourceCurrent(source);
+                let identity;
+                try {
+                    identity = await runPinnedWriteHelper({
+                        rootPath: pinned.rootReal,
+                        relativeParentPath: pinned.relativeParentPath,
+                        basename: pinned.basename,
+                        mkdir: params.mkdir !== false,
+                        mode: pinned.mode,
+                        overwrite: true,
+                        maxBytes: params.maxBytes,
+                        input: { kind: "stream", stream: source.handle.createReadStream() },
+                        rootIdentity: root.rootIdentity,
+                    });
+                }
+                catch (error) {
+                    throw normalizePinnedWriteError(error);
+                }
+                try {
+                    await assertCopySourcePathCurrent(source);
+                }
+                catch (error) {
+                    await removePathIfIdentityUnchanged(pinned.targetPath, identity).catch(() => undefined);
+                    throw error;
+                }
             });
-            try {
-                await assertCopySourcePathCurrent(source);
-            }
-            catch (error) {
-                await removeCopyTargetIfUnchanged(pinned.targetPath, identity).catch(() => undefined);
-                throw error;
-            }
         });
     }
     finally {
@@ -740,7 +806,7 @@ async function assertCopySourcePathCurrent(source) {
         throw new FsSafeError("path-mismatch", "copy source path changed");
     }
 }
-async function removeCopyTargetIfUnchanged(targetPath, identity) {
+async function removePathIfIdentityUnchanged(targetPath, identity) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
     const current = await fs.lstat(targetPath);
     if (current.isSymbolicLink() || !sameFileIdentity(current, identity)) {
@@ -751,25 +817,15 @@ async function removeCopyTargetIfUnchanged(targetPath, identity) {
     });
 }
 async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations) {
-    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, relativePath, {
-        aliasErrorCode: "path-alias",
+    const { rootReal, rootWithSep, resolved } = await resolveGuardedWritePathInRoot(root, {
+        relativePath,
+        denyMutations,
     });
-    await assertMutationNotDenied(resolved, denyMutations);
-    try {
-        await assertNoPathAliasEscape({
-            absolutePath: resolved,
-            rootPath: rootReal,
-            boundaryLabel: "root",
-        });
-    }
-    catch (err) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
-    }
     // resolvePathInRoot already enforces isPathInside, so any actual escape
     // is rejected upstream.
     const relativeResolved = path.relative(rootReal, resolved);
     if (path.isAbsolute(relativeResolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
+        throw outsideWorkspaceError();
     }
     const relativePosix = relativeResolved
         ? relativeResolved.split(path.sep).join(path.posix.sep)
@@ -784,11 +840,12 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode,
             relativePath,
             hardlinks: "reject",
             nonBlockingRead: true,
+            symlinks: "follow-within-root",
         });
         try {
             mode = requestedMode ?? (opened.stat.mode & 0o777);
             if (!isPathInside(rootWithSep, opened.realPath)) {
-                throw new FsSafeError("outside-workspace", "file is outside workspace root");
+                throw outsideWorkspaceError();
             }
         }
         finally {
@@ -812,17 +869,9 @@ async function resolvePinnedPathInRoot(root, params) {
     return await resolvePinnedOperationPathInRoot(root, {
         allowRoot: params.allowRoot,
         denyMutations: params.denyMutations,
-        protectDenyMutationAncestors: false,
+        protectDenyMutationAncestors: params.remove === true,
         relativePath: params.relativePath,
-        policy: PATH_ALIAS_POLICIES.strict,
-    });
-}
-async function resolvePinnedRemovePathInRoot(root, relativePath, denyMutations) {
-    return await resolvePinnedOperationPathInRoot(root, {
-        denyMutations,
-        protectDenyMutationAncestors: true,
-        relativePath,
-        policy: PATH_ALIAS_POLICIES.unlinkTarget,
+        policy: params.remove ? PATH_ALIAS_POLICIES.unlinkTarget : PATH_ALIAS_POLICIES.strict,
     });
 }
 async function resolvePinnedOperationPathInRoot(root, params) {
@@ -840,11 +889,11 @@ async function resolvePinnedOperationPathInRoot(root, params) {
         relativeResolved === "." ||
         firstSegment === ".." ||
         path.isAbsolute(relativeResolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
+        throw outsideWorkspaceError();
     }
     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");
+        throw outsideWorkspaceError();
     }
     await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations, {
         protectAncestors: params.protectDenyMutationAncestors,
@@ -852,6 +901,7 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
 }
 async function resolvePinnedRootPathInRoot(root, params) {
+    await assertRootIdentityCurrent(root);
     const rootReal = root.rootReal;
     let resolved;
     try {
@@ -876,11 +926,25 @@ async function resolvePinnedRootPathInRoot(root, params) {
         canonicalPath: resolved.canonicalPath,
     };
 }
+async function prepareRemoveGuard(targetPath) {
+    try {
+        const guard = await createAsyncDirectoryGuard(path.dirname(targetPath));
+        await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("remove", targetPath);
+        await assertAsyncDirectoryGuard(guard);
+        return guard;
+    }
+    catch (error) {
+        throw normalizeRemoveGuardError(error);
+    }
+}
 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));
+    const guard = await prepareRemoveGuard(resolved.resolved);
+    try {
+        await ((await fs.lstat(resolved.resolved)).isDirectory() ? fs.rmdir(resolved.resolved) : fs.rm(resolved.resolved));
+    }
+    catch (error) {
+        throw normalizeRemovePathError(error);
+    }
     await assertAsyncDirectoryGuard(guard).catch(() => undefined);
 }
 async function mkdirPathFallback(resolved) {
@@ -892,13 +956,13 @@ async function mkdirPathFallback(resolved) {
 async function statPathFallback(root, relativePath) {
     const resolved = await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
     try {
-        return pathStatFromStats(await fs.lstat(resolved.resolved));
+        const stat = pathStatFromStats(await fs.lstat(resolved.resolved));
+        await assertRootIdentityCurrent(root);
+        return stat;
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
-            throw new FsSafeError("not-found", "file not found", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw fileNotFoundError(error instanceof Error ? error : undefined);
         }
         throw error;
     }
@@ -909,6 +973,7 @@ async function listPathFallback(root, relativePath, withFileTypes) {
         const names = await fs.readdir(resolved.resolved);
         const sortedNames = names.toSorted();
         if (!withFileTypes) {
+            await assertRootIdentityCurrent(root);
             return sortedNames;
         }
         const entries = [];
@@ -918,6 +983,7 @@ async function listPathFallback(root, relativePath, withFileTypes) {
                 ...pathStatFromStats(await fs.lstat(path.join(resolved.resolved, name))),
             });
         }
+        await assertRootIdentityCurrent(root);
         return entries;
     }
     catch (error) {
@@ -930,6 +996,8 @@ async function listPathFallback(root, relativePath, withFileTypes) {
     }
 }
 async function assertMoveMutationAllowed(root, params) {
+    // Keep this preflight separate from the pinned resolutions in movePathFallback:
+    // mutation denials must take precedence over source alias or identity failures.
     const source = await resolvePathInRoot(root, params.fromRelative, {
         aliasErrorCode: "path-alias",
         allowFinalSymlink: true,
@@ -951,40 +1019,29 @@ async function movePathFallback(root, params) {
         relativePath: params.fromRelative,
         policy: PATH_ALIAS_POLICIES.strict,
     });
-    const target = await resolvePathInRoot(root, params.toRelative, {
-        aliasErrorCode: "path-alias",
-        allowFinalSymlink: true,
-    });
-    await assertMutationNotDenied(target.resolved, params.denyMutations, { protectAncestors: true });
-    await resolvePinnedRootPathInRoot(root, {
+    const target = await resolveGuardedWritePathInRoot(root, {
         relativePath: params.toRelative,
-        policy: PATH_ALIAS_POLICIES.unlinkTarget,
-    });
-    const targetStat = await fs.lstat(target.resolved).catch(() => undefined);
-    const replacesFinalSymlink = process.platform !== "win32" && params.overwrite && targetStat?.isSymbolicLink() === true;
-    if (!replacesFinalSymlink) {
-        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,
+        denyMutations: params.denyMutations,
+        allowFinalSymlink: true,
+        protectDeniedAncestors: true,
+        shouldAssertNoPathAlias: async (resolvedTarget) => {
+            await resolvePinnedRootPathInRoot(root, {
+                relativePath: params.toRelative,
+                policy: PATH_ALIAS_POLICIES.unlinkTarget,
             });
-        }
-    }
+            const targetStat = await fs.lstat(resolvedTarget.resolved).catch(() => undefined);
+            return !(process.platform !== "win32" &&
+                params.overwrite &&
+                targetStat?.isSymbolicLink() === true);
+        },
+    });
     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 fileNotFoundError(error instanceof Error ? error : undefined);
         }
         throw error;
     }
@@ -992,7 +1049,7 @@ async function movePathFallback(root, params) {
         throw new FsSafeError("symlink", "symlink not allowed");
     }
     if (sourceStat.isFile() && sourceStat.nlink > 1) {
-        throw new FsSafeError("hardlink", "hardlinked path not allowed");
+        throw hardlinkedPathNotAllowedError();
     }
     if (!params.overwrite && sourceStat.isDirectory()) {
         throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
@@ -1021,9 +1078,7 @@ async function movePathFallback(root, params) {
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
-            throw new FsSafeError("not-found", "file not found", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw fileNotFoundError(error instanceof Error ? error : undefined);
         }
         if (hasNodeErrorCode(error, "EEXIST")) {
             throw new FsSafeError("already-exists", "destination exists", {
@@ -1089,30 +1144,22 @@ async function writeFileFallback(root, params) {
     }
 }
 async function writeMissingFileFallback(root, params) {
-    const { rootReal, resolved } = await resolvePathInRoot(root, params.relativePath, {
-        aliasErrorCode: "path-alias",
+    const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, {
+        relativePath: params.relativePath,
+        denyMutations: params.denyMutations,
     });
-    await assertMutationNotDenied(resolved, params.denyMutations);
-    try {
-        await assertNoPathAliasEscape({
-            absolutePath: resolved,
-            rootPath: rootReal,
-            boundaryLabel: "root",
-        });
-    }
-    catch (err) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
-    }
     const targetPath = params.mkdir === false
         ? resolved
         : await prepareRootWriteTarget(rootReal, resolved);
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
     let created = false;
+    let createdIdentity;
     try {
         const { handle, writtenStat } = await withAsyncDirectoryGuards([parentGuard], async () => {
             const handle = await fs.open(targetPath, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600);
             created = true;
             try {
+                createdIdentity = await handle.stat();
                 if (typeof params.data === "string") {
                     await handle.writeFile(params.data, params.encoding ?? "utf8");
                 }
@@ -1148,8 +1195,8 @@ async function writeMissingFileFallback(root, params) {
         throw err;
     }
     finally {
-        if (created) {
-            await fs.rm(targetPath, { force: true }).catch(() => undefined);
+        if (created && createdIdentity) {
+            await removePathIfIdentityUnchanged(targetPath, createdIdentity).catch(() => undefined);
         }
     }
 }