@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/file-store-sync-write.js

@@ -1,19 +1,46 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
 import { syncDirectorySync } from "./directory-durability.js";
+import { createDirectoryReceiptFromIdentity } from "./directory-receipt.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
-import { assertSyncDirectoryGuard, ensureParentSync, ensureStoreDirectorySync, } from "./file-store-boundary.js";
+import { ensureParentSync, ensureStoreDirectorySync, } from "./file-store-boundary.js";
+import { assertSyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
 import { isPathInside } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { writeTempFileSync } from "./replace-file-descriptor.js";
+import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { errorCauseOptions } from "./root-errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
-    return ensureStoreDirectorySync({
-        rootDir,
-        targetDir,
-        mode,
-        messagePrefix: "private store",
-    });
+function verifyStoreFile(fd, expected, filePath) {
+    const assertFile = (stat, allowUnknown = false) => {
+        const unknown = allowUnknown && process.platform === "win32" && (stat.dev === 0n || stat.ino === 0n);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n ||
+            (stat.dev !== expected.dev && !(unknown && stat.dev === 0n)) ||
+            (stat.ino !== expected.ino && !(unknown && stat.ino === 0n))) {
+            throw new FsSafeError("path-mismatch", "store file changed during write");
+        }
+        return unknown;
+    };
+    const assertDescriptor = (descriptor) => {
+        assertFile(inspectFileIdentitySync(() => fs.fstatSync(descriptor, { bigint: true }), expected));
+    };
+    assertDescriptor(fd);
+    if (assertFile(fs.lstatSync(filePath, { bigint: true }), true)) {
+        // A Windows pathname can have opaque metadata even while the retained writer is known.
+        // Reopen for identity only; equal content cannot establish that publication kept its file.
+        const reopened = fs.openSync(filePath, resolveReadOpenFlags());
+        try {
+            assertDescriptor(reopened);
+            assertFile(fs.lstatSync(filePath, { bigint: true }), true);
+            assertDescriptor(reopened);
+        }
+        finally {
+            fs.closeSync(reopened);
+        }
+    }
+    assertDescriptor(fd);
 }
 export function writeFileSyncAtomic(params) {
     const filePath = path.resolve(params.filePath);
@@ -22,7 +49,12 @@ export function writeFileSyncAtomic(params) {
     }
     let parentGuard;
     if (params.privateMode) {
-        parentGuard = ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
+        parentGuard = ensureStoreDirectorySync({
+            rootDir: params.rootDir,
+            targetDir: path.dirname(filePath),
+            mode: params.dirMode,
+            messagePrefix: "private store",
+        });
         try {
             const stat = fs.lstatSync(filePath);
             if (stat.isSymbolicLink() || !stat.isFile()) {
@@ -42,86 +74,55 @@ export function writeFileSyncAtomic(params) {
             mode: params.dirMode,
         });
     }
-    const tempPath = path.join(parentGuard?.dir ?? path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
-    let tempExists = false;
+    const tempPath = path.join(parentGuard.dir, `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
+    const owner = new SyncAtomicTempOwner(tempPath);
+    let originalFailure;
     try {
         getFsSafeTestHooks()?.beforeFileStoreSyncPrivateWrite?.(filePath);
-        if (parentGuard) {
-            assertSyncDirectoryGuard(parentGuard);
-        }
-        const tempStat = (() => {
-            const descriptor = fs.openSync(tempPath, "wx", params.mode);
-            tempExists = true;
-            try {
-                fs.writeFileSync(descriptor, params.content);
+        assertSyncStoreDirectoryReceipt(parentGuard);
+        owner.start();
+        const temp = writeTempFileSync({
+            fsModule: fs, tempPath, content: params.content, mode: params.mode, sync: false,
+            onIdentity: owner.onIdentity,
+            fchmodSync: (descriptor, mode) => {
                 try {
-                    fs.fchmodSync(descriptor, params.mode);
+                    fs.fchmodSync(descriptor, mode);
                 }
                 catch {
                     // Best-effort on platforms that do not enforce POSIX modes.
                 }
-                const opened = fs.fstatSync(descriptor);
-                if (!opened.isFile() || opened.nlink > 1) {
-                    throw new FsSafeError("path-mismatch", "store temp is not an owned regular file");
-                }
-                fs.fsyncSync(descriptor);
-                return opened;
-            }
-            finally {
-                fs.closeSync(descriptor);
-            }
-        })();
-        const tempPathStat = fs.lstatSync(tempPath);
-        if (tempPathStat.isSymbolicLink() ||
-            !tempPathStat.isFile() ||
-            tempPathStat.nlink > 1 ||
-            !sameFileIdentity(tempPathStat, tempStat)) {
-            throw new FsSafeError("path-mismatch", "store temp changed before publication");
-        }
-        if (parentGuard) {
-            assertSyncDirectoryGuard(parentGuard);
-        }
+            },
+        });
+        owner.adopt(temp);
+        // Preserve the store's strict fsync errors; the generic temp helper tolerates EPERM.
+        if (params.durable)
+            fs.fsyncSync(temp.fd);
+        verifyStoreFile(temp.fd, owner.identity, tempPath);
+        assertSyncStoreDirectoryReceipt(parentGuard);
         fs.renameSync(tempPath, filePath);
-        tempExists = false;
-        if (parentGuard) {
-            assertSyncDirectoryGuard(parentGuard);
-        }
+        owner.markRenamed();
+        assertSyncStoreDirectoryReceipt(parentGuard);
         try {
-            const publishedStat = fs.lstatSync(filePath);
-            if (publishedStat.isSymbolicLink() ||
-                !publishedStat.isFile() ||
-                publishedStat.nlink > 1 ||
-                !sameFileIdentity(tempStat, publishedStat)) {
-                throw new FsSafeError("path-mismatch", "store target changed after write");
-            }
+            verifyStoreFile(temp.fd, owner.identity, filePath);
         }
         catch (error) {
             if (error instanceof FsSafeError) {
                 throw error;
             }
-            throw new FsSafeError("path-mismatch", "store target changed after write", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("path-mismatch", "store target changed after write", errorCauseOptions(error));
         }
-        if (parentGuard) {
-            assertSyncDirectoryGuard(parentGuard);
-            syncDirectorySync({
-                path: parentGuard.dir,
-                realPath: parentGuard.realPath,
-                identity: parentGuard.stat,
-            }, { label: "store parent" });
-            assertSyncDirectoryGuard(parentGuard);
+        assertSyncStoreDirectoryReceipt(parentGuard);
+        if (params.durable) {
+            syncDirectorySync(createDirectoryReceiptFromIdentity(parentGuard.dir, parentGuard.realPath, parentGuard.exactStat), { label: "store parent" });
         }
+        assertSyncStoreDirectoryReceipt(parentGuard);
         return filePath;
     }
+    catch (error) {
+        originalFailure = { error };
+        throw error;
+    }
     finally {
-        if (tempExists) {
-            try {
-                fs.unlinkSync(tempPath);
-            }
-            catch {
-                // Best-effort cleanup after write failure.
-            }
-        }
+        owner.finish({ fsModule: fs, originalFailure, throwOnCleanupError: false });
     }
 }

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

@@ -6,11 +6,15 @@ import { type OpenResult, type ReadResult, type Root, type RootReadOptions } fro
 export type FileStoreOptions = {
     rootDir: string;
     private?: boolean;
+    /** Default for writes, streams, and copies; true syncs file and parent where supported. */
+    durable?: boolean;
     dirMode?: number;
     mode?: number;
     maxBytes?: number;
 };
 export type FileStoreWriteOptions = {
+    /** Override store durability; defaults to the store option, then true. */
+    durable?: boolean;
     dirMode?: number;
     mode?: number;
     maxBytes?: number;
@@ -59,4 +63,3 @@ export type FileStoreSync = {
 };
 export declare function fileStore(options: FileStoreOptions): FileStore;
 export declare function fileStoreSync(options: FileStoreOptions): FileStoreSync;
-//# sourceMappingURL=file-store.d.ts.map

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

@@ -1,38 +1,33 @@
 import syncFs from "node:fs";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
-import { assertFileStoreMaxBytes } from "./file-store-limit.js";
 import { pruneExpiredStoreEntries } from "./file-store-prune.js";
-import { ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { writeFileSyncAtomic } from "./file-store-sync-write.js";
 import { createJsonStore } from "./json-document-store.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
-import { isNotFoundPathError, resolveSafeRelativePath, splitSafeRelativePath } from "./path.js";
+import { isNotFoundPathError } from "./path.js";
 import { throwFsSafeReadError } from "./root-errors.js";
 import { root } from "./root.js";
 import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
-import { readRegularFile } from "./regular-file.js";
 import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
 import { writeSecretFileAtomic } from "./secret-file.js";
-function assertRelativePath(relativePath) {
-    const raw = relativePath.trim();
-    if (!raw || raw !== relativePath) {
-        throw new FsSafeError("invalid-path", "store key must be non-empty and unpadded");
-    }
-    const segments = splitSafeRelativePath(raw);
-    if (segments.length === 0 ||
-        segments.join("/") !== raw ||
-        raw.normalize("NFC") !== raw ||
-        segments.some((segment) => /[ .]$/u.test(segment))) {
-        throw new FsSafeError("invalid-path", "store key must use one canonical relative spelling");
-    }
-    return raw;
-}
-function resolveStorePath(rootDir, relativePath) {
-    return resolveSafeRelativePath(rootDir, assertRelativePath(relativePath));
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function snapshotWriteOptions(options, durabilityFirst = true) {
+    if (options == null)
+        return undefined;
+    return durabilityFirst ? {
+        maxBytes: options.maxBytes,
+        durable: options.durable,
+        dirMode: options.dirMode,
+        mode: options.mode,
+    } : {
+        maxBytes: options.maxBytes,
+        dirMode: options.dirMode,
+        mode: options.mode,
+        durable: options.durable,
+    };
 }
 function isNotFound(error) {
     return error instanceof FsSafeError ? error.code === "not-found" : isNotFoundPathError(error);
@@ -65,58 +60,38 @@ function handleSyncStoreReadOpenFailure(opened) {
         },
     });
 }
-async function readFileStoreCopySource(params) {
-    const sourceStat = syncFs.lstatSync(params.sourcePath);
-    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-        throw new FsSafeError("not-file", "source path is not a file");
-    }
-    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
-    try {
-        return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
-            .buffer;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("regular file") || message.includes("not a regular file")) {
-            throw new FsSafeError("not-file", "source path is not a file", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        if (params.maxBytes !== undefined && message.includes(`exceeds ${params.maxBytes} bytes`)) {
-            throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`, {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
-}
 async function copyIntoRoot(params) {
     const relativePath = assertRelativePath(params.relativePath);
     const destination = resolveStorePath(params.rootDir, relativePath);
+    assertNoWindowsPathAlias(params.sourcePath, "filesystem", "source path uses a Windows filesystem namespace alias");
     const sourceStat = syncFs.lstatSync(params.sourcePath);
     if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
         throw new FsSafeError("not-file", "source path is not a file");
     }
     assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
-    const dirMode = params.dirMode ?? 0o700;
     const scopedRoot = await openWritableStoreRoot({
         rootDir: params.rootDir,
-        dirMode,
+        dirMode: params.dirMode,
         maxBytes: params.maxBytes,
     });
-    await ensureParentInRoot(scopedRoot, relativePath, dirMode);
+    await ensureParentInRoot(scopedRoot, relativePath, params.dirMode);
     await scopedRoot.copyIn(relativePath, params.sourcePath, {
+        durable: params.durable,
         maxBytes: params.maxBytes,
         mkdir: false,
-        mode: params.mode ?? 0o600,
+        mode: params.mode,
     });
     return destination;
 }
 export function fileStore(options) {
-    const rootDir = path.resolve(options.rootDir);
+    const rootDirInput = options.rootDir;
+    assertNoWindowsPathAlias(rootDirInput, "filesystem", "store root uses a Windows filesystem namespace alias");
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+    assertNoWindowsPathAlias(rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
     const privateMode = options.private ?? false;
     const dirMode = options.dirMode ?? 0o700;
     const mode = options.mode ?? 0o600;
+    const durable = options.durable ?? true;
     const maxBytes = normalizeMaxBytes(options.maxBytes);
     async function openRoot() {
         return await root(rootDir, { hardlinks: "reject", maxBytes });
@@ -132,12 +107,15 @@ export function fileStore(options) {
                 rootDir,
                 filePath: destination,
                 content,
+                durable: writeOptions?.durable ?? durable,
                 dirMode: writeOptions?.dirMode ?? dirMode,
                 mode: writeOptions?.mode ?? mode,
             });
             return destination;
         }
         const writeDirMode = writeOptions?.dirMode ?? dirMode;
+        const writeMode = writeOptions?.mode ?? mode;
+        const writeDurable = writeOptions?.durable ?? durable;
         const scopedRoot = await openWritableStoreRoot({
             rootDir,
             dirMode: writeDirMode,
@@ -146,7 +124,8 @@ export function fileStore(options) {
         await ensureParentInRoot(scopedRoot, safeRelativePath, writeDirMode);
         await scopedRoot.write(safeRelativePath, content, {
             mkdir: false,
-            mode: writeOptions?.mode ?? mode,
+            mode: writeMode,
+            durable: writeDurable,
         });
         return destination;
     }
@@ -161,6 +140,9 @@ export function fileStore(options) {
             const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
             const limit = configuredLimit ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
             if (privateMode) {
+                const writeDurable = writeOptions?.durable ?? durable;
+                const writeDirMode = writeOptions?.dirMode ?? dirMode;
+                const writeMode = writeOptions?.mode ?? mode;
                 const chunks = [];
                 let total = 0;
                 for await (const chunk of stream) {
@@ -173,25 +155,30 @@ export function fileStore(options) {
                     rootDir,
                     filePath: destination,
                     content: Buffer.concat(chunks),
-                    dirMode: writeOptions?.dirMode ?? dirMode,
-                    mode: writeOptions?.mode ?? mode,
+                    durable: writeDurable,
+                    dirMode: writeDirMode,
+                    mode: writeMode,
                 });
                 return destination;
             }
+            const writeMode = writeOptions?.mode ?? mode;
+            const writeDurable = writeOptions?.durable ?? durable;
+            const writeDirMode = writeOptions?.dirMode ?? dirMode;
             const staged = await writeStreamToTempSource({
                 stream,
                 maxBytes: limit,
-                mode: writeOptions?.mode ?? mode,
+                mode: writeMode,
             });
             try {
                 await copyIntoRoot({
                     rootDir,
                     relativePath: safeRelativePath,
                     sourcePath: staged.path,
+                    durable: writeDurable,
                     maxBytes: limit,
-                    mode: writeOptions?.mode ?? mode,
+                    mode: writeMode,
                     tempPrefix: writeOptions?.tempPrefix,
-                    dirMode: writeOptions?.dirMode ?? dirMode,
+                    dirMode: writeDirMode,
                 });
             }
             finally {
@@ -202,16 +189,25 @@ export function fileStore(options) {
         copyIn: async (relativePath, sourcePath, writeOptions) => {
             const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
             if (privateMode) {
+                const policy = writeOptions == null
+                    ? undefined
+                    : {
+                        maxBytes: configuredLimit,
+                        durable: writeOptions?.durable,
+                        dirMode: writeOptions?.dirMode,
+                        mode: writeOptions?.mode,
+                    };
                 const buffer = await readFileStoreCopySource({
                     sourcePath,
                     maxBytes: configuredLimit ?? DEFAULT_ROOT_MAX_BYTES,
                 });
-                return await write(relativePath, buffer, writeOptions);
+                return await write(relativePath, buffer, policy);
             }
             return await copyIntoRoot({
                 rootDir,
                 relativePath,
                 sourcePath,
+                durable: writeOptions?.durable ?? durable,
                 dirMode: writeOptions?.dirMode ?? dirMode,
                 maxBytes: configuredLimit,
                 mode: writeOptions?.mode ?? mode,
@@ -259,8 +255,10 @@ export function fileStore(options) {
         exists: async (relativePath) => await (await openRoot()).exists(assertRelativePath(relativePath)),
         writeText: async (relativePath, data, writeOptions) => await write(relativePath, data, writeOptions),
         writeJson: async (relativePath, data, writeOptions) => {
+            const trailingNewline = writeOptions?.trailingNewline;
+            const policy = snapshotWriteOptions(writeOptions, privateMode);
             const json = stringifyJsonDocument(data, null, 2);
-            return await write(relativePath, writeOptions?.trailingNewline === false ? json : `${json}\n`, writeOptions);
+            return await write(relativePath, trailingNewline === false ? json : `${json}\n`, policy);
         },
         json: (relativePath, jsonOptions) => {
             const filePath = resolveStorePath(rootDir, relativePath);
@@ -283,7 +281,7 @@ export function fileStore(options) {
                 readRequired: async () => await (await openRoot()).readJson(assertRelativePath(relativePath)),
                 write: async (value, options) => {
                     const json = stringifyJsonDocument(value, null, 2);
-                    await write(relativePath, options?.trailingNewline === false ? json : `${json}\n`);
+                    await write(relativePath, options?.trailingNewline === false ? json : `${json}\n`, { durable: options?.durable });
                 },
             }, jsonOptions);
         },
@@ -293,10 +291,14 @@ export function fileStore(options) {
     };
 }
 export function fileStoreSync(options) {
-    const rootDir = path.resolve(options.rootDir);
+    const rootDirInput = options.rootDir;
+    assertNoWindowsPathAlias(rootDirInput, "filesystem", "store root uses a Windows filesystem namespace alias");
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+    assertNoWindowsPathAlias(rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
     const privateMode = options.private ?? false;
     const dirMode = options.dirMode ?? 0o700;
     const mode = options.mode ?? 0o600;
+    const durable = options.durable ?? true;
     const maxBytes = normalizeMaxBytes(options.maxBytes);
     function write(relativePath, data, writeOptions) {
         const destination = resolveStorePath(rootDir, relativePath);
@@ -308,14 +310,16 @@ export function fileStoreSync(options) {
             filePath: destination,
             content,
             privateMode,
+            durable: writeOptions?.durable ?? durable,
             dirMode: writeOptions?.dirMode ?? dirMode,
             mode: writeOptions?.mode ?? mode,
         });
     }
+    let readTextIfExists;
     return {
         rootDir,
         path: (relativePath) => resolveStorePath(rootDir, relativePath),
-        readTextIfExists: (relativePath, readOptions) => {
+        readTextIfExists: readTextIfExists = (relativePath, readOptions) => {
             const limit = normalizeMaxBytes(readOptions?.maxBytes, { defaultValue: maxBytes });
             const targetPath = resolveStorePath(rootDir, relativePath);
             const opened = openRootFileSync({
@@ -343,15 +347,16 @@ export function fileStoreSync(options) {
             }
         },
         readJsonIfExists: (relativePath, readOptions) => {
-            const raw = fileStoreSync({ rootDir, private: privateMode, dirMode, mode, maxBytes })
-                .readTextIfExists(relativePath, readOptions);
+            const raw = readTextIfExists(relativePath, readOptions);
             return raw === null ? null : JSON.parse(raw);
         },
         write,
         writeText: (relativePath, data, writeOptions) => write(relativePath, data, writeOptions),
         writeJson: (relativePath, data, writeOptions) => {
+            const trailingNewline = writeOptions?.trailingNewline;
+            const policy = snapshotWriteOptions(writeOptions);
             const json = stringifyJsonDocument(data, null, 2);
-            return write(relativePath, writeOptions?.trailingNewline === false ? json : `${json}\n`, writeOptions);
+            return write(relativePath, trailingNewline === false ? json : `${json}\n`, policy);
         },
     };
 }

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

@@ -2,4 +2,3 @@ import fs from "node:fs";
 import type { FileHandle } from "node:fs/promises";
 export declare function syncFileBestEffort(handle: Pick<FileHandle, "sync">): Promise<void>;
 export declare function syncFileBestEffortSync(fd: number, fsModule?: Pick<typeof fs, "fsyncSync">): void;
-//# sourceMappingURL=file-sync.d.ts.map

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

@@ -1,3 +1,4 @@
+export declare function suffixWindowsReservedDeviceName(fileName: string): string;
 /** Keeps short names exact and trims only the filename tail of a composite temp name. */
 export declare function fitFileNameToPortableComponent(params: {
     prefix: string;
@@ -5,4 +6,3 @@ export declare function fitFileNameToPortableComponent(params: {
     suffix: string;
 }): string;
 export declare function sanitizeUntrustedFileName(fileName: string, fallbackName: string): string;
-//# sourceMappingURL=filename.d.ts.map