@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/root-impl.js

@@ -51,11 +51,13 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { randomUUID } from "node:crypto";
+import { registerRootHandleContext } from "./root-handle-context.js";
 import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertCopySourceCurrent, resolveFileCopyCloneMode } from "./copy-file-input.js";
+import { assertPrivateFileCreationAvailable, resolveCreationPermissions } from "./creation-boundary.js";
 import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
@@ -67,23 +69,25 @@ import { openedPathResolutionError, recordExclusiveCreateFailure, recordOpenedFi
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy } from "./pinned-write.js";
 import { preparePinnedWriteMutationAdmission, snapshotPinnedMutationPolicy } from "./pinned-mutation-admission.js";
 import { getNativeBinding } from "./native.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
 import { readOpenedFileSafely } from "./read-opened-file.js";
-import { cleanupPinnedFilePath, removePathIfIdentityUnchanged } from "./replace-file-temp-owner.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { removePathIfIdentityUnchanged } from "./replace-file-temp-owner.js";
 import { realpathSync } from "./realpath.js";
 import { mkdirPathFallback, prepareRootWriteTarget, tryMkdirAtExactParent } from "./root-directory-creation.js";
 import { isNonRegularWriteOpenError, resolveNonblockingWriteFlag } from "./write-open-flags.js";
-import { resolveRootPath, resolveRootPathForRemoval } from "./root-path.js";
+import { resolveRootPath, resolveRootPathSync, resolveRootPathForRemoval } from "./root-path.js";
 import { RemovalPathReceipts } from "./root-remove-receipt.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-list.js";
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
-import { assertRootIdentityCurrent, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
-import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
+import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { walkRoot } from "./root-walk.js";
@@ -91,19 +95,21 @@ import { registerTempPathForExit } from "./temp-cleanup.js";
 import { removePathInRootFallback, validateRemoveOptions } from "./root-remove.js";
 import { serializePathWrite } from "./write-queue.js";
 import { verifyAtomicWriteResult } from "./root-write-verification.js";
-import { assertRootWritePathSelectionSync, assertRootWriteSelectionSync, createRootWriteSelectionForFd, prepareGuardedRootWritePathSelection, resolveGuardedWritePathInRoot, resolveGuardedWriteTargetInRoot, resolvePinnedWriteTargetInRoot, refreshRetainedRootWriteAdmission, refreshRootWritePathSelection, retainRootWriteSelection, takeRootWriteSelection, } from "./root-write-admission.js";
+import { assertRootWritePathSelectionSync, assertRootWriteSelectionSync, createRootWriteSelectionForFd, prepareGuardedRootWritePathSelection, resolveGuardedWritePathInRoot, resolveGuardedWriteTargetInRoot, resolvePinnedWriteTargetInRoot, refreshRetainedRootWriteAdmission, refreshRootWritePathSelection, } from "./root-write-admission.js";
 import { prepareSharedRootWriteTarget } from "./root-write-complete-parent.js";
 import { finishRootFallbackWrite } from "./root-write-publication.js";
-import { assertRootFallbackWritePath, withRootFallbackCompatibilityLock } from "./root-write-compatibility.js";
+import { withRootFallbackCompatibilityLock } from "./root-write-compatibility.js";
+import { assertRootFallbackWritePath } from "./root-write-lock-binding.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { movePathNoReplaceNative } from "./root-move-noreplace.js";
+import { admitMoveSourceStat, movePathNoReplaceNative } from "./root-move-noreplace.js";
 import { admitRootReadHandle, inspectOpenedPathIdentitySync } from "./root-read-admission.js";
-import { createCopyPublicationObserver, onCopyPublication } from "./copy-publication.js";
+import { createCopyPublicationObserver, onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
 import { writeAllToFile } from "./write-file-handle.js";
 import { createInputOptions, rethrowCreateInputError, rootWriteInput } from "./root-create-input.js";
 import { assertFinalSymlinkRejected, mutationSymlinkResolution, readSymlinkResolution } from "./root-symlink-policy.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
 import { resolvePinnedObservedPathInRoot } from "./root-observed-path.js";
+import { registerFileLockSyncRootAdapter } from "./file-lock-sync-root.js";
 import { mergeReadOptions, readDefaults, } from "./root-options.js";
 import { composeMutationAssertions, MutationAuthorityError, rethrowMutationAuthorityError } from "./mutation-authority.js";
 export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
@@ -182,28 +188,19 @@ async function openVerifiedLocalFile(filePath, options) {
     }
 }
 export class RootHandle {
-    rootGuard;
-    rootIdentity;
+    context;
     rootDir;
     rootReal;
     rootWithSep;
     defaults;
     constructor(context, defaults = {}) {
-        this.rootGuard = context.rootGuard;
-        this.rootIdentity = context.rootIdentity;
+        this.context = context;
         this.rootDir = context.rootDir;
         this.rootReal = context.rootReal;
         this.rootWithSep = context.rootWithSep;
         this.defaults = defaults;
-    }
-    get context() {
-        return {
-            rootDir: this.rootDir,
-            rootGuard: this.rootGuard,
-            rootIdentity: this.rootIdentity,
-            rootReal: this.rootReal,
-            rootWithSep: this.rootWithSep,
-        };
+        registerFileLockSyncRootAdapter(this, context, defaults);
+        registerRootHandleContext(this, context);
     }
     mutationOptions(options) {
         return {
@@ -219,9 +216,9 @@ export class RootHandle {
     }
     async open(relativePath, options = {}) {
         return await openFileInRoot(this.context, {
-            relativePath,
             ...readDefaults(this.defaults),
             ...options,
+            relativePath,
         });
     }
     async read(relativePath, options = {}) {
@@ -241,9 +238,11 @@ export class RootHandle {
         return JSON.parse(await this.readText(relativePath, options));
     }
     async readAbsolute(filePath, options = {}) {
-        return await readPathInRoot(this.context, {
-            filePath,
-            ...mergeReadOptions(this.defaults, options),
+        const context = this.context;
+        const readOptions = mergeReadOptions(this.defaults, options);
+        return await readFileInRoot(context, {
+            relativePath: rootRelativeReadPath(context, filePath),
+            ...readOptions,
         });
     }
     reader(options = {}) {
@@ -255,10 +254,11 @@ export class RootHandle {
         assertValidRootDestinationPath(relativePath);
         const writeMode = options.writeMode ?? "replace";
         const target = await openWritableFileInRoot(this.context, {
-            relativePath,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(options),
+            relativePath,
+            expectedWritePath: undefined,
             append: writeMode === "append",
             truncateExisting: writeMode === "replace",
         }).catch(rethrowMutationAuthorityError);
@@ -267,11 +267,11 @@ export class RootHandle {
     async append(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await appendFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(options),
+            relativePath,
+            data,
             durable: options.durable ?? this.defaults.durable ?? true,
         }).catch(rethrowMutationAuthorityError);
     }
@@ -280,45 +280,51 @@ export class RootHandle {
         validateRemoveOptions(options);
         options.signal?.throwIfAborted();
         await removePathInRoot(this.context, {
-            relativePath,
             ...this.mutationOptions(options),
+            relativePath,
         }).catch(rethrowMutationAuthorityError);
     }
     async mkdir(relativePath, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await mkdirPathInRoot(this.context, {
-            relativePath,
             ...this.mutationOptions(options),
+            relativePath,
+            allowRoot: false,
         }).catch(rethrowMutationAuthorityError);
     }
     async ensureRoot(options = {}) {
         await mkdirPathInRoot(this.context, {
+            ...this.mutationOptions(options),
             relativePath: "",
             allowRoot: true,
-            ...this.mutationOptions(options),
         }).catch(rethrowMutationAuthorityError);
     }
     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,
             ...this.mutationOptions(options),
+            atomic: undefined,
+            private: undefined,
+            strictFileSync: undefined,
+            relativePath,
+            data,
             durable: options.durable ?? this.defaults.durable ?? true,
         }).catch(rethrowMutationAuthorityError);
     }
     async create(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
+        const durable = options.durable ?? this.defaults.durable ?? true;
         await writeFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(createInputOptions(data, options, this.defaults.maxBytes)),
-            durable: options.durable ?? this.defaults.durable ?? true,
+            relativePath,
+            data,
+            durable: durable !== false,
+            strictFileSync: durable === "file",
             overwrite: false,
         }).catch(rethrowMutationAuthorityError).catch(rethrowCreateInputError);
     }
@@ -336,15 +342,17 @@ export class RootHandle {
         options.signal?.throwIfAborted();
         assertValidRootDestinationPath(relativePath);
         const { maxBytes, ...copyOptions } = this.mutationOptions(options);
+        const copySource = typeof source === "string" ? source : { root: source.root, relativePath: source.relativePath };
         await copyFileInRoot(this.context, {
-            source: typeof source === "string" ? source : { root: source.root, relativePath: source.relativePath },
-            relativePath,
             maxBytes: normalizeMaxBytes(maxBytes, { defaultValue: this.defaults.maxBytes }),
             mkdir: this.defaults.mkdir,
             ...copyOptions,
+            source: copySource,
+            relativePath,
             mode: options.mode ?? this.defaults.mode,
             durable: options.durable ?? this.defaults.durable ?? true,
             verifyPublished: options[onCopyPublication],
+            admitSource: options[onCopySourceAdmission],
         }).catch(rethrowMutationAuthorityError);
     }
     async exists(relativePath) {
@@ -361,19 +369,22 @@ export class RootHandle {
     }
     async stat(relativePath) {
         assertValidRootRelativePath(relativePath);
-        validatePinnedOperationPayload({ relativePath });
+        validatePinnedRelativePath(relativePath);
         return await statPathFallback(this.context, relativePath);
     }
     async list(relativePath, options = {}) {
         assertValidRootRelativePath(relativePath);
-        validatePinnedOperationPayload({ relativePath });
+        validatePinnedRelativePath(relativePath);
         return await listPathFallback(this.context, relativePath, options.withFileTypes === true);
     }
     async move(fromRelative, toRelative, options = {}) {
         assertValidRootRelativePath(fromRelative);
         assertValidRootDestinationPath(toRelative);
-        validatePinnedOperationPayload({ from: fromRelative, to: toRelative });
-        const { denyMutations, assertBeforeMutation, mutationSymlinks } = this.mutationOptions(options);
+        validatePinnedRelativePath(fromRelative);
+        validatePinnedRelativePath(toRelative);
+        const mutationOptions = this.mutationOptions(options);
+        const { assertBeforeMutation } = mutationOptions;
+        const { denyMutations, mutationSymlinks } = snapshotPinnedMutationPolicy(mutationOptions.denyMutations, mutationOptions.mutationSymlinks) ?? {};
         const overwrite = options.overwrite ?? false;
         await assertMoveMutationAllowed(this.context, {
             fromRelative,
@@ -399,10 +410,14 @@ export class RootHandle {
     walk(relativePath, options) {
         assertValidRootRelativePath(relativePath);
         return walkRoot({
-            rootReal: this.rootReal,
+            rootReal: this.context.rootReal,
+            observeRoot: () => createRootObservationGuard(this.context),
             stat: relative => this.stat(relative),
-            list: async (relative, listingOptions) => {
-                validatePinnedOperationPayload({ relativePath: relative });
+            list: async (relative, listingOptions, receipt) => {
+                validatePinnedRelativePath(relative);
+                if (receipt) {
+                    return await openRootDirectoryListing(this.context, receipt.targetPath, listingOptions, receipt);
+                }
                 const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
                 return await openRootDirectoryListing(this.context, resolved.resolved, listingOptions);
             },
@@ -458,15 +473,6 @@ async function readFileInRoot(root, params) {
         await opened.handle.close().catch(() => { });
     }
 }
-async function readPathInRoot(root, params) {
-    const relativePath = rootRelativeReadPath(root, params.filePath);
-    return await readFileInRoot(root, {
-        relativePath,
-        hardlinks: params.hardlinks,
-        maxBytes: params.maxBytes,
-        symlinks: params.symlinks,
-    });
-}
 export async function readLocalFileSafely(params) {
     const maxBytes = normalizeMaxBytes(params.maxBytes);
     const opened = await openLocalFileSafely({ filePath: params.filePath });
@@ -492,7 +498,7 @@ function buildAtomicWriteTempPath(targetPath) {
 function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
 }
-async function openWritableFileInRoot(root, params) {
+async function openWritableFileInRoot(root, params, options) {
     const guardedTarget = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : await resolveGuardedWriteTargetInRoot(root, {
@@ -507,7 +513,6 @@ async function openWritableFileInRoot(root, params) {
         relativePath: params.relativePath, guardedTarget, mkdir: params.mkdir,
         assertBeforeMutation: params.assertBeforeMutation,
     }) : undefined;
-    const mutationAdmission = prepared?.mutationAdmission;
     const preparedParent = prepared?.preparedParent;
     let ioPath = prepared?.targetPath ?? (params.mkdir === false ? resolved :
         await prepareRootWriteTarget(root, resolved, params.assertBeforeMutation));
@@ -556,6 +561,17 @@ async function openWritableFileInRoot(root, params) {
             if (!isNotFoundPathError(err)) {
                 throw err;
             }
+            if (options?.createIfMissing === false) {
+                const parentGuard = writePathSelection?.parentGuard ??
+                    await createAsyncDirectoryGuard(path.dirname(ioPath), { bigint: true });
+                assertRootIdentityCurrentSync(root);
+                if (!admitPathInsideRoot({
+                    rootPath: root.rootReal, candidatePath: parentGuard.realPath, rootIdentity: root.rootIdentity,
+                }))
+                    throw outsideWorkspaceError();
+                assertSyncDirectoryGuard(parentGuard);
+                return { missing: true, targetPath: ioPath, parentGuard, writeSelection: writePathSelection };
+            }
             if (writePathSelection)
                 await refreshRootWritePathSelection(writePathSelection);
             params.assertBeforeMutation?.();
@@ -673,9 +689,7 @@ async function openWritableFileInRoot(root, params) {
             stat,
             [Symbol.asyncDispose]: () => handle.close().catch(() => undefined),
         };
-        if (writeSelection)
-            retainRootWriteSelection(result, writeSelection);
-        return { opened: result, identity };
+        return { opened: result, identity, writeSelection };
     }
     catch (err) {
         const cleanupCreatedPath = createdForWrite && err instanceof FsSafeError;
@@ -715,8 +729,9 @@ async function appendFileInRoot(root, params) {
             if (params.prependNewlineIfNeeded === true &&
                 !target.createdForWrite &&
                 target.stat.size > 0 &&
+                params.data.length > 0 &&
                 ((typeof params.data === "string" && !params.data.startsWith("\n")) ||
-                    (Buffer.isBuffer(params.data) && params.data.length > 0 && params.data[0] !== 0x0a))) {
+                    (Buffer.isBuffer(params.data) && params.data[0] !== 0x0a))) {
                 const newline = Buffer.from("\n", typeof params.data === "string" ? params.encoding : "utf8");
                 const tail = Buffer.alloc(newline.length);
                 const { bytesRead } = await target.handle.read(tail, 0, tail.length, Math.max(0, target.stat.size - tail.length));
@@ -757,7 +772,7 @@ async function appendFileInRoot(root, params) {
     }
 }
 async function removePathInRoot(root, params) {
-    validatePinnedOperationPayload({ relativePath: params.relativePath });
+    validatePinnedRelativePath(params.relativePath);
     const removalReceipts = params.recursive ? undefined : new RemovalPathReceipts();
     const resolved = await resolvePinnedPathInRoot(root, {
         relativePath: params.relativePath,
@@ -776,24 +791,19 @@ async function removePathInRoot(root, params) {
     }
 }
 async function mkdirPathInRoot(root, params) {
-    validatePinnedOperationPayload({ relativePath: params.relativePath });
+    const privateMode = resolveCreationPermissions(params, true).private;
+    validatePinnedRelativePath(params.relativePath);
     const policy = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
+    const resolution = { relativePath: params.relativePath, allowRoot: params.allowRoot, ...policy };
     const resolveCurrent = policy
-        ? async () => await resolvePinnedPathInRoot(root, {
-            ...params,
-            denyMutations: policy.denyMutations,
-            mutationSymlinks: policy.mutationSymlinks,
-        })
+        ? async () => await resolvePinnedPathInRoot(root, resolution)
         : undefined;
-    const resolved = resolveCurrent
-        ? await resolveCurrent()
-        : await resolvePinnedPathInRoot(root, params);
+    const resolved = await resolvePinnedPathInRoot(root, resolution);
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
-            rootWithSep: ensureTrailingSep(resolved.rootReal),
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved.resolved,
             originalPath: params.relativePath,
@@ -808,19 +818,23 @@ async function mkdirPathInRoot(root, params) {
         await getFsSafeTestHooks()?.beforePinnedWriteParentAdmission?.(resolved.resolved);
     }
     try {
-        if (prepared?.mutationAdmission && params.assertBeforeMutation === undefined &&
+        if (!privateMode && prepared?.mutationAdmission && params.assertBeforeMutation === undefined &&
             await tryMkdirAtExactParent(root, resolved.resolved, prepared.mutationAdmission))
             return;
-        await mkdirPathFallback(root, resolved, params.assertBeforeMutation, policy?.mutationSymlinks !== undefined, prepared?.mutationAdmission);
+        await mkdirPathFallback(root, resolved, params.assertBeforeMutation, policy?.mutationSymlinks !== undefined, prepared?.mutationAdmission, privateMode);
     }
     catch (error) {
         throw normalizePinnedPathError(error);
     }
 }
 async function writeFileInRoot(root, params) {
+    if (params.private !== undefined) {
+        const permissions = resolveCreationPermissions(params, false);
+        params = { ...params, private: permissions.private, mode: permissions.mode };
+    }
     const input = rootWriteInput(params);
     await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
-        if (input.kind === "buffer" && process.platform === "win32" &&
+        if (!params.private && input.kind === "buffer" && !input.stageBeforePublish && process.platform === "win32" &&
             (params.renameIdentity === "verify-content-with-lock" || !getNativeBinding())) {
             await writeFileFallback(root, { ...params, data: input.data });
             return;
@@ -834,19 +848,29 @@ async function writeFileInRoot(root, params) {
 async function commitPinnedWriteInRoot(root, pinned, params, input) {
     let verifyingPublication = false;
     try {
+        if (params.private)
+            assertPrivateFileCreationAvailable();
+        if (params.private && params.mkdir !== false) {
+            const target = await prepareRootWriteTarget(root, pinned.targetPath, params.assertBeforeMutation, pinned.mutationAdmission, true);
+            if (target !== pinned.targetPath) {
+                throw new FsSafeError("path-mismatch", "private creation parent changed during admission");
+            }
+        }
         await runPinnedWriteWithRenamePolicy({
             rootPath: pinned.rootReal,
             relativeParentPath: pinned.relativeParentPath,
             basename: pinned.basename,
             targetPath: pinned.targetPath,
             renameIdentity: params.renameIdentity,
-            mkdir: params.mkdir !== false,
+            mkdir: !params.private && params.mkdir !== false,
+            private: params.private,
             mode: params.mode ?? pinned.mode,
             sync: params.durable !== false,
+            strictFileSync: params.strictFileSync,
             overwrite: params.overwrite,
             rejectFinalSymlink: params.mutationSymlinks !== undefined,
             input,
-            maxBytes: params.maxBytes,
+            maxBytes: input.kind === "buffer" ? undefined : params.maxBytes,
             rootIdentity: root.rootIdentity,
             mutationAdmission: pinned.mutationAdmission,
             assertBeforeMutation: params.assertBeforeMutation,
@@ -876,9 +900,7 @@ async function commitPinnedWriteInRoot(root, pinned, params, input) {
             throw error;
         }
         if (params.overwrite === false && isAlreadyExistsError(error)) {
-            throw new FsSafeError("already-exists", "file already exists", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("already-exists", "file already exists", errorCauseOptions(error));
         }
         throw normalizePinnedWriteError(error);
     }
@@ -910,12 +932,20 @@ async function copyFileInRoot(root, params) {
         throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${source.stat.size})`);
     }
     try {
+        const sourceAdmission = params.admitSource?.(sourceIdentity, source.realPath);
+        const mode = sourceAdmission?.mode ?? params.mode;
         await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
-            const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode ?? (params.preserveSourceMode ? Number(sourceIdentity.mode & 4095n) : undefined), params.denyMutations, params.overwrite !== false, params.mutationSymlinks);
+            const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, mode ?? (params.preserveSourceMode ? Number(sourceIdentity.mode & 4095n) : undefined), params.denyMutations, params.overwrite !== false, params.mutationSymlinks);
             await serializePathWrite(pinned.targetPath, async () => {
                 await assertCopySourceCurrent(source, sourceIdentity);
                 const verifySource = async () => {
                     params.signal?.throwIfAborted();
+                    try {
+                        sourceAdmission?.verify();
+                    }
+                    catch (error) {
+                        throw new MutationAuthorityError(error);
+                    }
                     if (typeof params.source !== "string") {
                         await params.source.root.stat(".");
                     }
@@ -933,11 +963,11 @@ async function copyFileInRoot(root, params) {
                         rejectFinalSymlink: params.mutationSymlinks !== undefined,
                         maxBytes: params.maxBytes,
                         sync: params.durable !== false,
-                        assertBeforeMutation: () => {
+                        assertBeforeMutation: params.signal || params.assertBeforeMutation ? () => {
                             if (params.signal?.aborted)
                                 throw new MutationAuthorityError(params.signal.reason);
                             params.assertBeforeMutation?.();
-                        },
+                        } : undefined,
                         verifyPublished: params.verifyPublished,
                         onPublished: observer.onPublished,
                         input: { kind: "file", handle: source.handle, size: source.stat.size, clone, signal: params.signal, verifySource },
@@ -963,20 +993,9 @@ async function copyFileInRoot(root, params) {
     }
 }
 async function resolvePinnedPathInRoot(root, params) {
-    return await resolvePinnedOperationPathInRoot(root, {
-        allowRoot: params.allowRoot,
-        denyMutations: params.denyMutations,
-        mutationSymlinks: params.mutationSymlinks,
-        protectDenyMutationAncestors: params.remove === true,
-        relativePath: params.relativePath,
-        policy: params.remove ? PATH_ALIAS_POLICIES.unlinkTarget : PATH_ALIAS_POLICIES.strict,
-        removalReceipts: params.removalReceipts,
-    });
-}
-async function resolvePinnedOperationPathInRoot(root, params) {
     const resolved = await resolvePinnedRootPathInRoot(root, {
         relativePath: params.relativePath,
-        policy: params.policy,
+        policy: params.remove ? PATH_ALIAS_POLICIES.unlinkTarget : PATH_ALIAS_POLICIES.strict,
         mutationSymlinks: params.mutationSymlinks,
         removalReceipts: params.removalReceipts,
     });
@@ -1003,7 +1022,7 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     }
     resolved.canonicalPath = admittedCanonicalPath.path;
     await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations, {
-        protectAncestors: params.protectDenyMutationAncestors,
+        protectAncestors: params.remove === true,
     });
     return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
 }
@@ -1031,10 +1050,8 @@ async function resolvePinnedRootPathInRoot(root, params) {
             throw err;
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
-    const rootWithSep = ensureTrailingSep(resolved.rootCanonicalPath);
     return {
         rootReal: resolved.rootCanonicalPath,
-        rootWithSep,
         canonicalPath: resolved.canonicalPath,
     };
 }
@@ -1054,6 +1071,8 @@ async function listPathFallback(root, relativePath, withFileTypes) {
     return await listDirectoryPath(root, resolved.resolved, withFileTypes, resolved.receipt);
 }
 async function movePathFallback(root, params) {
+    const originalRoutes = params.overwrite && params.assertBeforeMutation
+        ? await Promise.all([params.fromRelative, params.toRelative].map(expandRelativePathWithHome)) : undefined;
     const source = await resolvePathInRoot(root, params.fromRelative, {
         aliasErrorCode: "path-alias",
         allowFinalSymlink: true,
@@ -1089,9 +1108,14 @@ async function movePathFallback(root, params) {
                 targetStat?.isSymbolicLink() === true);
         },
     });
-    let sourceStat;
+    let sourceIdentity;
     try {
-        sourceStat = fsSync.lstatSync(source.resolved);
+        if (params.overwrite && params.assertBeforeMutation) {
+            sourceIdentity = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true));
+        }
+        else {
+            admitMoveSourceStat(fsSync.lstatSync(source.resolved), params.overwrite);
+        }
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -1099,19 +1123,10 @@ async function movePathFallback(root, params) {
         }
         throw error;
     }
-    if (sourceStat.isSymbolicLink()) {
-        throw new FsSafeError("symlink", "symlink not allowed");
-    }
-    if (sourceStat.isFile() && sourceStat.nlink > 1) {
-        throw hardlinkedPathNotAllowedError();
-    }
-    if (!params.overwrite && sourceStat.isDirectory()) {
-        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    if (!pinnedTarget) {
+        throw new FsSafeError("path-mismatch", "destination admission was not completed");
     }
     if (!params.overwrite) {
-        if (!pinnedTarget) {
-            throw new FsSafeError("path-mismatch", "destination admission was not completed");
-        }
         await movePathNoReplaceNative(root, params, {
             sourcePath: source.resolved,
             sourceParentPath: path.dirname(pinnedSource.canonicalPath),
@@ -1120,8 +1135,9 @@ async function movePathFallback(root, params) {
         });
         return;
     }
-    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved));
-    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved));
+    const guardOptions = { bigint: sourceIdentity !== undefined };
+    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved), guardOptions);
+    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved), guardOptions);
     await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("move", target.resolved);
     await assertAsyncDirectoryGuard(sourceParentGuard);
     await assertAsyncDirectoryGuard(targetParentGuard);
@@ -1129,6 +1145,31 @@ async function movePathFallback(root, params) {
         assertFinalSymlinkRejected(source.resolved, params.mutationSymlinks !== undefined);
         assertFinalSymlinkRejected(target.resolved, params.mutationSymlinks !== undefined);
         params.assertBeforeMutation?.();
+        if (sourceIdentity) {
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(sourceParentGuard);
+            assertSyncDirectoryGuard(targetParentGuard);
+            for (const [route, selected, expected, policy] of [
+                [originalRoutes[0], source.resolved, pinnedSource.canonicalPath, PATH_ALIAS_POLICIES.strict],
+                [originalRoutes[1], target.resolved, pinnedTarget.canonicalPath, PATH_ALIAS_POLICIES.unlinkTarget],
+            ]) {
+                for (const absolutePath of new Set([path.isAbsolute(route) ? route : `${root.rootWithSep}${route}`, selected])) {
+                    try {
+                        const current = resolveRootPathSync({
+                            absolutePath, rootPath: root.rootReal, rootCanonicalPath: root.rootReal,
+                            rootIdentity: root.rootIdentity, boundaryLabel: "root", policy,
+                            ...mutationSymlinkResolution(params.mutationSymlinks),
+                        });
+                        if (current.canonicalPath !== expected)
+                            throw new FsSafeError("path-mismatch", "move route changed during authorization");
+                    }
+                    catch (error) {
+                        throw normalizePinnedPathError(error);
+                    }
+                }
+            }
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true), sourceIdentity);
+        }
         await fs.rename(source.resolved, target.resolved);
     }
     catch (error) {
@@ -1136,9 +1177,7 @@ async function movePathFallback(root, params) {
             throw fileNotFoundError(error instanceof Error ? error : undefined);
         }
         if (hasNodeErrorCode(error, "EEXIST")) {
-            throw new FsSafeError("already-exists", "destination exists", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
         }
         throw error;
     }
@@ -1156,7 +1195,11 @@ async function writeFileFallback(root, params) {
     const policy = snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
     if (policy)
         params = { ...params, ...policy };
-    const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, params);
+    const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, {
+        relativePath: params.relativePath,
+        denyMutations: params.denyMutations,
+        mutationSymlinks: params.mutationSymlinks,
+    });
     await withRootFallbackCompatibilityLock({
         rootPath: rootReal, rootIdentity: root.rootIdentity, targetPath: resolved, assertBeforeMutation: params.assertBeforeMutation,
     }, async ({ targetPath, ...binding }) => await writeFileFallbackUnlocked(root, { ...params, ...binding }, targetPath));
@@ -1166,49 +1209,59 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         await writeMissingFileFallback(root, params, expectedWritePath);
         return;
     }
-    const { opened: target, identity: targetIdentity } = await openWritableFileInRoot(root, {
+    const admissionParams = {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
-        // Private, writable placeholder: Windows cannot rename over a read-only file.
-        mode: 0o600,
         denyMutations: params.denyMutations,
         assertBeforeMutation: params.assertBeforeMutation,
         mutationSymlinks: params.mutationSymlinks,
         truncateExisting: false,
         expectedWritePath,
-    });
+    };
+    const admission = await openWritableFileInRoot(root, admissionParams, { createIfMissing: false });
+    const existing = "missing" in admission ? undefined : admission;
+    const target = existing?.opened;
+    const retainedSelection = existing?.writeSelection;
+    const missingSelection = "missing" in admission ? admission.writeSelection : undefined;
     const policyEnabled = params.denyMutations !== undefined || params.mutationSymlinks !== undefined;
-    const retainedSelection = policyEnabled ? takeRootWriteSelection(target) : undefined;
-    const destinationPath = retainedSelection?.selectedPath ?? target.realPath;
-    const mode = params.mode ?? (target.stat.mode & 0o777);
-    if (policyEnabled && !retainedSelection) {
-        await target.handle.close().catch(() => undefined);
+    const destinationPath = "missing" in admission ? admission.targetPath
+        : retainedSelection?.selectedPath ?? admission.opened.realPath;
+    let mode = params.mode ?? (target ? target.stat.mode & 0o777 : undefined);
+    if (policyEnabled && !retainedSelection && !missingSelection) {
+        await target?.handle.close().catch(() => undefined);
         throw new FsSafeError("path-mismatch", "write admission state was not retained");
     }
-    const destinationGuard = retainedSelection?.parentGuard ??
+    const destinationGuard = "missing" in admission ? admission.parentGuard : retainedSelection?.parentGuard ??
         await createAsyncDirectoryGuard(path.dirname(destinationPath), { bigint: true }).catch(async (error) => {
-            await target.handle.close().catch(() => undefined);
+            await target?.handle.close().catch(() => undefined);
             throw error;
         });
     let tempPath = null;
     let unregisterTempPath = null;
     let writtenHandle;
     let writtenIdentity;
-    let placeholderIdentity;
-    let published = false;
+    let lateTargetHandle;
     try {
-        if (target.createdForWrite)
-            placeholderIdentity = targetIdentity;
         tempPath = buildAtomicWriteTempPath(destinationPath);
         if (retainedSelection) {
-            await refreshRetainedRootWriteAdmission(root, retainedSelection, true, target.handle.fd);
+            await refreshRetainedRootWriteAdmission(root, retainedSelection, true, target?.handle.fd);
+        }
+        else if (missingSelection) {
+            await refreshRootWritePathSelection(missingSelection);
         }
         params.assertBeforeMutation?.();
         if (retainedSelection) {
-            assertRootWriteSelectionSync(root, retainedSelection, true, target.handle.fd);
+            assertRootWriteSelectionSync(root, retainedSelection, true, target?.handle.fd);
+        }
+        else if (missingSelection) {
+            assertRootWritePathSelectionSync(root, missingSelection);
         }
+        assertRootIdentityCurrentSync(root);
+        assertSyncDirectoryGuard(destinationGuard);
         writtenHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
         writtenIdentity = fsSync.fstatSync(writtenHandle.fd, { bigint: true });
+        // Preserve the creation mask when no existing destination supplies a mode.
+        mode ??= Number(writtenIdentity.mode & 511n);
         unregisterTempPath = registerTempPathForExit(tempPath, { identity: writtenIdentity, singleLinkFile: true });
         await writeAllToFile(writtenHandle, params.data, {
             encoding: params.encoding, assertBeforeMutation: params.assertBeforeMutation,
@@ -1223,24 +1276,42 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
                 root, targetPath: commitTempPath, fd: commitHandle.fd,
                 expectedIdentity: commitIdentity, parentGuard: destinationGuard,
             });
-            if (target.createdForWrite) {
-                await cleanupPinnedFilePath({
-                    pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
-                });
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(destinationGuard);
+            let publicationIdentity = inspectFallbackReplacementDestination(destinationPath);
+            // A raced file needs its own access admission, not the old handle's rights.
+            if (publicationIdentity && (!existing || !sameFileIdentity(publicationIdentity, existing.identity))) {
+                const admitted = await openWritableFileInRoot(root, {
+                    ...admissionParams, mkdir: false, expectedWritePath: destinationPath,
+                }, { createIfMissing: false });
+                lateTargetHandle = "missing" in admitted ? undefined : admitted.opened.handle;
+                publicationIdentity = "missing" in admitted ? undefined : admitted.identity;
+                await lateTargetHandle?.close();
             }
             // Windows cannot replace a destination while its old handle remains open.
-            await target.handle.close();
+            await target?.handle.close();
             if (retainedSelection) {
-                await refreshRetainedRootWriteAdmission(root, retainedSelection, !target.createdForWrite);
+                await refreshRetainedRootWriteAdmission(root, retainedSelection, true);
+            }
+            else if (missingSelection) {
+                await refreshRootWritePathSelection(missingSelection);
             }
             assertFinalSymlinkRejected(destinationPath, params.mutationSymlinks !== undefined);
             params.assertBeforeMutation?.();
             if (retainedSelection) {
-                assertRootWriteSelectionSync(root, retainedSelection, !target.createdForWrite);
+                assertRootWriteSelectionSync(root, retainedSelection, true);
+            }
+            else if (missingSelection) {
+                assertRootWritePathSelectionSync(root, missingSelection);
+            }
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(destinationGuard);
+            const current = inspectFallbackReplacementDestination(destinationPath);
+            if (publicationIdentity ? !current || !sameFileIdentity(current, publicationIdentity) : current) {
+                throw new FsSafeError("path-mismatch", "write destination changed before publication");
             }
             await fs.rename(commitTempPath, destinationPath);
             tempPath = null;
-            published = true;
         });
         unregisterTempPath();
         unregisterTempPath = null;
@@ -1253,12 +1324,8 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         });
     }
     finally {
-        if (!published && target.createdForWrite) {
-            await cleanupPinnedFilePath({
-                pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
-            });
-        }
-        await target.handle.close().catch(() => undefined);
+        await target?.handle.close().catch(() => undefined);
+        await lateTargetHandle?.close().catch(() => undefined);
         if (tempPath && writtenHandle) {
             await cleanupPinnedFilePath({
                 pathname: tempPath, handle: writtenHandle, identity: writtenIdentity, parentGuard: destinationGuard,
@@ -1268,6 +1335,23 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         unregisterTempPath?.();
     }
 }
+function inspectFallbackReplacementDestination(targetPath) {
+    let current;
+    try {
+        current = inspectFileIdentitySync(() => fsSync.lstatSync(targetPath, { bigint: true }));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            return;
+        throw error;
+    }
+    if (current.isSymbolicLink() || !current.isFile()) {
+        throw new FsSafeError("path-mismatch", "write destination changed before publication");
+    }
+    if (current.nlink > 1n)
+        throw hardlinkedPathNotAllowedError();
+    return current;
+}
 async function writeMissingFileFallback(root, params, expectedWritePath) {
     const guardedTarget = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
@@ -1294,6 +1378,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
     const parentGuard = pathSelection?.parentGuard ??
         await createAsyncDirectoryGuard(path.dirname(targetPath), { bigint: true });
     let created = false;
+    let completed = false;
     let createdIdentity;
     let writtenHandle;
     let verifyingPublication = false;
@@ -1337,14 +1422,13 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
         });
         if (params.durable !== false)
             await syncDirectoryBestEffort(path.dirname(targetPath));
+        completed = true;
     }
     catch (err) {
         if (verifyingPublication)
             throw err;
         if (hasNodeErrorCode(err, "EEXIST")) {
-            throw new FsSafeError("already-exists", "file already exists", {
-                cause: err instanceof Error ? err : undefined,
-            });
+            throw new FsSafeError("already-exists", "file already exists", errorCauseOptions(err));
         }
         throw err;
     }
@@ -1354,6 +1438,9 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
                 pathname: targetPath, handle: writtenHandle, identity: createdIdentity, parentGuard,
             });
         }
-        await writtenHandle?.close().catch(() => undefined);
+        if (completed)
+            await writtenHandle?.close();
+        else
+            await writtenHandle?.close().catch(() => undefined);
     }
 }