@openclaw/feishu 2026.9.8 → 2026.10.1-beta.1

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

@@ -69,16 +69,20 @@ export function matchRootFileOpenFailure(failure, handlers) {
     }
     return handlers.fallback(failure);
 }
-function openRootFileResolved(params) {
+function finalizeRootFileOpen(params) {
+    if ("ok" in params.resolved) {
+        return params.resolved;
+    }
+    const resolved = params.resolved;
     const rejectHardlinks = params.rejectHardlinks ?? true;
     const opened = openPinnedFileSync({
-        filePath: params.absolutePath,
-        resolvedPath: params.resolvedPath,
+        filePath: resolved.absolutePath,
+        resolvedPath: resolved.resolvedPath,
         rejectHardlinks,
         maxBytes: params.maxBytes,
         allowedType: params.allowedType,
         ioFs: params.ioFs,
-        finalAdmission: createRootFileFinalAdmission(params.ioFs, params.rootObservation, params.boundaryLabel, rejectHardlinks),
+        finalAdmission: createRootFileFinalAdmission(params.ioFs, resolved.rootObservation, resolved.boundaryLabel, rejectHardlinks),
     });
     if (!opened.ok) {
         return opened;
@@ -88,25 +92,9 @@ function openRootFileResolved(params) {
         path: opened.path,
         fd: opened.fd,
         stat: opened.stat,
-        rootRealPath: params.rootRealPath,
+        rootRealPath: resolved.rootRealPath,
     };
 }
-function finalizeRootFileOpen(params) {
-    if ("ok" in params.resolved) {
-        return params.resolved;
-    }
-    return openRootFileResolved({
-        absolutePath: params.resolved.absolutePath,
-        resolvedPath: params.resolved.resolvedPath,
-        rootRealPath: params.resolved.rootRealPath,
-        boundaryLabel: params.resolved.boundaryLabel,
-        rootObservation: params.resolved.rootObservation,
-        maxBytes: params.maxBytes,
-        rejectHardlinks: params.rejectHardlinks,
-        allowedType: params.allowedType,
-        ioFs: params.ioFs,
-    });
-}
 export async function openRootFile(params) {
     const ioFs = params.ioFs ?? fs;
     const rawAbsolutePath = params.absolutePath;

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

@@ -50,7 +50,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     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";
@@ -69,6 +68,7 @@ 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 { isFsSafeNativeRequired } from "./native-config.js";
 import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
@@ -78,6 +78,7 @@ 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 { buildAtomicWriteTempPath, rootWriteQueueKey, tryMkdirRootNative, tryOpenCreateRootNative } from "./root-create-native.js";
 import { isNonRegularWriteOpenError, resolveNonblockingWriteFlag } from "./write-open-flags.js";
 import { resolveRootPath, resolveRootPathSync, resolveRootPathForRemoval } from "./root-path.js";
 import { RemovalPathReceipts } from "./root-remove-receipt.js";
@@ -93,6 +94,7 @@ import { stringifyJsonDocument } from "./json-stringify.js";
 import { walkRoot } from "./root-walk.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { removePathInRootFallback, validateRemoveOptions } from "./root-remove.js";
+import { removePathInRootNative } from "./root-remove-native.js";
 import { serializePathWrite } from "./write-queue.js";
 import { verifyAtomicWriteResult } from "./root-write-verification.js";
 import { assertRootWritePathSelectionSync, assertRootWriteSelectionSync, createRootWriteSelectionForFd, prepareGuardedRootWritePathSelection, resolveGuardedWritePathInRoot, resolveGuardedWriteTargetInRoot, resolvePinnedWriteTargetInRoot, refreshRetainedRootWriteAdmission, refreshRootWritePathSelection, } from "./root-write-admission.js";
@@ -101,12 +103,13 @@ import { finishRootFallbackWrite } from "./root-write-publication.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 { admitMoveSourceStat, movePathNoReplaceNative } from "./root-move-noreplace.js";
+import { admitMoveSourceStat, movePathNative } from "./root-move-noreplace.js";
 import { admitRootReadHandle, inspectOpenedPathIdentitySync } from "./root-read-admission.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 { assertExclusiveCreateLeaf } from "./exclusive-create.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
 import { resolvePinnedObservedPathInRoot } from "./root-observed-path.js";
 import { registerFileLockSyncRootAdapter } from "./file-lock-sync-root.js";
@@ -386,12 +389,14 @@ export class RootHandle {
         const { assertBeforeMutation } = mutationOptions;
         const { denyMutations, mutationSymlinks } = snapshotPinnedMutationPolicy(mutationOptions.denyMutations, mutationOptions.mutationSymlinks) ?? {};
         const overwrite = options.overwrite ?? false;
+        const requireNative = isFsSafeNativeRequired();
         await assertMoveMutationAllowed(this.context, {
             fromRelative,
             toRelative,
             denyMutations,
         });
         await movePathFallback(this.context, {
+            requireNative,
             fromRelative,
             denyMutations,
             assertBeforeMutation,
@@ -492,13 +497,11 @@ export async function openLocalFileSafely(params) {
 function emitWriteBoundaryWarning(reason) {
     logWarn(`security: fs-safe write boundary warning (${reason})`);
 }
-function buildAtomicWriteTempPath(targetPath) {
-    return path.join(path.dirname(targetPath), `.fs-safe-${randomUUID()}.tmp`);
-}
-function rootWriteQueueKey(root, relativePath) {
-    return `${root.rootReal}\0${relativePath}`;
-}
 async function openWritableFileInRoot(root, params, options) {
+    const requireNative = isFsSafeNativeRequired();
+    const policy = requireNative ? snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks) : undefined;
+    if (policy)
+        params = { ...params, ...policy };
     const guardedTarget = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : await resolveGuardedWriteTargetInRoot(root, {
@@ -509,12 +512,20 @@ async function openWritableFileInRoot(root, params, options) {
     const { resolved } = guardedTarget?.resolvedPath ?? await resolveGuardedWritePathInRoot(root, {
         relativePath: params.relativePath,
     });
-    const prepared = guardedTarget ? await prepareSharedRootWriteTarget(root, {
+    const resolveCurrent = async () => (await resolveGuardedWritePathInRoot(root, {
+        relativePath: params.relativePath, ...policy,
+    })).resolved;
+    const nativeParent = requireNative && params.mkdir !== false && await tryMkdirRootNative({
+        originalPath: params.relativePath,
+        root, directory: path.dirname(resolved), target: resolved, mkdir: true, policy,
+        resolveCurrent, assertBeforeMutation: params.assertBeforeMutation,
+    });
+    const prepared = !nativeParent && guardedTarget ? await prepareSharedRootWriteTarget(root, {
         relativePath: params.relativePath, guardedTarget, mkdir: params.mkdir,
         assertBeforeMutation: params.assertBeforeMutation,
     }) : undefined;
     const preparedParent = prepared?.preparedParent;
-    let ioPath = prepared?.targetPath ?? (params.mkdir === false ? resolved :
+    let ioPath = nativeParent ? resolved : prepared?.targetPath ?? (params.mkdir === false ? resolved :
         await prepareRootWriteTarget(root, resolved, params.assertBeforeMutation));
     const operationTargetPath = ioPath;
     try {
@@ -542,6 +553,8 @@ async function openWritableFileInRoot(root, params, options) {
     const mode = params.mode ?? 0o600;
     let handle;
     let createdForWrite = false;
+    let cleanupCreated;
+    let releaseCreationParent;
     let writePathSelection = undefined;
     const existingFlags = params.append ? OPEN_APPEND_EXISTING_FLAGS : OPEN_WRITE_EXISTING_FLAGS;
     const createFlags = params.append ? OPEN_APPEND_CREATE_FLAGS : OPEN_WRITE_CREATE_FLAGS;
@@ -574,10 +587,29 @@ async function openWritableFileInRoot(root, params, options) {
             }
             if (writePathSelection)
                 await refreshRootWritePathSelection(writePathSelection);
-            params.assertBeforeMutation?.();
-            if (writePathSelection)
-                assertRootWritePathSelectionSync(root, writePathSelection);
-            handle = await fs.open(ioPath, createFlags, mode);
+            const nativeCreated = requireNative ? await tryOpenCreateRootNative({
+                originalPath: params.relativePath,
+                root, directory: path.dirname(ioPath), target: ioPath, mkdir: false, policy,
+                resolveCurrent, assertBeforeMutation() {
+                    params.assertBeforeMutation?.();
+                    if (writePathSelection)
+                        assertRootWritePathSelectionSync(root, writePathSelection);
+                },
+                flags: createFlags, existingFlags, mode,
+            }) : undefined;
+            if (nativeCreated)
+                handle = nativeCreated.handle;
+            else {
+                params.assertBeforeMutation?.();
+                if (writePathSelection)
+                    assertRootWritePathSelectionSync(root, writePathSelection);
+                // Windows can follow a dangling symlink even with O_EXCL.
+                if (!SUPPORTS_NOFOLLOW)
+                    assertFinalSymlinkRejected(ioPath, true);
+                handle = await fs.open(ioPath, createFlags, mode);
+            }
+            cleanupCreated = nativeCreated?.cleanupCreated;
+            releaseCreationParent = nativeCreated?.releaseCreationParent;
             createdForWrite = true;
         }
     }
@@ -670,16 +702,16 @@ async function openWritableFileInRoot(root, params, options) {
         // irreversible side effects if a symlink target changes before validation.
         if (params.append !== true && params.truncateExisting !== false && !createdForWrite) {
             if (writeSelection)
-                await refreshRetainedRootWriteAdmission(root, writeSelection, true, handle.fd);
+                await refreshRetainedRootWriteAdmission(root, writeSelection, handle.fd);
             assertFinalSymlinkRejected(ioPath, params.mutationSymlinks !== undefined);
             params.assertBeforeMutation?.();
             if (writeSelection)
-                assertRootWriteSelectionSync(root, writeSelection, true, handle.fd);
+                assertRootWriteSelectionSync(root, writeSelection, handle.fd);
             await handle.truncate(0);
         }
         if (writeSelection) {
-            await refreshRetainedRootWriteAdmission(root, writeSelection, true, handle.fd);
-            assertRootWriteSelectionSync(root, writeSelection, true, handle.fd);
+            await refreshRetainedRootWriteAdmission(root, writeSelection, handle.fd);
+            assertRootWriteSelectionSync(root, writeSelection, handle.fd);
         }
         const result = {
             handle,
@@ -689,13 +721,21 @@ async function openWritableFileInRoot(root, params, options) {
             stat,
             [Symbol.asyncDispose]: () => handle.close().catch(() => undefined),
         };
-        return { opened: result, identity, writeSelection };
+        if (!params.keepCreationParent)
+            releaseCreationParent?.();
+        return { opened: result, identity, writeSelection, cleanupCreated, releaseCreationParent };
     }
     catch (err) {
         const cleanupCreatedPath = createdForWrite && err instanceof FsSafeError;
         const cleanupPath = realPathForCleanup ?? ioPath;
+        if (cleanupCreatedPath && cleanupCreated)
+            await cleanupCreated().catch(() => { });
+        try {
+            releaseCreationParent?.();
+        }
+        catch { /* Preserve the admission failure. */ }
         await handle.close().catch(() => { });
-        if (cleanupCreatedPath && createdIdentity) {
+        if (cleanupCreatedPath && createdIdentity && !cleanupCreated) {
             await removePathIfIdentityUnchanged(cleanupPath, createdIdentity).catch(() => { });
         }
         throw err;
@@ -704,7 +744,7 @@ async function openWritableFileInRoot(root, params, options) {
 async function appendFileInRoot(root, params) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        const { opened: target, identity } = await openWritableFileInRoot(root, {
+        const { opened: target, identity, cleanupCreated, releaseCreationParent } = await openWritableFileInRoot(root, {
             relativePath: params.relativePath,
             mkdir: params.mkdir,
             mode: params.mode,
@@ -713,17 +753,23 @@ async function appendFileInRoot(root, params) {
             mutationSymlinks: params.mutationSymlinks,
             truncateExisting: false,
             append: true,
+            keepCreationParent: true,
         });
+        const creationParent = __addDisposableResource(env_1, { [Symbol.dispose]() { releaseCreationParent?.(); } }, false);
         let dispatched = false;
         // Reverse disposal order closes the handle before path cleanup and retains both failures.
         const cleanup = __addDisposableResource(env_1, {
             async [Symbol.asyncDispose]() {
-                if (!dispatched && target.createdForWrite) {
+                if (!dispatched && target.createdForWrite && !cleanupCreated) {
                     await removePathIfIdentityUnchanged(target.realPath, identity);
                 }
             },
         }, true);
         const handle = __addDisposableResource(env_1, target.handle, true);
+        const nativeCleanup = __addDisposableResource(env_1, { async [Symbol.asyncDispose]() {
+                if (!dispatched && target.createdForWrite)
+                    await cleanupCreated?.();
+            } }, true);
         try {
             let prefix = "";
             if (params.prependNewlineIfNeeded === true &&
@@ -773,6 +819,9 @@ async function appendFileInRoot(root, params) {
 }
 async function removePathInRoot(root, params) {
     validatePinnedRelativePath(params.relativePath);
+    const requireNative = isFsSafeNativeRequired();
+    if (requireNative)
+        params = { ...params, ...snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks) };
     const removalReceipts = params.recursive ? undefined : new RemovalPathReceipts();
     const resolved = await resolvePinnedPathInRoot(root, {
         relativePath: params.relativePath,
@@ -782,7 +831,10 @@ async function removePathInRoot(root, params) {
         removalReceipts,
     });
     try {
-        await removePathInRootFallback(root, resolved.resolved, params, removalReceipts);
+        if (requireNative)
+            await removePathInRootNative(root, resolved.resolved, params, removalReceipts);
+        else
+            await removePathInRootFallback(root, resolved.resolved, params, removalReceipts);
     }
     catch (error) {
         if (params.recursive)
@@ -791,6 +843,7 @@ async function removePathInRoot(root, params) {
     }
 }
 async function mkdirPathInRoot(root, params) {
+    const requireNative = isFsSafeNativeRequired();
     const privateMode = resolveCreationPermissions(params, true).private;
     validatePinnedRelativePath(params.relativePath);
     const policy = params.denyMutations === undefined && params.mutationSymlinks === undefined
@@ -801,6 +854,13 @@ async function mkdirPathInRoot(root, params) {
         ? async () => await resolvePinnedPathInRoot(root, resolution)
         : undefined;
     const resolved = await resolvePinnedPathInRoot(root, resolution);
+    if (requireNative && await tryMkdirRootNative({
+        originalPath: params.relativePath,
+        root, directory: resolved.resolved, target: resolved.resolved, mkdir: true, private: privateMode,
+        policy, resolveCurrent: async () => (await resolvePinnedPathInRoot(root, resolution)).resolved,
+        assertBeforeMutation: params.assertBeforeMutation,
+    }))
+        return;
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
@@ -1057,17 +1117,13 @@ async function resolvePinnedRootPathInRoot(root, params) {
 }
 async function statPathFallback(root, relativePath) {
     const initialObservationHook = getFsSafeTestHooks()?.beforeRootStatInitialObservation;
-    const observed = initialObservationHook
-        ? undefined
+    const resolved = initialObservationHook
+        ? await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true })
         : await resolvePinnedObservedPathInRoot(root, relativePath, "stat");
-    const resolved = observed ??
-        await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
     return await statResolvedPathInRoot(root, resolved.resolved, resolved.receipt);
 }
 async function listPathFallback(root, relativePath, withFileTypes) {
-    const observed = await resolvePinnedObservedPathInRoot(root, relativePath, "directory");
-    const resolved = observed ??
-        await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
+    const resolved = await resolvePinnedObservedPathInRoot(root, relativePath, "directory");
     return await listDirectoryPath(root, resolved.resolved, withFileTypes, resolved.receipt);
 }
 async function movePathFallback(root, params) {
@@ -1126,13 +1182,23 @@ async function movePathFallback(root, params) {
     if (!pinnedTarget) {
         throw new FsSafeError("path-mismatch", "destination admission was not completed");
     }
-    if (!params.overwrite) {
-        await movePathNoReplaceNative(root, params, {
+    const nativeReplace = params.overwrite && params.requireNative
+        ? getNativeBinding()?.renameReplaceWithIdentity : undefined;
+    if (params.overwrite && !nativeReplace && params.requireNative) {
+        throw new FsSafeError("helper-unavailable", "native overwrite move is unavailable");
+    }
+    if (!params.overwrite || nativeReplace) {
+        await movePathNative(root, params, {
             sourcePath: source.resolved,
             sourceParentPath: path.dirname(pinnedSource.canonicalPath),
             targetPath: target.resolved,
             targetParentPath: path.dirname(pinnedTarget.canonicalPath),
-        });
+            sourceOriginalPath: originalRoutes?.[0],
+            targetOriginalPath: originalRoutes?.[1],
+            sourceCanonicalPath: pinnedSource.canonicalPath,
+            targetCanonicalPath: pinnedTarget.canonicalPath,
+            expectedSourceIdentity: sourceIdentity,
+        }, params.overwrite);
         return;
     }
     const guardOptions = { bigint: sourceIdentity !== undefined };
@@ -1244,20 +1310,21 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
     try {
         tempPath = buildAtomicWriteTempPath(destinationPath);
         if (retainedSelection) {
-            await refreshRetainedRootWriteAdmission(root, retainedSelection, true, target?.handle.fd);
+            await refreshRetainedRootWriteAdmission(root, retainedSelection, target?.handle.fd);
         }
         else if (missingSelection) {
             await refreshRootWritePathSelection(missingSelection);
         }
         params.assertBeforeMutation?.();
         if (retainedSelection) {
-            assertRootWriteSelectionSync(root, retainedSelection, true, target?.handle.fd);
+            assertRootWriteSelectionSync(root, retainedSelection, target?.handle.fd);
         }
         else if (missingSelection) {
             assertRootWritePathSelectionSync(root, missingSelection);
         }
         assertRootIdentityCurrentSync(root);
         assertSyncDirectoryGuard(destinationGuard);
+        assertExclusiveCreateLeaf(tempPath);
         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.
@@ -1291,7 +1358,7 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
             // Windows cannot replace a destination while its old handle remains open.
             await target?.handle.close();
             if (retainedSelection) {
-                await refreshRetainedRootWriteAdmission(root, retainedSelection, true);
+                await refreshRetainedRootWriteAdmission(root, retainedSelection);
             }
             else if (missingSelection) {
                 await refreshRootWritePathSelection(missingSelection);
@@ -1299,7 +1366,7 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
             assertFinalSymlinkRejected(destinationPath, params.mutationSymlinks !== undefined);
             params.assertBeforeMutation?.();
             if (retainedSelection) {
-                assertRootWriteSelectionSync(root, retainedSelection, true);
+                assertRootWriteSelectionSync(root, retainedSelection);
             }
             else if (missingSelection) {
                 assertRootWritePathSelectionSync(root, missingSelection);
@@ -1388,6 +1455,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
             params.assertBeforeMutation?.();
             if (mutationAdmission)
                 assertSyncDirectoryGuard(parentGuard);
+            assertExclusiveCreateLeaf(targetPath);
             const handle = await fs.open(targetPath, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600).catch((error) => recordExclusiveCreateFailure(error, targetPath));
             writtenHandle = handle;
             created = true;

package/node_modules/@openclaw/fs-safe/dist/root-move-noreplace.d.ts

@@ -2,9 +2,14 @@ import { type BigIntStats, type Stats } from "node:fs";
 import type { RootMoveOptions } from "./root-options.js";
 import { type RootContext } from "./root-context.js";
 export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
-export declare function movePathNoReplaceNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
+export declare function movePathNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
     sourcePath: string;
     sourceParentPath: string;
     targetPath: string;
     targetParentPath: string;
-}): Promise<void>;
+    sourceOriginalPath?: string;
+    targetOriginalPath?: string;
+    sourceCanonicalPath?: string;
+    targetCanonicalPath?: string;
+    expectedSourceIdentity?: BigIntStats;
+}, overwrite?: boolean): Promise<void>;

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

@@ -10,7 +10,8 @@ import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root
 import { resolveRootPathSync } from "./root-path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
-import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { assertFinalSymlinkRejected, mutationSymlinkResolution } from "./root-symlink-policy.js";
+import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -40,11 +41,19 @@ function nativePrimitiveUnavailable(error) {
     return code === "ENOSYS" || code === "ENOTSUP" || code === "EOPNOTSUPP";
 }
 function normalizeMoveError(error) {
+    if (error instanceof FsSafeError)
+        return error;
+    const code = error?.code;
+    if (code === "path-mismatch" || code === "hardlink") {
+        return new FsSafeError(code, "native move source changed", errorCauseOptions(error));
+    }
+    if (code === "ELOOP")
+        return new FsSafeError("symlink", "native move source is a symlink", errorCauseOptions(error));
     if (isNotFoundPathError(error)) {
         return fileNotFoundError(error instanceof Error ? error : undefined);
     }
     if (nativePrimitiveUnavailable(error)) {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", errorCauseOptions(error));
+        return new FsSafeError("helper-unavailable", "native move is unavailable", errorCauseOptions(error));
     }
     return error;
 }
@@ -66,26 +75,28 @@ export function admitMoveSourceStat(stat, overwrite = false) {
     }
     return stat;
 }
-export async function movePathNoReplaceNative(root, params, paths) {
-    try {
-        fsSync.lstatSync(paths.targetPath);
-        throw new FsSafeError("already-exists", "destination exists");
-    }
-    catch (error) {
-        if (error instanceof FsSafeError)
-            throw error;
-        if (!isNotFoundPathError(error))
-            throw error;
-        // Advisory fast rejection only. renameNoReplace owns the collision decision.
-    }
+export async function movePathNative(root, params, paths, overwrite = false) {
+    if (!overwrite)
+        try {
+            fsSync.lstatSync(paths.targetPath);
+            throw new FsSafeError("already-exists", "destination exists");
+        }
+        catch (error) {
+            if (error instanceof FsSafeError)
+                throw error;
+            if (!isNotFoundPathError(error))
+                throw error;
+            // Advisory fast rejection only. renameNoReplace owns the collision decision.
+        }
     const binding = requireNativeBinding();
-    if (typeof binding.renameNoReplace !== "function") {
-        throw new FsSafeError("helper-unavailable", "native no-replace move is unavailable");
+    if (typeof (overwrite ? binding.renameReplaceWithIdentity : binding.renameNoReplace) !== "function") {
+        throw new FsSafeError("helper-unavailable", "native move is unavailable");
     }
     const rootAdmission = await openNativeRootAdmission(binding, {
         rootPath: root.rootReal,
         rootIdentity: root.rootIdentity,
         operation: "native move",
+        searchOnly: true,
     });
     let sourceParent;
     let targetParent;
@@ -113,14 +124,13 @@ export async function movePathNoReplaceNative(root, params, paths) {
         await assertRootIdentityCurrent(root);
         for (const admission of parentAdmissions)
             assertSyncDirectoryGuard(admission.guard);
-        // Capture an exact receipt only when admission must survive a callback.
-        let sourceStat;
-        if (params.assertBeforeMutation) {
-            sourceStat = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })));
-        }
-        else {
+        // Overwrite publication always binds an exact source; no-clobber retains
+        // its existing callback-dependent identity contract.
+        const sourceStat = overwrite || params.assertBeforeMutation
+            ? inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true }), overwrite), paths.expectedSourceIdentity)
+            : undefined;
+        if (!sourceStat)
             admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath));
-        }
         assertFinalSymlinkRejected(admittedTargetPath, params.mutationSymlinks !== undefined);
         params.assertBeforeMutation?.();
         if (params.assertBeforeMutation || params.mutationSymlinks === "reject") {
@@ -145,21 +155,43 @@ export async function movePathNoReplaceNative(root, params, paths) {
                 assertSyncDirectoryGuard(admission.guard);
         }
         // The callback can change a leaf without replacing its admitted parent.
+        if (overwrite && params.assertBeforeMutation) {
+            for (const [original, selected, expected, policy] of [
+                [paths.sourceOriginalPath, admittedSourcePath, paths.sourceCanonicalPath, PATH_ALIAS_POLICIES.strict],
+                [paths.targetOriginalPath, admittedTargetPath, paths.targetCanonicalPath, PATH_ALIAS_POLICIES.unlinkTarget],
+            ]) {
+                if (original === undefined || expected === undefined)
+                    continue;
+                for (const absolutePath of new Set([path.isAbsolute(original) ? original : `${root.rootWithSep}${original}`, selected])) {
+                    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");
+                }
+            }
+        }
         if (sourceStat !== undefined) {
-            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })), sourceStat);
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true }), overwrite), sourceStat);
         }
         try {
-            binding.renameNoReplace(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath));
+            assertFinalSymlinkRejected(admittedTargetPath, params.mutationSymlinks !== undefined);
+            if (overwrite)
+                binding.renameReplaceWithIdentity(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath), sourceStat.dev, sourceStat.ino);
+            else
+                binding.renameNoReplace(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath));
         }
         catch (error) {
-            if (isAlreadyExistsError(error) || error?.code === "ENOTEMPTY") {
+            if (isAlreadyExistsError(error) || (!overwrite && error?.code === "ENOTEMPTY")) {
                 throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
             }
-            throw normalizeRenameNoReplaceError(error);
+            throw overwrite ? normalizeMoveError(error) : normalizeRenameNoReplaceError(error);
         }
         try {
             for (const admission of parentAdmissions)
                 await assertAsyncDirectoryGuard(admission.guard);
+            if (overwrite)
+                inspectFileIdentitySync(() => fsSync.lstatSync(admittedTargetPath, { bigint: true }), sourceStat);
         }
         catch (error) {
             throw normalizePinnedPathError(error);
@@ -188,18 +220,15 @@ export async function movePathNoReplaceNative(root, params, paths) {
     catch (error) {
         closeErrors.push(error);
     }
-    if (failed) {
-        if (closeErrors.length > 0) {
-            const closeError = closeErrors.length === 1
-                ? closeErrors[0]
-                : new AggregateError(closeErrors, "native move descriptor closes failed");
+    if (closeErrors.length > 0) {
+        const closeError = closeErrors.length === 1
+            ? closeErrors[0]
+            : new AggregateError(closeErrors, "native move descriptor closes failed");
+        if (failed) {
             throw createSuppressedError(closeError, operationError, "native move and descriptor close failed");
         }
-        throw operationError;
-    }
-    if (closeErrors.length === 1)
-        throw closeErrors[0];
-    if (closeErrors.length > 1) {
-        throw new AggregateError(closeErrors, "native move descriptor closes failed");
+        throw closeError;
     }
+    if (failed)
+        throw operationError;
 }

package/node_modules/@openclaw/fs-safe/dist/root-observed-path.d.ts

@@ -4,4 +4,4 @@ export type PinnedObservedPath = {
     resolved: string;
     receipt?: RootPathObservationReceipt;
 };
-export declare function resolvePinnedObservedPathInRoot(root: RootContext, relativePath: string, kind: RootPathObservationKind): Promise<PinnedObservedPath | undefined>;
+export declare function resolvePinnedObservedPathInRoot(root: RootContext, relativePath: string, kind: RootPathObservationKind): Promise<PinnedObservedPath>;

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

@@ -11,8 +11,6 @@ import { errorCauseOptions, fileNotFoundError, outsideWorkspaceError } from "./r
 import { getFsSafeTestHooks } from "./test-hooks.js";
 export async function resolvePinnedObservedPathInRoot(root, relativePath, kind) {
     const rootGuard = await createRootObservationGuard(root);
-    if (!rootGuard)
-        return undefined;
     // Race hooks exercise the established JavaScript observation points. Do not
     // silently move those points into the native helper in test configurations.
     const directoryObserver = getNativeDirectoryObservationBackend(getFsSafeTestHooks() === undefined);

package/node_modules/@openclaw/fs-safe/dist/root-options.d.ts

@@ -19,12 +19,11 @@ export type RootDefaults = {
     mkdir?: boolean;
     mode?: number;
     denyMutations?: DenyMutationPolicy;
-    nonBlockingRead?: boolean;
     renameIdentity?: RenameIdentityPolicy;
     symlinks?: SymlinkPolicy;
     mutationSymlinks?: MutationSymlinkPolicy;
 };
-export type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
+export type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "symlinks">;
 export type RootOpenOptions = Omit<RootReadOptions, "maxBytes">;
 export type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
     encoding?: BufferEncoding;
@@ -79,6 +78,6 @@ export type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "den
 export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
     private?: boolean;
 };
-export type RootReadParams = Omit<RootReadOptions, "nonBlockingRead">;
+export type RootReadParams = RootReadOptions;
 export declare function readDefaults(defaults: RootDefaults): RootReadParams;
 export declare function mergeReadOptions(defaults: RootDefaults, options: RootReadOptions): RootReadParams;