@openclaw/openshell-sandbox 2026.9.3 → 2026.9.5

package/node_modules/@openclaw/fs-safe/dist/root-context.js

@@ -1,17 +1,24 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { inspectDirectoryIdentity } from "./directory-guard.js";
+import { extendDirectoryObservationGuard, inspectDirectoryIdentitySync, inspectDirectoryObservationSync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
-import { expandHomePrefix } from "./home-dir.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
-import { outsideWorkspaceError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function hasExactRootIdentity(identity) {
+    return typeof identity.dev === "bigint" && typeof identity.ino === "bigint";
+}
 export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
 export function assertValidRootRelativePath(relativePath) {
     assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
+    assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
 }
 export function assertValidRootDestinationPath(relativePath) {
     assertValidRootRelativePath(relativePath);
@@ -20,30 +27,52 @@ export function assertValidRootDestinationPath(relativePath) {
     }
 }
 let cachedHomePath;
+const POSIX_PARENT_COMPONENT = /(?:^|\/)\.\.(?:\/|$)/;
+const WINDOWS_PARENT_COMPONENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 export async function expandRelativePathWithHome(relativePath) {
+    const homeOnly = relativePath === "~";
+    const homePrefix = relativePath.startsWith("~/") || (path.sep === "\\" && relativePath.startsWith("~\\"));
+    if (!homeOnly && !homePrefix) {
+        assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
+        return relativePath;
+    }
     const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    assertNoWindowsPathAlias(rawHome, "filesystem", "home path uses a Windows filesystem namespace alias");
     if (cachedHomePath?.raw !== rawHome) {
         let realHome = rawHome;
         try {
-            realHome = fs.realpathSync.native(rawHome);
+            realHome = realpathSync.native(pathForWindowsFilesystem(rawHome));
         }
         catch {
             // If the home dir cannot be canonicalized, keep lexical expansion behavior.
         }
         cachedHomePath = { raw: rawHome, real: realHome };
     }
-    return expandHomePrefix(relativePath, { home: cachedHomePath.real });
+    if (homeOnly) {
+        assertNoWindowsPathAlias(cachedHomePath.real, "filesystem", "home path uses a Windows filesystem namespace alias");
+        return cachedHomePath.real;
+    }
+    const expanded = `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    return expanded;
 }
 export async function resolveRootContext(rootDir) {
     assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
+    assertNoWindowsPathAlias(rootDir, "filesystem", "root dir uses a Windows filesystem namespace alias");
+    const lexicalRoot = resolvePathPreservingWindowsRoot(rootDir);
+    assertNoWindowsPathAlias(lexicalRoot, "filesystem", "root dir uses a Windows filesystem namespace alias");
     let rootReal;
+    let rootStat;
     let rootIdentity;
     try {
-        rootReal = fs.realpathSync.native(rootDir);
-        const rootStat = fs.statSync(rootReal);
-        if (!rootStat.isDirectory()) {
-            throw new FsSafeError("invalid-path", "root dir is not a directory");
-        }
+        rootReal = realpathSync.native(pathForWindowsFilesystem(rootDir));
+        assertNoWindowsPathAlias(rootReal, "filesystem", "canonical root path uses a Windows filesystem namespace alias");
+        rootStat = await inspectFileIdentity(() => {
+            const stat = fs.statSync(rootReal, { bigint: true });
+            if (!stat.isDirectory())
+                throw new FsSafeError("invalid-path", "root dir is not a directory");
+            return stat;
+        });
         rootIdentity = { dev: rootStat.dev, ino: rootStat.ino };
     }
     catch (err) {
@@ -56,7 +85,8 @@ export async function resolveRootContext(rootDir) {
         throw err;
     }
     return {
-        rootDir: path.resolve(rootDir),
+        rootDir: lexicalRoot,
+        rootGuard: { dir: rootReal, realPath: rootReal, stat: rootStat },
         rootIdentity,
         rootReal,
         rootWithSep: ensureTrailingSep(rootReal),
@@ -64,44 +94,83 @@ export async function resolveRootContext(rootDir) {
 }
 export function rootRelativeReadPath(root, filePath) {
     const absoluteInput = path.isAbsolute(filePath);
-    const candidatePath = absoluteInput
-        ? path.resolve(filePath)
-        : path.resolve(root.rootDir, filePath);
-    let relativeBase = root.rootDir;
-    if (absoluteInput &&
-        !isPathInside(root.rootDir, candidatePath) &&
-        isPathInside(root.rootReal, candidatePath)) {
-        // A Root created through an alias has two valid in-root absolute spellings.
-        relativeBase = root.rootReal;
-    }
-    return path.relative(relativeBase, candidatePath);
+    if (!absoluteInput)
+        return filePath;
+    const raw = process.platform === "win32" ? filePath.replaceAll("/", path.sep) : filePath;
+    const bases = root.rootDir === root.rootReal ? [root.rootReal] : [root.rootDir, root.rootReal];
+    for (const base of bases) {
+        if (process.platform === "win32") {
+            const admitted = admitPathInsideRoot({
+                rootPath: base,
+                candidatePath: raw,
+                rootIdentity: root.rootIdentity,
+                resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
+            });
+            if (admitted)
+                return admitted.relativePath;
+            continue;
+        }
+        const prefix = ensureTrailingSep(base);
+        const matches = raw.startsWith(prefix);
+        if (matches) {
+            let start = prefix.length;
+            while (raw[start] === path.sep)
+                start += 1;
+            return raw.slice(start);
+        }
+    }
+    return raw;
 }
-export async function assertRootIdentityCurrent(root) {
+export function assertRootIdentityCurrentSync(root, observe) {
     let current;
     try {
         if (typeof root.rootIdentity.dev === "bigint" && typeof root.rootIdentity.ino === "bigint") {
-            await inspectDirectoryIdentity(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            const stat = inspectDirectoryIdentitySync(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            observe?.(stat);
             return;
         }
         current = fs.lstatSync(root.rootReal);
     }
     catch (error) {
-        throw new FsSafeError("path-mismatch", "root path changed during operation", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
     }
     if (current.isSymbolicLink() ||
         !current.isDirectory() ||
         !sameFileIdentity(current, root.rootIdentity)) {
-        throw new FsSafeError("path-mismatch", "root path changed during operation");
+        throw rootPathChangedError();
+    }
+}
+export async function assertRootIdentityCurrent(root, observe) {
+    assertRootIdentityCurrentSync(root, observe);
+}
+/**
+ * Observe the current Root with an exact, operation-local receipt.
+ *
+ * This is deliberately separate from {@link assertRootIdentityCurrent}: callers
+ * must not retain the returned guard beyond the operation that requested it.
+ */
+export async function createRootObservationGuard(root) {
+    const rootIdentity = root.rootIdentity;
+    if (!hasExactRootIdentity(rootIdentity)) {
+        await assertRootIdentityCurrent(root);
+        return undefined;
+    }
+    try {
+        const observed = await inspectDirectoryObservationSync(root.rootReal, rootIdentity);
+        return extendDirectoryObservationGuard(observed, root.rootReal, root.rootReal);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
     }
 }
 export async function resolvePathInRoot(root, relativePath, options) {
     assertValidRootRelativePath(relativePath);
     await assertRootIdentityCurrent(root);
     const expanded = await expandRelativePathWithHome(relativePath);
-    const resolved = path.resolve(root.rootWithSep, expanded);
-    if (!isPathInside(root.rootWithSep, resolved)) {
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    let resolved = resolvePathFromBasePreservingWindowsRoot(root.rootWithSep, expanded);
+    assertNoWindowsPathAlias(resolved, "filesystem", "resolved path uses a Windows filesystem namespace alias");
+    if (!options?.resolveCanonical && !isPathInside(root.rootWithSep, resolved)) {
         throw outsideWorkspaceError();
     }
     if (options?.rejectUnsafeDeviceReads === true) {
@@ -110,15 +179,44 @@ export async function resolvePathInRoot(root, relativePath, options) {
     const rawAbsolutePath = path.isAbsolute(expanded)
         ? expanded
         : `${root.rootWithSep}${expanded}`;
+    assertNoWindowsPathAlias(rawAbsolutePath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
     try {
-        await resolveRootPath({
+        const resolution = {
             absolutePath: rawAbsolutePath,
             rootPath: root.rootReal,
             rootCanonicalPath: root.rootReal,
+            rootIdentity: root.rootIdentity,
             boundaryLabel: "root",
             policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
             rejectSymlinks: options?.rejectSymlinks,
-        });
+            rejectFinalSymlink: options?.rejectFinalSymlink,
+        };
+        const checked = await resolveRootPath(resolution);
+        const parentComponent = process.platform === "win32" ? WINDOWS_PARENT_COMPONENT : POSIX_PARENT_COMPONENT;
+        if (options?.rejectAmbiguousParents && parentComponent.test(expanded) &&
+            path.relative(checked.canonicalPath, resolved) !== "") {
+            const normalized = await resolveRootPath({ ...resolution, absolutePath: resolved });
+            if (path.relative(checked.canonicalPath, normalized.canonicalPath) !== "") {
+                throw new FsSafeError("path-alias", "parent traversal resolves differently through a symlink");
+            }
+        }
+        if (options?.resolveCanonical) {
+            resolved = checked.canonicalPath;
+        }
+        else {
+            // resolveRootPath preserves ordinary caller spelling as part of its
+            // public receipt. Re-admit the exact normalized spelling before it is
+            // reused for Root I/O: on a case-sensitive Windows directory it may
+            // otherwise name a distinct case-folded sibling after raw traversal.
+            const admitted = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: checked.absolutePath,
+                rootIdentity: root.rootIdentity,
+            });
+            if (!admitted)
+                throw outsideWorkspaceError();
+            resolved = admitted.path;
+        }
     }
     catch (error) {
         if (error instanceof FsSafeError && error.code === "symlink") {

package/node_modules/@openclaw/fs-safe/dist/root-create-input.d.ts

@@ -0,0 +1,10 @@
+import type { PinnedWriteInput } from "./pinned-write.js";
+import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
+export type RootWriteParams = RootWriteOptions & RootCreateStreamOptions & {
+    relativePath: string;
+    data: string | Buffer | AsyncIterable<Uint8Array>;
+};
+export declare function rethrowCreateInputError(error: unknown): never;
+export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
+export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
+//# sourceMappingURL=root-create-input.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/root-create-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-create-input.d.ts","sourceRoot":"","sources":["../src/root-create-input.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEtG,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,uBAAuB,GAAG;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;CACnD,CAAC;AAQF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAG7D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,iBAAiB,GAAG,uBAAuB,EACpD,eAAe,CAAC,EAAE,MAAM,GACvB,iBAAiB,GAAG,uBAAuB,CAe7C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAwCxE"}

package/node_modules/@openclaw/fs-safe/dist/root-create-input.js

@@ -0,0 +1,80 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
+class CreateInputError extends FsSafeError {
+    rejection;
+    constructor(rejection) {
+        super("helper-failed", "create input failed", { cause: rejection });
+        this.rejection = rejection;
+    }
+}
+export function rethrowCreateInputError(error) {
+    if (error instanceof CreateInputError)
+        throw error.rejection;
+    throw error;
+}
+export function createInputOptions(data, options, defaultMaxBytes) {
+    if (typeof data === "string" || Buffer.isBuffer(data))
+        return options;
+    options.signal?.throwIfAborted();
+    if (options.encoding !== undefined || options.renameIdentity !== undefined) {
+        throw new TypeError("streamed create does not accept encoding or renameIdentity");
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: defaultMaxBytes });
+    return {
+        ...options,
+        maxBytes,
+        assertBeforeMutation: () => {
+            options.signal?.throwIfAborted();
+            return options.assertBeforeMutation?.();
+        },
+    };
+}
+export function rootWriteInput(params) {
+    const data = params.data;
+    if (typeof data === "string" || Buffer.isBuffer(data)) {
+        return { kind: "buffer", data, encoding: params.encoding };
+    }
+    return {
+        kind: "stream",
+        stageBeforePublish: true,
+        stream: (async function* () {
+            let iterator;
+            let completed = false;
+            try {
+                params.signal?.throwIfAborted();
+                iterator = data[Symbol.asyncIterator]();
+                while (true) {
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    const next = await iterator.next();
+                    completed = next.done === true;
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    if (completed)
+                        return;
+                    const chunk = next.value;
+                    if (!(chunk instanceof Uint8Array)) {
+                        throw new TypeError("streamed create chunks must be Uint8Array values");
+                    }
+                    yield chunk;
+                }
+            }
+            catch (error) {
+                if (error instanceof MutationAuthorityError)
+                    throw error;
+                throw new CreateInputError(error);
+            }
+            finally {
+                if (iterator && !completed) {
+                    try {
+                        await iterator.return?.();
+                    }
+                    catch (error) {
+                        throw new CreateInputError(error);
+                    }
+                }
+            }
+        })(),
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { RootContext } from "./root-context.js";
+/**
+ * Complete the common Root.mkdir case with one exact existing parent. This is
+ * optional evidence: every uncertain probe returns to the ordered root walk.
+ */
+export declare function tryMkdirAtExactParent(root: RootContext, targetPath: string, mutationAdmission: PinnedWriteMutationAdmission): Promise<boolean>;
+export declare function prepareRootWriteTarget(root: RootContext, targetPath: string, assertBeforeMutation?: () => void, mutationAdmission?: PinnedWriteMutationAdmission): Promise<string>;
+export declare function mkdirPathFallback(root: RootContext, resolved: {
+    rootReal: string;
+    resolved: string;
+}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission): Promise<void>;
+//# sourceMappingURL=root-directory-creation.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/root-directory-creation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-directory-creation.d.ts","sourceRoot":"","sources":["../src/root-directory-creation.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoDrD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,4BAA4B,GAC9C,OAAO,CAAC,OAAO,CAAC,CAoGlB;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,iBAAiB,CAAC,EAAE,4BAA4B,GAC/C,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChD,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,cAAc,UAAQ,EACtB,iBAAiB,CAAC,EAAE,4BAA4B,GAC/C,OAAO,CAAC,IAAI,CAAC,CAuBf"}

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

@@ -0,0 +1,212 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
+import { hasNodeErrorCode } from "./path.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function mutationWalkOptions(mutationAdmission, operationTarget, assertBeforeMutation) {
+    const session = assertBeforeMutation === undefined
+        ? mutationAdmission.beginSharedParentWalk?.()
+        : undefined;
+    return {
+        dispose: () => session?.dispose(),
+        options: {
+            rejectSymlinks: mutationAdmission.rejectParentSymlinks,
+            revalidateParentAfterBeforeComponent: true,
+            retainedTargetPath: session?.retainedTargetPath,
+            synchronousAuthorizationIncludesFence: session !== undefined,
+            afterCreateComponent: session?.advanceCreatedDirectory,
+            beforeCreateComponent: (componentPath, prospectiveDirectory, retainedTargetPath, parent) => {
+                const targetPath = retainedTargetPath ?? operationTarget(prospectiveDirectory);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: componentPath,
+                    phase: "parent-create",
+                });
+                return session?.tryAuthorizeAtParent(request, parent) ??
+                    (session?.authorize(request) ?? mutationAdmission.authorize(request));
+            },
+            beforeUseComponent: async (_componentPath, prospectiveDirectory, retainedTargetPath) => {
+                const targetPath = retainedTargetPath ?? operationTarget(prospectiveDirectory);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                await (session?.authorize(request) ?? mutationAdmission.authorize(request));
+            },
+        },
+    };
+}
+/**
+ * Complete the common Root.mkdir case with one exact existing parent. This is
+ * optional evidence: every uncertain probe returns to the ordered root walk.
+ */
+export async function tryMkdirAtExactParent(root, targetPath, mutationAdmission) {
+    if (getFsSafeTestHooks()?.beforeRootFallbackMutation)
+        return false;
+    if (typeof root.rootIdentity.dev !== "bigint" ||
+        typeof root.rootIdentity.ino !== "bigint" ||
+        root.rootIdentity.dev === 0n || root.rootIdentity.ino === 0n)
+        return false;
+    const rootIdentity = Object.freeze({
+        dev: root.rootIdentity.dev,
+        ino: root.rootIdentity.ino,
+    });
+    const session = mutationAdmission.beginSharedParentWalk?.();
+    if (!session)
+        return false;
+    try {
+        if (path.resolve(session.retainedTargetPath) !== path.resolve(targetPath))
+            return false;
+        const parentPath = path.dirname(targetPath);
+        let parentGuard;
+        try {
+            parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+        }
+        catch {
+            return false;
+        }
+        try {
+            fsSync.lstatSync(targetPath, { bigint: true });
+            return false;
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                return false;
+        }
+        const admittedParent = admitPathInsideRoot({
+            rootPath: root.rootReal,
+            candidatePath: parentPath,
+            rootIdentity,
+        });
+        if (admittedParent?.admission !== "exact" || admittedParent.path !== parentPath ||
+            parentGuard.realPath !== parentPath)
+            return false;
+        await session.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+        try {
+            fsSync.lstatSync(targetPath, { bigint: true });
+            return false;
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                return false;
+        }
+        assertSyncDirectoryGuard(parentGuard);
+        const createAdmission = session.tryAuthorizeAtParent(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent-create",
+        }), checkedMutationDirectory(parentPath, parentGuard.realPath, parentGuard.stat));
+        if (!createAdmission)
+            return false;
+        try {
+            await fs.mkdir(targetPath);
+        }
+        catch (error) {
+            if (hasNodeErrorCode(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        const observeCreated = async () => {
+            const childGuard = await createAsyncDirectoryGuard(targetPath, { bigint: true });
+            const parentAfter = inspectDirectoryIdentitySync(parentPath, parentGuard.stat);
+            assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+            const admittedChild = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: childGuard.realPath,
+                rootIdentity,
+            });
+            if (childGuard.realPath !== targetPath || childGuard.dir !== targetPath ||
+                admittedChild?.admission !== "exact" || admittedChild.path !== targetPath) {
+                throw new FsSafeError("path-mismatch", "created directory changed during operation");
+            }
+            return { childGuard, parentAfter };
+        };
+        try {
+            const created = await observeCreated();
+            if (session.advanceCreatedDirectory(Object.freeze({
+                admission: createAdmission,
+                parent: checkedMutationDirectory(parentPath, parentGuard.realPath, created.parentAfter),
+                child: checkedMutationDirectory(targetPath, created.childGuard.realPath, created.childGuard.stat),
+            })))
+                return true;
+        }
+        catch {
+            // Post-create observations are optional receipt evidence. The directory
+            // was already created, so renew ordered admission without a second mkdir.
+        }
+        await session.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+        assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+        assertFinalSymlinkRejected(targetPath, true);
+        const refreshed = await observeCreated();
+        await assertAsyncDirectoryGuard(parentGuard);
+        await assertAsyncDirectoryGuard(refreshed.childGuard);
+        assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+        return true;
+    }
+    finally {
+        session.dispose();
+    }
+}
+export async function prepareRootWriteTarget(root, targetPath, assertBeforeMutation, mutationAdmission) {
+    const basename = path.basename(targetPath);
+    const baseParams = {
+        rootReal: root.rootReal,
+        rootIdentity: root.rootIdentity,
+        targetPath: path.dirname(targetPath),
+        assertBeforeMutation,
+    };
+    const mutationWalk = mutationAdmission
+        ? mutationWalkOptions(mutationAdmission, (prospectiveParent) => path.join(prospectiveParent, basename), assertBeforeMutation)
+        : undefined;
+    let parentPath;
+    try {
+        parentPath = await mkdirPathComponentsWithGuards(mutationWalk ? {
+            ...baseParams,
+            ...mutationWalk.options,
+        } : baseParams);
+    }
+    finally {
+        mutationWalk?.dispose();
+    }
+    // Continue through the guarded walk's real parent instead of re-entering
+    // the original path through a symlinked component.
+    return path.join(parentPath, basename);
+}
+export async function mkdirPathFallback(root, resolved, assertBeforeMutation, rejectSymlinks = false, mutationAdmission) {
+    const baseParams = {
+        rootReal: resolved.rootReal, targetPath: resolved.resolved, assertBeforeMutation,
+        rootIdentity: root.rootIdentity,
+        rejectSymlinks,
+        beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
+    };
+    const mutationWalk = mutationAdmission
+        ? mutationWalkOptions(mutationAdmission, (prospectiveDirectory) => prospectiveDirectory, assertBeforeMutation)
+        : undefined;
+    try {
+        await mkdirPathComponentsWithGuards(mutationWalk ? {
+            ...baseParams,
+            ...mutationWalk.options,
+            rejectSymlinks: rejectSymlinks || mutationAdmission.rejectParentSymlinks,
+        } : baseParams);
+    }
+    finally {
+        mutationWalk?.dispose();
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { BigIntStats, Stats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { type RootContext } from "./root-context.js";
+import type { RootPathDirectoryObservationGuard, RootPathObservationReceipt, RootPathParentObservationReceipt } from "./root-path.js";
+import type { DirEntry, PathStat } from "./types.js";
+export declare function pathStatFromStats(stat: Stats | BigIntStats): PathStat;
+export type RootDirectoryObservationGuard = AsyncDirectoryGuard<BigIntStats>;
+export declare function createRootDirectoryObservationGuard(root: RootContext, directory: string): Promise<RootDirectoryObservationGuard>;
+export declare function assertRootDirectoryObservationGuard(root: RootContext, guard: RootDirectoryObservationGuard | RootPathDirectoryObservationGuard): Promise<void>;
+/**
+ * Close an operation-local traversal receipt with fresh exact observations.
+ * Descendant canonical paths are admitted while the receipt is created. The
+ * final directory check repeats canonical admission; the Root-only case does
+ * both its identity and canonical check here.
+ */
+export declare function assertRootPathObservationReceiptCurrent(root: RootContext, receipt: RootPathObservationReceipt | RootPathParentObservationReceipt, finalTarget?: Stats | BigIntStats): void;
+export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: true, receipt?: RootPathObservationReceipt): Promise<DirEntry[]>;
+export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: boolean, receipt?: RootPathObservationReceipt): Promise<string[] | DirEntry[]>;
+export type RootDirectoryListing = {
+    next(): Promise<{
+        kind: "entry";
+        entry: DirEntry;
+    } | {
+        kind: "limit";
+        name: string;
+    } | undefined>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export type RootDirectoryListingOptions = {
+    order: "sorted" | "filesystem";
+    signal?: AbortSignal;
+    snapshot: boolean;
+    maxNames?: number;
+    metadataBatchSize?: number;
+    admitEntry(): boolean;
+};
+export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+//# sourceMappingURL=root-directory-list.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/root-directory-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-directory-list.d.ts","sourceRoot":"","sources":["../src/root-directory-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAKvD,OAAO,EAKL,KAAK,mBAAmB,EAEzB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,KAAK,EACV,iCAAiC,EACjC,0BAA0B,EAC1B,gCAAgC,EACjC,MAAM,gBAAgB,CAAC;AAKxB,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,WAAW,GAAG,QAAQ,CAmBrE;AAED,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;AAE7E,wBAAsB,mCAAmC,CACvD,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,6BAA6B,CAAC,CAaxC;AASD,wBAAsB,mCAAmC,CACvD,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,6BAA6B,GAAG,iCAAiC,GACvE,OAAO,CAAC,IAAI,CAAC,CAuBf;AAiCD;;;;;GAKG;AACH,wBAAgB,uCAAuC,CACrD,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,0BAA0B,GAAG,gCAAgC,EACtE,WAAW,CAAC,EAAE,KAAK,GAAG,WAAW,GAChC,IAAI,CAgCN;AAkBD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,IAAI,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AACvB,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,OAAO,EACtB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;AAoElC,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAClG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAuI/B"}