@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/replace-directory.js

@@ -1,12 +1,81 @@
 import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { guardedRename, guardedRm } from "./guarded-mutation.js";
+import { assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { classifyNativeRenameFailure, NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH, } from "./native-rename-outcome.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { copyOperationalCode, RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { serializePathWrite } from "./write-queue.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+function distinctGuards(source, target) {
+    return source === target ? [source] : [source, target];
+}
+function assertGuardsCurrent(guards) {
+    for (const guard of guards)
+        assertSyncDirectoryGuard(guard);
+}
+function replacementFailure(error, message, details, cause = error) {
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, { cause, details });
+    }
+    const failure = new Error(message, { cause });
+    copyOperationalCode(failure, error);
+    Object.defineProperty(failure, "details", { configurable: true, value: details });
+    return failure;
+}
+function replacementAggregate(error, recoveryError, message, details) {
+    const combined = new AggregateError([error, recoveryError], "directory replacement operation and recovery both failed");
+    return replacementFailure(error, message, details, combined);
+}
+function isMissingDirectoryEntry(error) {
+    return error?.code === "ENOENT";
+}
+function observeOptionalDirectory(pathname) {
+    let initial;
+    try {
+        initial = fsSync.lstatSync(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (isMissingDirectoryEntry(error))
+            return undefined;
+        throw error;
+    }
+    return inspectDirectoryIdentitySync(pathname, undefined, initial);
+}
+function normalizeNativeRenameFailure(error) {
+    const code = error?.code;
+    if (code === NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH) {
+        return new FsSafeError("path-mismatch", "directory replacement source identity changed before native rename", { cause: error });
+    }
+    if (code === "EINVAL" || code === "ENOSYS" || code === "ENOTSUP" ||
+        code === "EOPNOTSUPP") {
+        return new FsSafeError("helper-unavailable", "native no-replace directory rename is unavailable on this filesystem", { cause: error });
+    }
+    return error;
+}
+function renameRetainedDirectory(params) {
+    const guards = distinctGuards(params.sourceParent, params.targetParent);
+    assertGuardsCurrent(guards);
+    const initial = fsSync.lstatSync(params.from, { bigint: true });
+    const identity = inspectDirectoryIdentitySync(params.from, params.expectedSource, initial);
+    try {
+        params.renameNoReplace(identity);
+    }
+    catch (error) {
+        if (classifyNativeRenameFailure(error) === "indeterminate") {
+            params.onIndeterminate();
+        }
+        throw normalizeNativeRenameFailure(error);
+    }
+    // Record the transition synchronously before any post-rename observation.
+    params.onRenamed?.(identity);
+    inspectDirectoryIdentitySync(params.to, identity);
+    assertGuardsCurrent(guards);
+    return identity;
+}
 export async function replaceDirectoryAtomic(options) {
     const stagedDirInput = admitStandalonePublicationPath(options.stagedDir, "staged directory uses a Windows filesystem namespace alias");
     const targetDirInput = admitStandalonePublicationPath(options.targetDir, "target directory uses a Windows filesystem namespace alias");
@@ -23,28 +92,184 @@ async function replaceDirectoryAtomicUnserialized(stagedDir, targetDir, backupPr
     const parentDir = path.dirname(targetDir);
     const backupPrefix = assertSafePathPrefix(backupPrefixInput ?? ".fs-safe-dir-backup-", { label: "atomic directory backup prefix" });
     const backupDir = path.join(parentDir, `${backupPrefix}${process.pid}-${randomUUID()}`);
-    let backupCreated = false;
+    const backup = {
+        identity: undefined,
+        transition: "not-renamed",
+    };
+    const publication = {
+        status: "not-published",
+    };
+    let operationFailed = false;
+    let operationError;
+    let operationDetails = {
+        phase: "backup",
+        publication: publication.status,
+        recovery: "none",
+    };
+    const retainedBinding = RetainedDirectoryReplacement.requireBinding();
     await fs.mkdir(recursiveMkdirPath(parentDir), { recursive: true });
+    const targetParent = await createAsyncDirectoryGuard(parentDir, { bigint: true });
+    const stagedParentDir = path.dirname(stagedDir);
+    const stagedParent = stagedParentDir === parentDir
+        ? targetParent
+        : await createAsyncDirectoryGuard(stagedParentDir, { bigint: true });
+    const stagedIdentity = inspectDirectoryIdentitySync(stagedDir);
+    const targetIdentity = observeOptionalDirectory(targetDir);
+    const retained = RetainedDirectoryReplacement.retain({
+        targetParent: {
+            path: parentDir,
+            realPath: targetParent.realPath,
+            identity: targetParent.stat,
+        },
+        stagedParent: {
+            path: stagedParentDir,
+            realPath: stagedParent.realPath,
+            identity: stagedParent.stat,
+        },
+        ...(targetIdentity ? {
+            originalTarget: { path: targetDir, identity: targetIdentity },
+        } : {}),
+    }, retainedBinding);
+    const targetBasename = path.basename(targetDir);
+    const stagedBasename = path.basename(stagedDir);
+    const backupBasename = path.basename(backupDir);
+    const details = (phase, recovery) => {
+        operationDetails = {
+            phase,
+            publication: publication.status,
+            recovery,
+            ...(backup.transition === "not-renamed" ? {} : { backupPath: backupDir }),
+        };
+        return operationDetails;
+    };
+    const rollback = (error, failedPhase, identity) => {
+        const rollbackState = {
+            transition: "not-renamed",
+        };
+        try {
+            renameRetainedDirectory({
+                from: backupDir,
+                to: targetDir,
+                sourceParent: targetParent,
+                targetParent,
+                expectedSource: identity,
+                renameNoReplace: expectedSource => {
+                    retained.renameNoReplace("target", backupBasename, targetBasename, expectedSource);
+                },
+                onIndeterminate() {
+                    rollbackState.transition = "indeterminate";
+                    backup.transition = "indeterminate";
+                },
+                onRenamed() {
+                    rollbackState.transition = "renamed";
+                    backup.transition = "not-renamed";
+                },
+            });
+        }
+        catch (rollbackError) {
+            const recovery = rollbackState.transition === "renamed"
+                ? "restored-unverified"
+                : rollbackState.transition === "indeterminate"
+                    ? "indeterminate"
+                    : "backup-path-preserved";
+            throw replacementAggregate(error, rollbackError, `directory ${failedPhase} and rollback failed`, details("rollback", recovery));
+        }
+        throw replacementFailure(error, `directory ${failedPhase} failed after restoring the original target`, details(failedPhase, "restored"));
+    };
     try {
-        await guardedRename({ from: targetDir, to: backupDir });
-        backupCreated = true;
-    }
-    catch (err) {
-        if (err.code !== "ENOENT") {
-            throw err;
+        if (targetIdentity) {
+            try {
+                backup.identity = renameRetainedDirectory({
+                    from: targetDir,
+                    to: backupDir,
+                    sourceParent: targetParent,
+                    targetParent,
+                    expectedSource: targetIdentity,
+                    renameNoReplace: expectedSource => {
+                        retained.renameNoReplace("target", targetBasename, backupBasename, expectedSource);
+                    },
+                    onIndeterminate() {
+                        backup.transition = "indeterminate";
+                    },
+                    onRenamed(identity) {
+                        backup.identity = identity;
+                        backup.transition = "renamed";
+                    },
+                });
+            }
+            catch (err) {
+                if (backup.transition === "renamed" && backup.identity) {
+                    rollback(err, "backup", backup.identity);
+                }
+                const recovery = backup.transition === "indeterminate" ? "indeterminate" : "none";
+                throw replacementFailure(err, "directory backup failed before publication", details("backup", recovery));
+            }
+        }
+        try {
+            renameRetainedDirectory({
+                from: stagedDir,
+                to: targetDir,
+                sourceParent: stagedParent,
+                targetParent,
+                expectedSource: stagedIdentity,
+                renameNoReplace: expectedSource => {
+                    retained.renameNoReplace("staged", stagedBasename, targetBasename, expectedSource);
+                },
+                onIndeterminate() {
+                    publication.status = "indeterminate";
+                },
+                onRenamed() {
+                    publication.status = "published";
+                },
+            });
+        }
+        catch (err) {
+            if (publication.status === "published") {
+                throw replacementFailure(err, "published directory failed retained identity verification", details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none"));
+            }
+            if (publication.status === "indeterminate") {
+                throw replacementFailure(err, "directory publication outcome is indeterminate", details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none"));
+            }
+            if (backup.transition === "renamed" && backup.identity) {
+                rollback(err, "publish", backup.identity);
+            }
+            throw replacementFailure(err, "directory publication failed before commit", details("publish", "none"));
+        }
+        details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none");
+        if (backup.transition === "renamed" && backup.identity) {
+            let cleanupAttempted = false;
+            try {
+                assertSyncDirectoryGuard(targetParent);
+                inspectDirectoryIdentitySync(backupDir, backup.identity);
+                cleanupAttempted = true;
+                const outcome = await retained.removeOriginal(backupBasename);
+                if (outcome !== "removed") {
+                    throw new FsSafeError("path-mismatch", "retained backup changed before bounded cleanup");
+                }
+                backup.transition = "not-renamed";
+                details("cleanup", "none");
+            }
+            catch (error) {
+                throw replacementFailure(error, "published directory but retained backup cleanup failed", {
+                    ...details("cleanup", cleanupAttempted ? "cleanup-incomplete" : "backup-path-preserved"),
+                });
+            }
         }
     }
-    try {
-        await guardedRename({ from: stagedDir, to: targetDir });
+    catch (error) {
+        operationFailed = true;
+        operationError = error;
+        throw error;
     }
-    catch (err) {
-        if (backupCreated) {
-            await guardedRename({ from: backupDir, to: targetDir }).catch(() => undefined);
-            backupCreated = false;
+    finally {
+        try {
+            retained.close();
+        }
+        catch (closeError) {
+            if (operationFailed) {
+                throw replacementAggregate(operationError, closeError, "directory replacement and retained descriptor close failed", operationDetails);
+            }
+            throw replacementFailure(closeError, "directory replacement retained descriptor close failed", operationDetails);
         }
-        throw err;
-    }
-    if (backupCreated) {
-        await guardedRm({ target: backupDir, recursive: true, force: true, verifyAfter: false });
     }
 }

package/node_modules/@openclaw/fs-safe/dist/replace-file-buffer.d.ts

@@ -0,0 +1,4 @@
+import type syncFs from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export declare function writeAtomicDestination(handle: FileHandle, data: Buffer, beforeWrite?: () => Promise<void>, assertBeforeMutation?: () => void, onWriting?: () => void): Promise<void>;
+export declare function writeAtomicDestinationSync(fsModule: Pick<typeof syncFs, "ftruncateSync" | "writeSync">, fd: number, data: Buffer, beforeWrite?: () => void, onWriting?: () => void): void;

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

@@ -0,0 +1,36 @@
+export async function writeAtomicDestination(handle, data, beforeWrite, assertBeforeMutation, onWriting) {
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        if (beforeWrite)
+            await beforeWrite();
+        assertBeforeMutation?.();
+        const result = await handle.write(data, written, data.length - written, written);
+        if (result.bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += result.bytesWritten;
+    }
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(data.length);
+}
+export function writeAtomicDestinationSync(fsModule, fd, data, beforeWrite, onWriting) {
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, 0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        beforeWrite?.();
+        const bytesWritten = fsModule.writeSync(fd, data, written, data.length - written, written);
+        if (bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += bytesWritten;
+    }
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, data.length);
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-copy-fallback.d.ts

@@ -1,4 +1,5 @@
 import syncFs, { type BigIntStats } from "node:fs";
+import { AtomicMutation } from "./replace-file-mutation.js";
 export type ReplaceFileDestinationHardlinkPolicy = "reject";
 export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
 export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
@@ -9,9 +10,8 @@ type AsyncFallbackFs = {
     lstat: typeof import("node:fs/promises").lstat;
     open: typeof import("node:fs/promises").open;
     rm: typeof import("node:fs/promises").rm;
-    unlink: typeof import("node:fs/promises").unlink;
 };
-type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "writeSync">;
 export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
 export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
 export declare function copyFallbackReplace(params: {
@@ -23,17 +23,10 @@ export declare function copyFallbackReplace(params: {
     maxRestoreBytes?: number;
     expectedSourceIdentity?: BigIntStats;
     sync: boolean;
+    mutation?: AtomicMutation;
 }): Promise<void>;
-export declare function copyFallbackReplaceSync(params: {
+export declare function copyFallbackReplaceSync(params: Omit<Parameters<typeof copyFallbackReplace>[0], "fsModule"> & {
     fsModule: SyncFallbackFs;
-    src: string;
-    dest: string;
-    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
-    restore: ReplaceFileCopyFallbackRestorePolicy;
-    maxRestoreBytes?: number;
-    expectedSourceIdentity?: BigIntStats;
     fchmodSync?: (fd: number, mode: number) => void;
-    sync: boolean;
 }): void;
 export {};
-//# sourceMappingURL=replace-file-copy-fallback.d.ts.map