@openclaw/openshell-sandbox 2026.9.5 → 2026.9.6

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

@@ -6,6 +6,7 @@ export type PinnedWriteInput = {
     kind: "buffer";
     data: string | Buffer;
     encoding?: BufferEncoding;
+    stageBeforePublish?: boolean;
 } | {
     kind: "stream";
     stream: AsyncIterable<Uint8Array | string>;
@@ -23,18 +24,15 @@ export type PinnedCreatedDirectoryReceipt = Readonly<{
     parent: MutationDirectoryObservation;
     child: MutationDirectoryObservation;
 }>;
+export type PinnedMutationParentRequest = {
+    targetPath: string;
+    mutationPath: string;
+    phase: "parent" | "parent-create";
+};
 export type PinnedMutationParentWalkSession = Readonly<{
     retainedTargetPath: string;
-    tryAuthorizeAtParent(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
-    authorize(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    tryAuthorizeAtParent(request: Readonly<PinnedMutationParentRequest>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<PinnedMutationParentRequest>): Promise<PinnedMutationAdmissionReceipt | undefined>;
     advanceCreatedDirectory(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
     dispose(): void;
 }>;
@@ -42,16 +40,9 @@ export type PinnedWriteMutationAdmission = Readonly<{
     rejectParentSymlinks: boolean;
     beginParentWalk?(): string | undefined;
     beginSharedParentWalk?(): PinnedMutationParentWalkSession | undefined;
-    tryAuthorizeAtParent?(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
-    authorize(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>): Promise<PinnedMutationAdmissionReceipt | 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 = {
@@ -60,7 +51,10 @@ export type PinnedWriteParams = {
     basename: string;
     mkdir: boolean;
     mode: number;
+    private?: boolean;
+    verifyPosixMode?: boolean;
     sync?: boolean;
+    strictFileSync?: boolean;
     overwrite?: boolean;
     assertBeforeMutation?: () => void;
     rejectFinalSymlink?: boolean;
@@ -72,4 +66,3 @@ export type PinnedWriteParams = {
     onPublished?: (identity: PublishedWriteIdentity) => void;
     verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
 };
-//# sourceMappingURL=pinned-write-types.d.ts.map

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

@@ -1,6 +1,5 @@
 import type { FileIdentityStat } from "./file-identity.js";
 import type { PinnedWriteParams, RenameIdentityPolicy } from "./pinned-write-types.js";
-export type { PinnedWriteInput, RenameIdentityPolicy, PublishedWriteIdentity, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken, PinnedCreatedDirectoryReceipt, PinnedMutationParentWalkSession, PinnedWriteMutationAdmission, PinnedWriteParams, } from "./pinned-write-types.js";
 export declare function runPinnedWriteHelper(params: PinnedWriteParams): Promise<FileIdentityStat>;
 export declare function runPinnedWriteWithRenamePolicy(params: PinnedWriteParams & {
     targetPath: string;
@@ -11,4 +10,3 @@ export declare function withPinnedWriteRenameIdentityLock<T>(params: {
     targetPath: string;
     relativeTargetPath: string;
 }, run: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=pinned-write.d.ts.map

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

@@ -1,32 +1,27 @@
 import { syncFileBestEffort } from "./file-sync.js";
-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 { creationAdmissionFromParent } from "./creation-boundary.js";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
-import { sameFileIdentity, sha256Hex } from "./file-identity.js";
+import { sha256Hex } from "./file-identity.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { runPinnedWriteNative } from "./native-pinned-write.js";
 import { getNativeBinding } from "./native.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
-import { resolveReadOpenFlags } from "./read-open-flags.js";
-import { cleanupPinnedFilePath } from "./replace-file-temp-owner.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { withSidecarLock } from "./sidecar-lock.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { writeAllToFile } from "./write-file-handle.js";
+import { writePinnedInput } from "./pinned-write-input.js";
+import { assertPinnedWriteMode, preparePinnedWriteMode } from "./pinned-write-mode.js";
+import { runPinnedStagedWrite } from "./pinned-write-staged.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
-import { writeCopyFileToFd } from "./copy-file-input.js";
-import { publishCopyStage } from "./publish-copy-stage.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-function byteLength(input, encoding) {
-    return typeof input === "string"
-        ? Buffer.byteLength(input, encoding ?? "utf8")
-        : input.byteLength;
-}
 function assertSafeBasename(basename) {
     if (!basename ||
         basename === "." ||
@@ -37,24 +32,10 @@ function assertSafeBasename(basename) {
         throw new FsSafeError("invalid-path", "invalid target path");
     }
 }
-function assertWithinMaxBytes(bytes, maxBytes) {
-    if (maxBytes !== undefined && bytes > maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
-    }
-}
 function fastParentGuardDeopt(error) {
     return error instanceof FsSafeError &&
         (error.code === "path-mismatch" || error.code === "not-file");
 }
-async function writeStreamToHandle(stream, handle, maxBytes, assertBeforeMutation) {
-    let bytes = 0;
-    for await (const chunk of stream) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += buffer.byteLength;
-        assertWithinMaxBytes(bytes, maxBytes);
-        await writeAllToFile(handle, buffer, { assertBeforeMutation });
-    }
-}
 const PINNED_WRITE_SNAPSHOT_KEYS = [
     "rootPath", "relativeParentPath", "basename", "maxBytes", "rootIdentity",
 ];
@@ -90,9 +71,7 @@ export async function runPinnedWriteHelper(params) {
         rootIdentity,
     };
     assertSafeBasename(normalizedParams.basename);
-    validatePinnedOperationPayload({
-        relativeParentPath: normalizedParams.relativeParentPath,
-    });
+    validatePinnedRelativePath(normalizedParams.relativeParentPath);
     assertNoWindowsPathAlias(normalizedParams.rootPath, "filesystem", "pinned write root uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(normalizedParams.relativeParentPath, "relative", "pinned write parent uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(normalizedParams.basename, "relative", "pinned write basename uses a Windows filesystem namespace alias");
@@ -142,6 +121,8 @@ export async function withPinnedWriteRenameIdentityLock(params, run) {
     }, run);
 }
 async function runPinnedWriteFallback(params) {
+    const verifyPosixMode = process.platform !== "win32" &&
+        (params.verifyPosixMode === true || params.private === true);
     const exactRoot = typeof params.rootIdentity?.dev === "bigint" && typeof params.rootIdentity.ino === "bigint"
         ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
     const mutationAdmission = params.mutationAdmission;
@@ -246,15 +227,19 @@ async function runPinnedWriteFallback(params) {
         }));
         await assertAsyncDirectoryGuard(parentGuard);
     }
-    if (params.overwrite === false && (params.input.kind === "buffer" ||
-        (params.input.kind === "stream" && !params.input.stageBeforePublish))) {
+    if (params.overwrite === false && params.input.kind !== "file" && !params.input.stageBeforePublish) {
         const assertBeforeMutation = () => {
             assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
             params.assertBeforeMutation?.();
         };
         const handle = await withAsyncDirectoryGuards([parentGuard], async () => {
             assertBeforeMutation();
-            return await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode);
+            if (params.private) {
+                return await createFileHandle(targetPath, {
+                    private: true, mode: 0o600, assertBeforeMutation,
+                }, creationAdmissionFromParent(parentGuard));
+            }
+            return await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, verifyPosixMode ? 0o600 : params.mode);
         }, {
             onPostGuardFailure: async (openedHandle) => {
                 // The parent failed verification, so targetPath may now resolve
@@ -263,29 +248,38 @@ async function runPinnedWriteFallback(params) {
             },
         });
         let created = true;
+        let completed = false;
         let createdIdentity;
         try {
             const verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
             createdIdentity = verificationIdentity;
-            if (params.input.kind === "buffer") {
-                assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
-                await writeAllToFile(handle, params.input.data, {
-                    encoding: params.input.encoding, assertBeforeMutation,
-                });
-            }
-            else {
-                await writeStreamToHandle(params.input.stream, handle, params.maxBytes, assertBeforeMutation);
-            }
+            const assertBeforeWrite = verifyPosixMode
+                ? await preparePinnedWriteMode(handle, Number(createdIdentity.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);
             // Content writes may clear set-ID bits; finalize them through the owned fd.
             await handle.chmod(params.mode);
-            if (params.sync !== false)
-                await syncFileBestEffort(handle);
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            if (params.sync !== false) {
+                if (params.strictFileSync)
+                    await handle.sync();
+                else
+                    await syncFileBestEffort(handle);
+            }
             const stat = fsSync.fstatSync(handle.fd);
             if (params.sync !== false)
                 await syncDirectoryBestEffort(parentPath);
             // Publication is complete. A failed outer check must not remove its target.
             created = false;
             await params.verifyPublished?.(handle.fd, verificationIdentity, parentGuard);
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            completed = true;
             return { dev: stat.dev, ino: stat.ino };
         }
         finally {
@@ -295,114 +289,12 @@ async function runPinnedWriteFallback(params) {
                 }
             }
             finally {
-                await handle.close().catch(() => undefined);
-            }
-        }
-    }
-    // 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;
-    try {
-        params.assertBeforeMutation?.();
-        handle = await fs.open(tempPath, tempFlags, params.mode);
-        let verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
-        tempIdentity = verificationIdentity;
-        if (params.input.kind === "buffer") {
-            assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
-            await writeAllToFile(handle, params.input.data, {
-                encoding: params.input.encoding, assertBeforeMutation: params.assertBeforeMutation,
-            });
-        }
-        else if (params.input.kind === "file") {
-            await writeCopyFileToFd(handle.fd, params.input, params.maxBytes, params.assertBeforeMutation);
-        }
-        else {
-            await writeStreamToHandle(params.input.stream, handle, params.maxBytes, params.assertBeforeMutation);
-        }
-        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 (params.sync !== false)
-            await syncFileBestEffort(handle);
-        if (params.input.kind === "file")
-            await params.input.verifySource();
-        let verifiedIdentity = expectedTempStat;
-        await withAsyncDirectoryGuards([parentGuard], async () => {
-            assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
-            if (params.overwrite === false) {
-                publishCopyStage({
-                    temporaryPath: tempPath, targetPath, fd: handle.fd,
-                    identity: tempIdentity, parentGuard,
-                    assertBeforeMutation: params.assertBeforeMutation,
-                    onPublished: (identity) => {
-                        renamed = true;
-                        params.onPublished?.(identity);
-                    },
-                });
+                if (completed)
+                    await handle.close();
+                else
+                    await handle.close().catch(() => undefined);
             }
-            else {
-                params.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);
-        return { dev: verifiedIdentity.dev, ino: verifiedIdentity.ino };
-    }
-    finally {
-        try {
-            if (!renamed && handle) {
-                await cleanupPinnedFilePath({ pathname: tempPath, handle, identity: tempIdentity, parentGuard });
-            }
-        }
-        finally {
-            await readHandle?.close().catch(() => undefined);
-            await handle?.close().catch(() => undefined);
         }
     }
+    return await runPinnedStagedWrite(params, parentPath, parentGuard);
 }

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

@@ -6,4 +6,3 @@ export type ReadFileWindowOptions = {
 export declare function readFileWindowFully(handle: FileHandle, buffer: Buffer, position: number, { signal }?: ReadFileWindowOptions): Promise<number>;
 /** Synchronous positional read; neither variant advances or closes its descriptor. */
 export declare function readFileWindowFullySync(fd: number, buffer: Buffer, position: number): number;
-//# sourceMappingURL=positional-read.d.ts.map

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

@@ -2,4 +2,3 @@ export type CreatePrivateDirectoryOptions = {
     platform?: NodeJS.Platform;
 };
 export declare function createPrivateDirectory(targetPath: string, options?: CreatePrivateDirectoryOptions): Promise<void>;
-//# sourceMappingURL=private-directory.d.ts.map

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

@@ -1,6 +1,10 @@
+import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { createPrivateWindowsDirectoryCommand } from "./windows-security-command.js";
 export async function createPrivateDirectory(targetPath, options) {
     const platform = options?.platform ?? process.platform;
     if (platform !== "win32") {
@@ -8,9 +12,19 @@ export async function createPrivateDirectory(targetPath, options) {
     }
     assertNoWindowsPathAlias(targetPath, "filesystem", "private directory path uses a Windows filesystem namespace alias", platform);
     const native = getNativeBinding();
-    if (!native) {
-        throw new FsSafeError("helper-unavailable", "private Windows directory creation requires the matching optional native platform package; " +
-            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
+    if (typeof native?.createPrivateDirectory === "function") {
+        native.createPrivateDirectory(targetPath);
+        return;
     }
-    native.createPrivateDirectory(targetPath);
+    if (getFsSafeNativeConfig().mode === "require") {
+        throw new FsSafeError("helper-unavailable", "private Windows directory creation requires an up-to-date native helper");
+    }
+    // Preserve the native parser's raw component restrictions before resolve()
+    // could discard dot components or Win32 could trim trailing aliases.
+    const components = targetPath.replaceAll("/", "\\").split("\\");
+    if (components.some(component => component.endsWith(".") || component.endsWith(" "))) {
+        throw Object.assign(new Error("private directory path has an ambiguous component"), { code: "EINVAL" });
+    }
+    warnNativeFallback("windows-private-directory", "Private Windows directory creation uses a slower built-in system command.");
+    await createPrivateWindowsDirectoryCommand(path.win32.resolve(targetPath));
 }

package/node_modules/@openclaw/fs-safe/dist/private-producer-handoff-sync.d.ts

@@ -0,0 +1,3 @@
+import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
+import { type CreatedHandoffParams } from "./private-producer-handoff.js";
+export declare function handoffCreatedFileSync(params: CreatedHandoffParams<OwnedFileDescriptorSync, void>): OwnedFileDescriptorSync;