@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,63 +1,87 @@
 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 { createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.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";
-function byteLength(input, encoding) {
-    return typeof input === "string"
-        ? Buffer.byteLength(input, encoding ?? "utf8")
-        : input.byteLength;
-}
+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 { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 function assertSafeBasename(basename) {
     if (!basename ||
         basename === "." ||
         basename === ".." ||
         basename.includes("/") ||
+        (process.platform === "win32" && basename.includes("\\")) ||
         basename.includes("\0")) {
         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) {
-    let bytes = 0;
-    for await (const chunk of stream) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += buffer.byteLength;
-        assertWithinMaxBytes(bytes, maxBytes);
-        let offset = 0;
-        while (offset < buffer.byteLength) {
-            const { bytesWritten } = await handle.write(buffer, offset, buffer.byteLength - offset);
-            if (bytesWritten <= 0) {
-                throw new FsSafeError("helper-failed", "fallback stream write made no progress");
-            }
-            offset += bytesWritten;
-        }
+const PINNED_WRITE_SNAPSHOT_KEYS = [
+    "rootPath", "relativeParentPath", "basename", "maxBytes", "rootIdentity",
+];
+const RENAME_POLICY_SNAPSHOT_KEYS = ["targetPath", "renameIdentity"];
+function copyOwnEnumerableExcept(source, excluded) {
+    const owned = {};
+    for (const key of Reflect.ownKeys(source)) {
+        // Node 22's object-rest fast path can read excluded accessors eagerly.
+        // Exclude before even inspecting the descriptor so named authority and
+        // pathname fields remain single-read snapshots on every supported Node.
+        if (excluded.includes(key))
+            continue;
+        if (!Object.getOwnPropertyDescriptor(source, key)?.enumerable)
+            continue;
+        Object.defineProperty(owned, key, {
+            value: Reflect.get(source, key),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
     }
+    return owned;
 }
 export async function runPinnedWriteHelper(params) {
-    const normalizedParams = { ...params, maxBytes: normalizeMaxBytes(params.maxBytes) };
-    assertSafeBasename(params.basename);
-    validatePinnedOperationPayload({
-        relativeParentPath: params.relativeParentPath,
-    });
+    const { rootPath, relativeParentPath, basename, maxBytes, rootIdentity } = params;
+    const ownedParams = copyOwnEnumerableExcept(params, PINNED_WRITE_SNAPSHOT_KEYS);
+    const normalizedParams = {
+        ...ownedParams,
+        rootPath,
+        relativeParentPath,
+        basename,
+        maxBytes: normalizeMaxBytes(maxBytes),
+        rootIdentity,
+    };
+    assertSafeBasename(normalizedParams.basename);
+    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");
+    if (rootIdentity !== undefined) {
+        normalizedParams.rootIdentity = { dev: rootIdentity.dev, ino: rootIdentity.ino };
+    }
+    if (normalizedParams.mutationAdmission) {
+        const targetPath = path.join(normalizedParams.rootPath, ...normalizedParams.relativeParentPath.split("/").filter(Boolean), normalizedParams.basename);
+        await getFsSafeTestHooks()?.beforePinnedWriteParentAdmission?.(targetPath);
+    }
     // The explicit compatibility policy uses the guarded Node fallback, where
     // content verification can replace the strict post-rename inode check.
     if (normalizedParams.onRenameIdentityMismatch === "verify-content") {
@@ -70,52 +94,153 @@ export async function runPinnedWriteHelper(params) {
     return await runPinnedWriteFallback(normalizedParams);
 }
 export async function runPinnedWriteWithRenamePolicy(params) {
-    const { targetPath, renameIdentity, ...writeParams } = params;
+    const { targetPath, renameIdentity } = params;
+    const writeParams = copyOwnEnumerableExcept(params, RENAME_POLICY_SNAPSHOT_KEYS);
     if (renameIdentity !== "verify-content-with-lock") {
         return await runPinnedWriteHelper(writeParams);
     }
     const relativeTargetPath = writeParams.relativeParentPath
         ? `${writeParams.relativeParentPath}/${writeParams.basename}`
         : writeParams.basename;
-    const lockPath = path.join(writeParams.rootPath, `.fs-safe-write-${sha256Hex(relativeTargetPath)}.lock`);
-    return await withSidecarLock(writeParams.rootPath, {
-        managerKey: `fs-safe.write:${targetPath}`,
+    return await withPinnedWriteRenameIdentityLock({
+        rootPath: writeParams.rootPath, targetPath, relativeTargetPath,
+    }, async () => await runPinnedWriteHelper({
+        ...writeParams,
+        onRenameIdentityMismatch: "verify-content",
+    }));
+}
+export async function withPinnedWriteRenameIdentityLock(params, run) {
+    const lockPath = path.join(params.rootPath, `.fs-safe-write-${sha256Hex(params.relativeTargetPath)}.lock`);
+    return await withSidecarLock(params.rootPath, {
+        managerKey: `fs-safe.write:${params.targetPath}`,
         lockPath,
         staleMs: 30_000,
         timeoutMs: 5_000,
         payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
         retry: { retries: 5, minTimeout: 100, maxTimeout: 2_000, factor: 2 },
-    }, async () => await runPinnedWriteHelper({
-        ...writeParams,
-        onRenameIdentityMismatch: "verify-content",
-    }));
+    }, 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;
     if (exactRoot)
         await inspectDirectoryIdentity(params.rootPath, exactRoot);
-    const guardOptions = { bigint: exactRoot !== undefined };
     let parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
         : params.rootPath;
-    if (params.mkdir) {
+    let parentGuard;
+    let parentAdmitted = false;
+    const initialTargetPath = path.join(parentPath, params.basename);
+    const retainedTargetPath = mutationAdmission?.beginParentWalk?.();
+    const ordinaryRetainedTarget = retainedTargetPath !== undefined &&
+        path.relative(path.resolve(retainedTargetPath), path.resolve(initialTargetPath)) === "";
+    let fastGuardClassifierFailure;
+    if (ordinaryRetainedTarget) {
+        try {
+            parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+        }
+        catch (error) {
+            // Only a genuinely missing complete parent may enter the component
+            // creator. ENOTDIR, permission, identity, and canonicalization failures
+            // retain their original fail-closed result.
+            if (error?.code !== "ENOENT") {
+                if (!fastParentGuardDeopt(error))
+                    throw error;
+                fastGuardClassifierFailure = error;
+            }
+        }
+        if (parentGuard) {
+            await mutationAdmission.authorize(Object.freeze({
+                targetPath: initialTargetPath,
+                mutationPath: initialTargetPath,
+                phase: "parent",
+            }));
+            await assertAsyncDirectoryGuard(parentGuard);
+            parentAdmitted = true;
+        }
+    }
+    if (fastGuardClassifierFailure) {
+        // The optimized exact-guard classifier runs before policy admission. Let
+        // the established resolver restore deny/symlink precedence before using
+        // the guarded walker or reporting the classifier failure. Because this
+        // was not an ENOENT probe, it may never authorize a newly missing parent.
+        await mutationAdmission.authorize(Object.freeze({
+            targetPath: initialTargetPath,
+            mutationPath: initialTargetPath,
+            phase: "parent",
+        }));
+    }
+    if (params.mkdir && !parentGuard) {
         // mkdirPathComponentsWithGuards may resolve the final component through
         // an in-root symlink (e.g. a skill-bank layout). Use its returned real
         // path for the subsequent guard and target path so we don't re-check the
         // original, possibly-symlinked, lexical path and reject it outright.
-        parentPath = await mkdirPathComponentsWithGuards({
+        const mkdirParams = {
             rootReal: params.rootPath,
             targetPath: parentPath,
-            beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
-        });
+            rootIdentity: params.rootIdentity,
+            assertBeforeMutation: params.assertBeforeMutation,
+            beforeComponent: async (componentPath) => {
+                await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath);
+            },
+        };
+        parentPath = await mkdirPathComponentsWithGuards(mutationAdmission ? {
+            ...mkdirParams,
+            rejectSymlinks: mutationAdmission.rejectParentSymlinks,
+            revalidateParentAfterBeforeComponent: true,
+            synchronousAuthorizationIncludesFence: true,
+            retainedTargetPath,
+            afterCreateComponent: mutationAdmission.advanceCreatedDirectory,
+            beforeCreateComponent: (componentPath, prospectiveParentPath, retainedTarget, parent) => {
+                if (fastGuardClassifierFailure)
+                    throw fastGuardClassifierFailure;
+                const request = Object.freeze({
+                    targetPath: retainedTarget ?? path.join(prospectiveParentPath, params.basename),
+                    mutationPath: componentPath,
+                    phase: "parent-create",
+                });
+                return mutationAdmission.tryAuthorizeAtParent?.(request, parent) ??
+                    mutationAdmission.authorize(request);
+            },
+            beforeUseComponent: async (_componentPath, prospectiveParentPath, retainedTarget) => {
+                const targetPath = retainedTarget ?? path.join(prospectiveParentPath, params.basename);
+                await mutationAdmission.authorize(Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                }));
+            },
+        } : mkdirParams);
     }
-    const parentGuard = params.mkdir
-        ? await createAsyncDirectoryGuard(parentPath, guardOptions)
-        : await createNearestExistingDirectoryGuard(params.rootPath, parentPath, guardOptions);
+    parentGuard ??= params.mkdir
+        ? await createAsyncDirectoryGuard(parentPath, { bigint: true })
+        : await createNearestExistingDirectoryGuard(params.rootPath, parentPath, { bigint: true });
     const targetPath = path.join(parentPath, params.basename);
-    if (params.overwrite === false) {
-        const handle = await withAsyncDirectoryGuards([parentGuard], async () => await fs.open(targetPath, fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL, params.mode), {
+    if (mutationAdmission && !parentAdmitted) {
+        await mutationAdmission.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+    }
+    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();
+            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
                 // somewhere else. Close the fd, but do not clean up by path.
@@ -123,32 +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);
-                if (typeof params.input.data === "string") {
-                    await handle.writeFile(params.input.data, params.input.encoding ?? "utf8");
-                }
-                else {
-                    await handle.writeFile(params.input.data);
-                }
-            }
-            else {
-                await writeStreamToHandle(params.input.stream, handle, params.maxBytes);
-            }
+            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 {
@@ -158,95 +289,12 @@ async function runPinnedWriteFallback(params) {
                 }
             }
             finally {
-                await handle.close().catch(() => undefined);
+                if (completed)
+                    await handle.close();
+                else
+                    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 {
-        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);
-            if (typeof params.input.data === "string") {
-                await handle.writeFile(params.input.data, params.input.encoding ?? "utf8");
-            }
-            else {
-                await handle.writeFile(params.input.data);
-            }
-        }
-        else {
-            await writeStreamToHandle(params.input.stream, handle, params.maxBytes);
-        }
-        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);
-        let verifiedIdentity = expectedTempStat;
-        await withAsyncDirectoryGuards([parentGuard], async () => {
-            await fs.rename(tempPath, targetPath);
-            renamed = true;
-            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

@@ -0,0 +1,8 @@
+import type { FileHandle } from "node:fs/promises";
+export type ReadFileWindowOptions = {
+    signal?: AbortSignal;
+};
+/** Fills a caller-owned buffer from an explicit position, stopping at EOF. */
+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;

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

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+// Node's synchronous read length is a signed 32-bit value on supported runtimes.
+const MAX_READ_BYTES = 0x7fffffff;
+function validateWindow(buffer, position) {
+    if (!Number.isSafeInteger(position) || position < 0 ||
+        !Number.isSafeInteger(position + buffer.length)) {
+        throw new RangeError("read position and window end must be non-negative safe integers");
+    }
+}
+/** Fills a caller-owned buffer from an explicit position, stopping at EOF. */
+export async function readFileWindowFully(handle, buffer, position, { signal } = {}) {
+    validateWindow(buffer, position);
+    signal?.throwIfAborted();
+    let total = 0;
+    while (total < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, total, Math.min(buffer.length - total, MAX_READ_BYTES), position + total);
+        // Settle the pending read before cancellation lets the caller reuse its buffer or handle.
+        signal?.throwIfAborted();
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return total;
+}
+/** Synchronous positional read; neither variant advances or closes its descriptor. */
+export function readFileWindowFullySync(fd, buffer, position) {
+    validateWindow(buffer, position);
+    let total = 0;
+    while (total < buffer.length) {
+        const bytesRead = fs.readSync(fd, buffer, total, Math.min(buffer.length - total, MAX_READ_BYTES), position + total);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return total;
+}

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,14 +1,30 @@
+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") {
         throw new FsSafeError("helper-unavailable", "private-directory creation is supported only on Windows");
     }
+    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;

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

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import { ownFileDescriptorSync } from "./create-owned-file.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertInitialSource, FileHandoff, inspectLinkedFile, } from "./private-producer-handoff.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+export function handoffCreatedFileSync(params) {
+    let retained = params.source;
+    const owners = new Set([retained]);
+    const failures = [];
+    const state = new FileHandoff(params, params.identity, true);
+    function close(owner) {
+        // A throwing close may already have released the descriptor for reuse.
+        owners.delete(owner);
+        try {
+            owner.close();
+        }
+        catch (error) {
+            state.closeFailed = true;
+            throw error;
+        }
+    }
+    function verifyCurrent(owner, descriptorPath, links) {
+        state.inspect(owner, links);
+        params.verifyDescriptor?.(owner.fd, descriptorPath, Number(links));
+    }
+    try {
+        assertInitialSource(params.identity);
+        verifyCurrent(retained, params.sourcePath, 1n);
+        assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
+        state.inspect(retained, 1n);
+        state.publish();
+        try {
+            params.onPublished?.();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (process.platform === "win32") {
+            verifyCurrent(retained, params.sourcePath, 2n);
+            // Keep the original pin until a verified published-name pin exists, so
+            // Windows can retire the staging name without leaving it delete-pending.
+            const sibling = ownFileDescriptorSync(fs.openSync(params.targetPath, fs.constants.O_RDWR | resolveReadOpenFlags()));
+            owners.add(sibling);
+            verifyCurrent(sibling, params.targetPath, 2n);
+            inspectLinkedFile(() => fs.fstatSync(retained.fd, { bigint: true }), params.identity, 2n, "created file descriptor");
+            close(retained);
+            retained = sibling;
+        }
+        const descriptorPath = process.platform === "win32" ? params.targetPath : params.sourcePath;
+        verifyCurrent(retained, descriptorPath, 2n);
+        assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
+        state.inspect(retained, 2n);
+        // Link and unlink stay in one JS turn. Only the verified stage is removed;
+        // publication has committed and the destination is never rollback cleanup.
+        state.retireSource();
+        verifyCurrent(retained, params.targetPath, 1n);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    if (failures.length === 0)
+        return retained;
+    for (const owner of owners) {
+        try {
+            close(owner);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    throw state.failure(failures, "created file publication and settlement failed");
+}