@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/pinned-mutation-shared-route.d.ts

@@ -0,0 +1,24 @@
+import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { RootBoundaryIdentity } from "./root-boundary.js";
+import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
+export type ExactRootIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+type SharedMutationPolicy = Readonly<{
+    denyMutations?: DenyMutationPolicy;
+    mutationSymlinks?: MutationSymlinkPolicy;
+}>;
+export declare function ordinaryWindowsSegments(relativePath: string): boolean;
+export declare function ordinarySharedAbsoluteInsideRoot(rootReal: string, candidatePath: string, rootIdentity: ExactRootIdentity): boolean;
+export declare function simpleSharedRoute(params: {
+    rootReal: string;
+    rootIdentity?: RootBoundaryIdentity;
+    originalPath?: string;
+    selectedTarget: string;
+    policy: SharedMutationPolicy;
+}): {
+    route: string;
+    rootIdentity: ExactRootIdentity;
+} | undefined;
+export {};

package/node_modules/@openclaw/fs-safe/dist/pinned-mutation-shared-route.js

@@ -0,0 +1,70 @@
+import path from "node:path";
+import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { isSafePathSegment } from "./safe-path-segment.js";
+function windowsReservedDeviceSegment(segment) {
+    const extension = segment.indexOf(".");
+    const stem = segment.slice(0, extension < 0 ? segment.length : extension).toUpperCase();
+    return WINDOWS_RESERVED_DEVICE_NAMES.has(stem);
+}
+export function ordinaryWindowsSegments(relativePath) {
+    if (relativePath === "" || relativePath.includes("/") || relativePath.includes("\0"))
+        return false;
+    const segments = relativePath.split("\\");
+    return segments.every((segment) => isSafePathSegment(segment, { allowDotPrefix: true }) &&
+        !segment.endsWith(".") && !segment.endsWith(" ") &&
+        !windowsReservedDeviceSegment(segment));
+}
+function ordinaryPosixSegments(relativePath) {
+    return relativePath !== "" && !relativePath.includes("\\") &&
+        relativePath.split("/").every((segment) => isSafePathSegment(segment, { allowDotPrefix: true }));
+}
+function exactNonzeroRootIdentity(identity) {
+    return typeof identity?.dev === "bigint" && typeof identity.ino === "bigint" &&
+        identity.dev !== 0n && identity.ino !== 0n
+        ? Object.freeze({ dev: identity.dev, ino: identity.ino })
+        : undefined;
+}
+export function ordinarySharedAbsoluteInsideRoot(rootReal, candidatePath, rootIdentity) {
+    if (!path.isAbsolute(candidatePath) || candidatePath.includes("\0") ||
+        path.resolve(candidatePath) !== candidatePath ||
+        (process.platform === "win32"
+            ? candidatePath.startsWith("\\\\") || candidatePath.includes("/")
+            : candidatePath.includes("\\")))
+        return false;
+    const admitted = admitPathInsideRoot({
+        rootPath: rootReal,
+        candidatePath,
+        rootIdentity,
+    });
+    return admitted?.admission === "exact" && admitted.path === candidatePath &&
+        (admitted.relativePath === "" || (process.platform === "win32"
+            ? ordinaryWindowsSegments(admitted.relativePath)
+            : ordinaryPosixSegments(admitted.relativePath)));
+}
+export function simpleSharedRoute(params) {
+    if (process.versions.bun ||
+        params.policy.mutationSymlinks !== "reject" || !params.originalPath ||
+        params.originalPath.startsWith("~") || path.isAbsolute(params.originalPath) ||
+        !(process.platform === "win32"
+            ? ordinaryWindowsSegments(params.originalPath) &&
+                !params.rootReal.startsWith("\\\\") && !params.rootReal.includes("/")
+            : ordinaryPosixSegments(params.originalPath) && !params.rootReal.includes("\\")) ||
+        path.resolve(params.rootReal) !== params.rootReal)
+        return undefined;
+    const rootIdentity = exactNonzeroRootIdentity(params.rootIdentity);
+    if (!rootIdentity)
+        return undefined;
+    const route = path.resolve(params.rootReal, params.originalPath);
+    if (route !== params.selectedTarget ||
+        !ordinarySharedAbsoluteInsideRoot(params.rootReal, route, rootIdentity))
+        return undefined;
+    const policyEntries = [
+        ...(params.policy.denyMutations?.paths ?? []),
+        ...(params.policy.denyMutations?.prefixes ?? []),
+    ];
+    if (policyEntries.some((entry) => entry !== path.resolve(entry) ||
+        !ordinarySharedAbsoluteInsideRoot(params.rootReal, entry, rootIdentity)))
+        return undefined;
+    return { route, rootIdentity };
+}

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

@@ -5,12 +5,18 @@ export type PinnedOpenSyncResult = {
     path: string;
     fd: number;
     stat: fs.Stats;
+    identity: fs.BigIntStats;
 } | {
     ok: false;
     reason: PinnedOpenSyncFailureReason;
     error?: unknown;
 };
 export type PinnedOpenSyncAllowedType = "file" | "directory";
+export type PinnedOpenSyncFinalAdmission = (params: {
+    path: string;
+    preRealpathIdentity: fs.BigIntStats;
+    descriptorIdentity: fs.BigIntStats;
+}) => string;
 export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;
 export declare function openPinnedFileSync(params: {
     filePath: string;
@@ -20,5 +26,5 @@ export declare function openPinnedFileSync(params: {
     maxBytes?: number;
     allowedType?: PinnedOpenSyncAllowedType;
     ioFs?: PinnedOpenSyncFs;
+    finalAdmission?: PinnedOpenSyncFinalAdmission;
 }): PinnedOpenSyncResult;
-//# sourceMappingURL=pinned-open.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/pinned-open.js

@@ -3,47 +3,67 @@ import { isUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
 function isExpectedPathError(error) {
     const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
     return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
 }
 export function openPinnedFileSync(params) {
+    const filePath = params.filePath;
+    const resolvedPath = params.resolvedPath;
     const ioFs = params.ioFs ?? fs;
     const allowedType = params.allowedType ?? "file";
+    const rejectPathSymlink = params.rejectPathSymlink === true;
+    const statPolicy = {
+        rejectHardlinks: params.rejectHardlinks,
+        maxBytes: params.maxBytes,
+    };
     const openReadFlags = resolveReadOpenFlags({ constants: ioFs.constants });
     let fd = null;
     try {
-        if (isUnsafeDeviceReadPath(params.filePath)) {
+        assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
+        if (resolvedPath !== undefined) {
+            assertNoWindowsPathAlias(resolvedPath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
+        }
+        if (isUnsafeDeviceReadPath(filePath)) {
             return { ok: false, reason: "validation" };
         }
-        if (params.rejectPathSymlink) {
-            const candidateStat = ioFs.lstatSync(params.filePath);
+        if (rejectPathSymlink) {
+            const candidateStat = ioFs.lstatSync(filePath);
             if (candidateStat.isSymbolicLink()) {
                 return { ok: false, reason: "validation" };
             }
         }
-        const realPath = params.resolvedPath ?? ioFs.realpathSync(params.filePath);
+        const realPath = resolvedPath ??
+            (ioFs === fs ? realpathSync(filePath) : ioFs.realpathSync(filePath));
+        assertNoWindowsPathAlias(realPath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
         if (isUnsafeDeviceReadPath(realPath)) {
             return { ok: false, reason: "validation" };
         }
         const preOpenStat = inspectFileIdentitySync(() => {
             const stat = ioFs.lstatSync(realPath, { bigint: true });
-            assertAllowedStat(stat, allowedType, params);
+            assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         });
         fd = ioFs.openSync(realPath, openReadFlags);
         const openedStat = ioFs.fstatSync(fd);
         const identity = inspectFileIdentitySync(() => {
             const stat = ioFs.fstatSync(fd, { bigint: true });
-            assertAllowedStat(stat, allowedType, params);
+            assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, preOpenStat);
-        inspectFileIdentitySync(() => {
+        const pathIdentity = inspectFileIdentitySync(() => {
             const stat = ioFs.lstatSync(realPath, { bigint: true });
-            assertAllowedStat(stat, allowedType, params);
+            assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, identity);
-        const opened = { ok: true, path: realPath, fd, stat: openedStat };
+        const admittedPath = params.finalAdmission?.({
+            path: realPath,
+            preRealpathIdentity: pathIdentity,
+            descriptorIdentity: identity,
+        }) ?? realPath;
+        const opened = { ok: true, path: admittedPath, fd, stat: openedStat, identity };
         fd = null;
         return opened;
     }
@@ -57,7 +77,12 @@ export function openPinnedFileSync(params) {
     }
     finally {
         if (fd !== null) {
-            ioFs.closeSync(fd);
+            try {
+                ioFs.closeSync(fd);
+            }
+            catch {
+                // Preserve the failed admission result; success transfers fd above.
+            }
         }
     }
 }

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

@@ -1,2 +1 @@
-export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
-//# sourceMappingURL=pinned-operation.d.ts.map
+export declare function validatePinnedRelativePath(relativePath: unknown): void;

package/node_modules/@openclaw/fs-safe/dist/pinned-operation.js

@@ -1,19 +1,7 @@
 import { FsSafeError } from "./errors.js";
-export function validatePinnedOperationPayload(payload) {
-    if (typeof payload.relativePath === "string") {
-        validatePinnedRelativePath(payload.relativePath);
-    }
-    if (typeof payload.relativeParentPath === "string") {
-        validatePinnedRelativePath(payload.relativeParentPath);
-    }
-    if (typeof payload.from === "string") {
-        validatePinnedRelativePath(payload.from);
-    }
-    if (typeof payload.to === "string") {
-        validatePinnedRelativePath(payload.to);
-    }
-}
-function validatePinnedRelativePath(relativePath) {
+export function validatePinnedRelativePath(relativePath) {
+    if (typeof relativePath !== "string")
+        return;
     if (relativePath.length === 0 || relativePath === ".") {
         return;
     }
@@ -21,13 +9,12 @@ function validatePinnedRelativePath(relativePath) {
         throw new FsSafeError("invalid-path", "relative path contains a NUL byte");
     }
     if (relativePath.startsWith("/") ||
-        relativePath.startsWith("//") ||
         relativePath === ".." ||
         relativePath.startsWith("../") ||
         relativePath.startsWith("..\\")) {
         throw new FsSafeError("invalid-path", "relative path must not escape root");
     }
-    for (const segment of relativePath.split("/")) {
+    for (const segment of relativePath.split(process.platform === "win32" ? /[\\/]/ : "/")) {
         if (segment === "..") {
             throw new FsSafeError("invalid-path", "relative path must not contain '..'");
         }

package/node_modules/@openclaw/fs-safe/dist/pinned-write-input.d.ts

@@ -0,0 +1,3 @@
+import type { FileHandle } from "node:fs/promises";
+import type { PinnedWriteInput } from "./pinned-write-types.js";
+export declare function writePinnedInput(target: FileHandle | number, input: PinnedWriteInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/pinned-write-input.js

@@ -0,0 +1,35 @@
+import { types } from "node:util";
+import { snapshotByteView } from "./byte-view.js";
+import { writeCopyFileToFd } from "./copy-file-input.js";
+import { FsSafeError } from "./errors.js";
+import { writeAllToFile } from "./write-file-handle.js";
+const isUint8Array = types.isUint8Array;
+function streamChunkBytes(chunk) {
+    if (Buffer.isBuffer(chunk))
+        return chunk;
+    if (!isUint8Array(chunk))
+        return Buffer.from(chunk);
+    return snapshotByteView(chunk);
+}
+export async function writePinnedInput(target, input, maxBytes, assertBeforeMutation) {
+    if (input.kind === "file") {
+        await writeCopyFileToFd(typeof target === "number" ? target : target.fd, input, maxBytes, assertBeforeMutation);
+        return;
+    }
+    let bytes = 0;
+    const write = async (data) => {
+        bytes += data.byteLength;
+        if (maxBytes !== undefined && bytes > maxBytes) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
+        }
+        await writeAllToFile(target, data, { assertBeforeMutation });
+    };
+    if (input.kind === "buffer") {
+        await write(typeof input.data === "string" ? Buffer.from(input.data, input.encoding ?? "utf8") : input.data);
+    }
+    else {
+        for await (const chunk of input.stream) {
+            await write(streamChunkBytes(chunk));
+        }
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/pinned-write-mode.d.ts

@@ -0,0 +1,4 @@
+import type { FileHandle } from "node:fs/promises";
+export declare function assertPinnedWriteMode(fd: number, mode: number, privateCreation?: boolean): void;
+export declare function preparePinnedWriteMode(handle: FileHandle, createdMode: number, assertBeforeMutation?: () => void, privateCreation?: boolean): Promise<(() => void) | undefined>;
+export declare function pinnedWriteModeAssertion(fd: number, mode: number, assertBeforeMutation?: () => void, privateCreation?: boolean): () => void;

package/node_modules/@openclaw/fs-safe/dist/pinned-write-mode.js

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertPrivateCreationFile } from "./creation-boundary.js";
+export function assertPinnedWriteMode(fd, mode, privateCreation = false) {
+    if (process.platform === "win32")
+        return;
+    const stat = fs.fstatSync(fd, { bigint: true });
+    if (privateCreation)
+        assertPrivateCreationFile(stat, fd);
+    if (Number(stat.mode & 4095n) !== mode) {
+        throw new FsSafeError("insecure-permissions", "filesystem did not enforce the requested file mode");
+    }
+}
+export async function preparePinnedWriteMode(handle, createdMode, assertBeforeMutation, privateCreation = false) {
+    if (process.platform === "win32")
+        return assertBeforeMutation;
+    assertSynchronousCallbackResult(assertBeforeMutation?.(), "assertBeforeMutation");
+    if (createdMode !== 0o600) {
+        if (privateCreation)
+            assertPrivateCreationFile(fs.fstatSync(handle.fd, { bigint: true }), handle.fd);
+        await handle.chmod(0o600);
+    }
+    return pinnedWriteModeAssertion(handle.fd, 0o600, assertBeforeMutation, privateCreation);
+}
+export function pinnedWriteModeAssertion(fd, mode, assertBeforeMutation, privateCreation = false) {
+    return () => {
+        assertSynchronousCallbackResult(assertBeforeMutation?.(), "assertBeforeMutation");
+        assertPinnedWriteMode(fd, mode, privateCreation);
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/pinned-write-staged.d.ts

@@ -0,0 +1,5 @@
+import { type BigIntStats } from "node:fs";
+import type { AsyncDirectoryGuard } from "./directory-guard.js";
+import { type FileIdentityStat } from "./file-identity.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
+export declare function runPinnedStagedWrite(params: PinnedWriteParams, parentPath: string, parentGuard: AsyncDirectoryGuard<BigIntStats>): Promise<FileIdentityStat>;

package/node_modules/@openclaw/fs-safe/dist/pinned-write-staged.js

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { createFileHandle } from "./create.js";
+import { hasPreservedCreationArtifacts, creationAdmissionFromParent } from "./creation-boundary.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity, sha256Hex } from "./file-identity.js";
+import { syncFileBestEffort } from "./file-sync.js";
+import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
+import { writePinnedInput } from "./pinned-write-input.js";
+import { assertPinnedWriteMode, pinnedWriteModeAssertion, preparePinnedWriteMode } from "./pinned-write-mode.js";
+import { publishCopyStage } from "./publish-copy-stage.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { createStagedFileReceipt, settleStagedFile } from "./staged-file-settlement.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
+    const verifyPosixMode = process.platform !== "win32" &&
+        (params.verifyPosixMode === true || params.private === true);
+    const targetPath = path.join(parentPath, params.basename);
+    // Private staging must not consume the destination basename's filename budget.
+    const tempPath = path.join(parentPath, `.fs-safe-${randomUUID()}.tmp`);
+    const tempFlags = fsSync.constants.O_WRONLY |
+        fsSync.constants.O_CREAT |
+        fsSync.constants.O_EXCL |
+        (process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
+            ? fsSync.constants.O_NOFOLLOW
+            : 0);
+    let handle;
+    let tempStat;
+    let tempIdentity;
+    let readHandle;
+    let renamed = false;
+    const completeCreate = params.overwrite === false && params.input.kind !== "file" && params.input.stageBeforePublish === true;
+    let receipt;
+    let publication = Object.freeze({ status: "not-published" });
+    let phase = "prepare";
+    let failure;
+    try {
+        params.assertBeforeMutation?.();
+        handle = params.private
+            ? await createFileHandle(tempPath, {
+                private: true, mode: 0o600, assertBeforeMutation: params.assertBeforeMutation,
+            }, creationAdmissionFromParent(parentGuard))
+            : await fs.open(tempPath, tempFlags, verifyPosixMode ? 0o600 : params.mode);
+        let verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
+        tempIdentity = verificationIdentity;
+        let assertBeforeMutation = params.assertBeforeMutation;
+        const assertBeforeWrite = verifyPosixMode
+            ? await preparePinnedWriteMode(handle, Number(tempIdentity.mode & 4095n), assertBeforeMutation, params.private)
+            : assertBeforeMutation;
+        if (verifyPosixMode)
+            assertPinnedWriteMode(handle.fd, 0o600, params.private);
+        await writePinnedInput(handle, params.input, params.maxBytes, assertBeforeWrite);
+        if (verifyPosixMode)
+            assertPinnedWriteMode(handle.fd, 0o600, params.private);
+        tempStat = fsSync.fstatSync(handle.fd);
+        const tempPathStat = fsSync.lstatSync(tempPath);
+        if (tempPathStat.isSymbolicLink() || !sameFileIdentity(tempPathStat, tempStat)) {
+            throw new FsSafeError("path-mismatch", "fallback temp path changed during write");
+        }
+        const expectedTempStat = tempStat;
+        await handle.chmod(params.mode);
+        if (verifyPosixMode) {
+            assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            assertBeforeMutation = pinnedWriteModeAssertion(handle.fd, params.mode, params.assertBeforeMutation, params.private);
+        }
+        if (params.sync !== false) {
+            if (params.strictFileSync)
+                await handle.sync();
+            else
+                await syncFileBestEffort(handle);
+        }
+        if (params.input.kind === "file")
+            await params.input.verifySource();
+        if (completeCreate) {
+            receipt = createStagedFileReceipt(Object.freeze({
+                path: parentGuard.dir,
+                realPath: parentGuard.realPath,
+                identity: Object.freeze({ dev: parentGuard.stat.dev, ino: parentGuard.stat.ino }),
+            }), path.basename(tempPath), fsSync.fstatSync(handle.fd, { bigint: true }));
+        }
+        let verifiedIdentity = expectedTempStat;
+        phase = "publish";
+        await withAsyncDirectoryGuards([parentGuard], async () => {
+            assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
+            if (params.overwrite === false) {
+                publishCopyStage({
+                    temporaryPath: tempPath, targetPath, fd: handle.fd,
+                    identity: tempIdentity, parentGuard,
+                    assertBeforeMutation,
+                    onPublicationAttempt: () => {
+                        if (receipt)
+                            publication = Object.freeze({ status: "indeterminate", basename: params.basename, overwrite: false });
+                    },
+                    onPublished: (identity) => {
+                        renamed = true;
+                        if (receipt)
+                            publication = Object.freeze({ status: "published", staged: receipt, basename: params.basename, overwrite: false });
+                        params.onPublished?.(identity);
+                    },
+                });
+            }
+            else {
+                assertBeforeMutation?.();
+                await fs.rename(tempPath, targetPath);
+                renamed = true;
+                params.onPublished?.(verificationIdentity);
+            }
+            await getFsSafeTestHooks()?.afterPinnedWriteFallbackRename?.(targetPath);
+            if (params.sync !== false)
+                await syncDirectoryBestEffort(parentPath);
+            const targetStat = fsSync.lstatSync(targetPath);
+            if (targetStat.isSymbolicLink()) {
+                throw new FsSafeError("path-mismatch", "fallback target changed during write");
+            }
+            if (!sameFileIdentity(targetStat, expectedTempStat)) {
+                // On filesystems like rclone FUSE, rename(2) can give the destination a
+                // different inode from the source temp fd even with zero concurrency. The
+                // caller must ensure mutual exclusion before passing "verify-content";
+                // fall back to a content hash for this rename-boundary check only.
+                if (params.onRenameIdentityMismatch !== "verify-content") {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                if (params.input.kind !== "buffer") {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                const expectedHash = sha256Hex(params.input.data, params.input.encoding);
+                readHandle = await fs.open(targetPath, resolveReadOpenFlags());
+                const readHandleStat = fsSync.fstatSync(readHandle.fd, { bigint: true });
+                const actualHash = sha256Hex(await readHandle.readFile());
+                if (actualHash !== expectedHash) {
+                    throw new FsSafeError("path-mismatch", "fallback target changed during write");
+                }
+                // The content-verified destination, not the old temp inode, is now pinned.
+                verificationIdentity = readHandleStat;
+                // Preserve the helper's legacy numeric return facts, not the private proof.
+                verifiedIdentity = { dev: Number(readHandleStat.dev), ino: Number(readHandleStat.ino) };
+            }
+        });
+        await params.verifyPublished?.((readHandle ?? handle).fd, verificationIdentity, parentGuard);
+        if (verifyPosixMode)
+            assertPinnedWriteMode((readHandle ?? handle).fd, params.mode, params.private);
+        return { dev: verifiedIdentity.dev, ino: verifiedIdentity.ino };
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        const preservedPreparation = params.private && !handle && hasPreservedCreationArtifacts(failure?.error);
+        if (completeCreate || preservedPreparation) {
+            await settleStagedFile({
+                temporaryBasename: path.basename(tempPath), publication, phase, failure,
+                cleanup: async () => {
+                    if (preservedPreparation)
+                        return "preserved";
+                    if (publication.status === "indeterminate")
+                        return "preserved";
+                    if (renamed) {
+                        return failure?.error instanceof FsSafeError && failure.error.details?.cleanup === "failed"
+                            ? "failed" : "not-needed";
+                    }
+                    return handle ? await cleanupPinnedFilePath({
+                        pathname: tempPath, handle, identity: tempIdentity, parentGuard, throwOnCleanupError: true,
+                    }) : "not-needed";
+                },
+                close: [async () => { await readHandle?.close(); }, async () => { await handle?.close(); }],
+            });
+        }
+        else
+            try {
+                if (!renamed && handle) {
+                    await cleanupPinnedFilePath({ pathname: tempPath, handle, identity: tempIdentity, parentGuard });
+                }
+            }
+            finally {
+                await readHandle?.close().catch(() => undefined);
+                await handle?.close().catch(() => undefined);
+            }
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/pinned-write-types.d.ts

@@ -0,0 +1,68 @@
+import type { CopyFileInput } from "./copy-file-input.js";
+import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+export type PinnedWriteInput = {
+    kind: "buffer";
+    data: string | Buffer;
+    encoding?: BufferEncoding;
+    stageBeforePublish?: boolean;
+} | {
+    kind: "stream";
+    stream: AsyncIterable<Uint8Array | string>;
+    stageBeforePublish?: boolean;
+} | CopyFileInput;
+export type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
+export type PublishedWriteIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type PinnedMutationAdmissionReceipt = Readonly<object>;
+export type PinnedMutationAuthorizationToken = Readonly<object>;
+export type PinnedCreatedDirectoryReceipt = Readonly<{
+    admission: PinnedMutationAdmissionReceipt;
+    parent: MutationDirectoryObservation;
+    child: MutationDirectoryObservation;
+}>;
+export type PinnedMutationParentRequest = {
+    targetPath: string;
+    mutationPath: string;
+    phase: "parent" | "parent-create";
+};
+export type PinnedMutationParentWalkSession = Readonly<{
+    retainedTargetPath: string;
+    tryAuthorizeAtParent(request: Readonly<PinnedMutationParentRequest>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<PinnedMutationParentRequest>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    advanceCreatedDirectory(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
+    dispose(): void;
+}>;
+export type PinnedWriteMutationAdmission = Readonly<{
+    rejectParentSymlinks: boolean;
+    beginParentWalk?(): string | undefined;
+    beginSharedParentWalk?(): PinnedMutationParentWalkSession | undefined;
+    beginNativeParentWalk?(): PinnedMutationParentWalkSession | undefined;
+    tryAuthorizeAtParent?(request: Readonly<PinnedMutationParentRequest>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<PinnedMutationParentRequest>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    advanceCreatedDirectory?(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
+}>;
+export type PinnedWriteParams = {
+    rootPath: string;
+    relativeParentPath: string;
+    basename: string;
+    mkdir: boolean;
+    mode: number;
+    private?: boolean;
+    verifyPosixMode?: boolean;
+    sync?: boolean;
+    strictFileSync?: boolean;
+    overwrite?: boolean;
+    assertBeforeMutation?: () => void;
+    rejectFinalSymlink?: boolean;
+    maxBytes?: number;
+    input: PinnedWriteInput;
+    rootIdentity?: FileIdentityStat;
+    mutationAdmission?: PinnedWriteMutationAdmission;
+    onRenameIdentityMismatch?: "verify-content";
+    onPublished?: (identity: PublishedWriteIdentity) => void;
+    verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
+};

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

@@ -1,36 +1,12 @@
-import type { Readable } from "node:stream";
-import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
-export type PinnedWriteInput = {
-    kind: "buffer";
-    data: string | Buffer;
-    encoding?: BufferEncoding;
-} | {
-    kind: "stream";
-    stream: Readable;
-};
-export type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
-export type PublishedWriteIdentity = Readonly<{
-    dev: bigint;
-    ino: bigint;
-}>;
-export type PinnedWriteParams = {
-    rootPath: string;
-    relativeParentPath: string;
-    basename: string;
-    mkdir: boolean;
-    mode: number;
-    sync?: boolean;
-    overwrite?: boolean;
-    maxBytes?: number;
-    input: PinnedWriteInput;
-    rootIdentity?: FileIdentityStat;
-    onRenameIdentityMismatch?: "verify-content";
-    verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
-};
+import type { PinnedWriteParams, RenameIdentityPolicy } from "./pinned-write-types.js";
 export declare function runPinnedWriteHelper(params: PinnedWriteParams): Promise<FileIdentityStat>;
 export declare function runPinnedWriteWithRenamePolicy(params: PinnedWriteParams & {
     targetPath: string;
     renameIdentity?: RenameIdentityPolicy;
 }): Promise<FileIdentityStat>;
-//# sourceMappingURL=pinned-write.d.ts.map
+export declare function withPinnedWriteRenameIdentityLock<T>(params: {
+    rootPath: string;
+    targetPath: string;
+    relativeTargetPath: string;
+}, run: () => Promise<T>): Promise<T>;