@openclaw/signal 2026.9.5 → 2026.9.6

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

@@ -0,0 +1,186 @@
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
+export function sameNormalizedPathSpelling(left, right) {
+    // Preserve case on Windows, where individual directories can be case-sensitive.
+    return path.resolve(left) === path.resolve(right);
+}
+function windowsComparablePath(value, normalize) {
+    const original = normalize
+        ? path.win32.normalize(value.replaceAll("/", "\\"))
+        : value.replaceAll("/", "\\");
+    if (/^\\\\\?\\UNC\\/i.test(original)) {
+        return {
+            original,
+            comparison: `\\\\${original.slice(8)}`,
+            originalIndex: (comparisonIndex) => comparisonIndex + 6,
+        };
+    }
+    if (original.startsWith("\\\\?\\")) {
+        return {
+            original,
+            comparison: original.slice(4),
+            originalIndex: (comparisonIndex) => comparisonIndex + 4,
+        };
+    }
+    return { original, comparison: original, originalIndex: (comparisonIndex) => comparisonIndex };
+}
+function trimWindowsTrailingSeparators(value) {
+    const rootLength = path.win32.parse(value).root.length;
+    let end = value.length;
+    while (end > rootLength && value[end - 1] === "\\")
+        end -= 1;
+    return value.slice(0, end);
+}
+function trimWindowsLeadingSeparators(value) {
+    let start = 0;
+    while (value[start] === "\\")
+        start += 1;
+    return value.slice(start);
+}
+function exactWindowsRootPrefix(rootPath, candidatePath) {
+    const root = trimWindowsTrailingSeparators(rootPath.replaceAll("/", "\\"));
+    const candidate = candidatePath.replaceAll("/", "\\");
+    let relativePath;
+    if (candidate === root) {
+        relativePath = "";
+    }
+    else {
+        const rootWithSep = root.endsWith("\\") ? root : `${root}\\`;
+        if (!candidate.startsWith(rootWithSep))
+            return undefined;
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+    }
+    return {
+        admission: "exact",
+        candidateRootPath: root,
+        path: relativePath === "" ? root : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`,
+        relativePath,
+    };
+}
+function windowsRootPrefix(rootPath, candidatePath) {
+    const exact = exactWindowsRootPrefix(rootPath, candidatePath);
+    if (exact)
+        return exact;
+    const trusted = windowsComparablePath(rootPath, true);
+    const supplied = windowsComparablePath(candidatePath, false);
+    const root = trimWindowsTrailingSeparators(trusted.original);
+    const rootComparison = trimWindowsTrailingSeparators(trusted.comparison);
+    const candidate = supplied.comparison;
+    if (!path.win32.isAbsolute(supplied.original))
+        return undefined;
+    let relativePath;
+    let candidateRootPath;
+    let admission;
+    if (candidate === rootComparison) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "exact";
+    }
+    else if (candidate.toLowerCase() === rootComparison.toLowerCase()) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "identity";
+    }
+    else {
+        const rootWithSep = rootComparison.endsWith("\\") ? rootComparison : `${rootComparison}\\`;
+        const candidatePrefix = candidate.slice(0, rootWithSep.length);
+        if (candidatePrefix === rootWithSep) {
+            admission = "exact";
+        }
+        else if (candidatePrefix.toLowerCase() === rootWithSep.toLowerCase()) {
+            admission = "identity";
+        }
+        else {
+            return undefined;
+        }
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+        candidateRootPath = supplied.original.slice(0, supplied.originalIndex(rootComparison.length));
+    }
+    const rebasedPath = relativePath === ""
+        ? root
+        : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`;
+    return { candidateRootPath, path: rebasedPath, relativePath, admission };
+}
+function exactRootIdentity(rootPath, expected) {
+    if (typeof expected?.dev === "bigint" && typeof expected.ino === "bigint") {
+        return { dev: expected.dev, ino: expected.ino };
+    }
+    const observed = inspectDirectoryIdentitySync(rootPath);
+    return { dev: observed.dev, ino: observed.ino };
+}
+/**
+ * Admit a path at a trusted directory boundary.
+ *
+ * On Windows, an exact structural prefix is allocation-only and performs no
+ * filesystem observation. A match which depends on case folding is accepted
+ * only when the candidate prefix names the exact trusted root object. Accepted
+ * paths are always returned under the trusted root spelling.
+ */
+export function admitPathInsideRoot(params) {
+    // Some platform-fallback tests intentionally spoof process.platform while
+    // retaining Node's POSIX path module. A single-slash absolute root remains
+    // unambiguously POSIX; double-slash and slash-backslash roots are reserved
+    // for the synthetic Windows namespace cases below.
+    const usesPosixBoundary = process.platform !== "win32" || (path.sep === "/" &&
+        params.rootPath.startsWith("/") &&
+        params.rootPath[1] !== "/" &&
+        params.rootPath[1] !== "\\");
+    if (usesPosixBoundary) {
+        if (params.rootPath.startsWith("/") &&
+            params.candidatePath.startsWith("/") &&
+            !params.candidatePath.includes("/..") &&
+            (params.candidatePath === params.rootPath ||
+                (params.candidatePath.startsWith(params.rootPath) &&
+                    (params.rootPath.endsWith("/") || params.candidatePath[params.rootPath.length] === "/")))) {
+            const relativeStart = params.rootPath.endsWith("/")
+                ? params.rootPath.length
+                : params.rootPath.length + 1;
+            return {
+                admission: "exact",
+                path: params.candidatePath,
+                relativePath: params.candidatePath === params.rootPath
+                    ? ""
+                    : params.candidatePath.slice(relativeStart),
+            };
+        }
+        const root = path.resolve(params.rootPath);
+        const candidate = path.resolve(params.candidatePath);
+        const relativePath = path.relative(root, candidate);
+        if (isPathRelativeEscape(relativePath))
+            return undefined;
+        return { path: candidate, relativePath: relativePath === "." ? "" : relativePath, admission: "exact" };
+    }
+    const match = windowsRootPrefix(params.rootPath, params.candidatePath);
+    if (!match)
+        return undefined;
+    const admitted = () => ({
+        admission: match.admission,
+        path: match.path,
+        relativePath: match.relativePath,
+    });
+    if (match.admission === "exact")
+        return admitted();
+    const cached = params.identityCache?.get(match.candidateRootPath);
+    if (cached !== undefined)
+        return cached ? admitted() : undefined;
+    try {
+        const expected = exactRootIdentity(params.rootPath, params.rootIdentity);
+        const candidateRootPath = params.resolveCandidateRoot
+            ? realpathSync.native(match.candidateRootPath)
+            : match.candidateRootPath;
+        if (params.inspectCandidateRoot) {
+            params.inspectCandidateRoot(candidateRootPath, expected);
+        }
+        else {
+            inspectDirectoryIdentitySync(candidateRootPath, expected);
+        }
+        params.identityCache?.set(match.candidateRootPath, true);
+        return admitted();
+    }
+    catch {
+        params.identityCache?.set(match.candidateRootPath, false);
+        return undefined;
+    }
+}

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

@@ -0,0 +1,43 @@
+import fs, { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard, type DirectoryObservationGuard } from "./directory-guard.js";
+export type RootContext = {
+    rootDir: string;
+    rootGuard?: AsyncDirectoryGuard<BigIntStats>;
+    rootIdentity: {
+        dev: number;
+        ino: number;
+    } | {
+        dev: bigint;
+        ino: bigint;
+    };
+    rootReal: string;
+    rootWithSep: string;
+};
+export declare const ensureTrailingSep: (value: string) => string;
+export declare function assertValidRootRelativePath(relativePath: string): void;
+export declare function assertValidRootDestinationPath(relativePath: string): void;
+export declare function expandRelativePathWithHome(relativePath: string): Promise<string>;
+export declare function resolveRootContext(rootDir: string): Promise<RootContext>;
+export declare function rootRelativeReadPath(root: RootContext, filePath: string): string;
+export declare function assertRootIdentityCurrentSync(root: RootContext, observe?: (stat: fs.BigIntStats) => void): void;
+export declare function assertRootIdentityCurrent(root: RootContext, observe?: (stat: fs.BigIntStats) => void): Promise<void>;
+/**
+ * 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 declare function createRootObservationGuard(root: RootContext): Promise<DirectoryObservationGuard | undefined>;
+export declare function resolvePathInRoot(root: RootContext, relativePath: string, options?: {
+    aliasErrorCode?: "outside-workspace" | "path-alias";
+    allowFinalSymlink?: boolean;
+    rejectUnsafeDeviceReads?: boolean;
+    rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
+    resolveCanonical?: boolean;
+    rejectAmbiguousParents?: boolean;
+}): Promise<{
+    rootReal: string;
+    rootWithSep: string;
+    resolved: string;
+}>;

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

@@ -0,0 +1,232 @@
+import fs, {} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { extendDirectoryObservationGuard, inspectDirectoryIdentitySync, inspectDirectoryObservationSync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { errorCauseOptions, 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);
+    if (isDriveRelativePath(relativePath)) {
+        throw new FsSafeError("invalid-path", "relative path must not start with a drive letter");
+    }
+}
+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 = realpathSync.native(pathForWindowsFilesystem(rawHome));
+        }
+        catch {
+            // If the home dir cannot be canonicalized, keep lexical expansion behavior.
+        }
+        cachedHomePath = { raw: rawHome, real: realHome };
+    }
+    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 = 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) {
+        if (err instanceof FsSafeError) {
+            throw err;
+        }
+        if (isNotFoundPathError(err)) {
+            throw new FsSafeError("not-found", "root dir not found");
+        }
+        throw err;
+    }
+    return {
+        rootDir: lexicalRoot,
+        rootGuard: { dir: rootReal, realPath: rootReal, stat: rootStat },
+        rootIdentity,
+        rootReal,
+        rootWithSep: ensureTrailingSep(rootReal),
+    };
+}
+export function rootRelativeReadPath(root, filePath) {
+    const absoluteInput = path.isAbsolute(filePath);
+    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 function assertRootIdentityCurrentSync(root, observe) {
+    let current;
+    try {
+        if (typeof root.rootIdentity.dev === "bigint" && typeof root.rootIdentity.ino === "bigint") {
+            const stat = inspectDirectoryIdentitySync(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            observe?.(stat);
+            return;
+        }
+        current = fs.lstatSync(root.rootReal);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
+    }
+    if (current.isSymbolicLink() ||
+        !current.isDirectory() ||
+        !sameFileIdentity(current, root.rootIdentity)) {
+        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);
+    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) {
+        assertNoUnsafeDeviceReadPath(resolved);
+    }
+    const rawAbsolutePath = path.isAbsolute(expanded)
+        ? expanded
+        : `${root.rootWithSep}${expanded}`;
+    assertNoWindowsPathAlias(rawAbsolutePath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
+    try {
+        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") {
+            throw error;
+        }
+        if (hasNodeErrorCode(error, "ENAMETOOLONG")) {
+            throw new FsSafeError("invalid-path", "relative path is too long", errorCauseOptions(error));
+        }
+        const code = options?.aliasErrorCode ?? "outside-workspace";
+        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", errorCauseOptions(error));
+    }
+    return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
+}

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

@@ -0,0 +1,16 @@
+import type { PinnedWriteInput } from "./pinned-write-types.js";
+import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
+declare const exclusiveSidecarCreate: unique symbol;
+export declare const sidecarExclusiveCreate: Readonly<{
+    [exclusiveSidecarCreate]: true;
+}>;
+export type RootWriteParams = RootWriteOptions & RootCreateOptions & RootCreateStreamOptions & {
+    relativePath: string;
+    data: string | Buffer | AsyncIterable<Uint8Array>;
+    strictFileSync?: boolean;
+    [exclusiveSidecarCreate]?: true;
+};
+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;
+export {};

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

@@ -0,0 +1,93 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
+// Lock records need exclusive creation, not private-before-visible publication.
+// Keep this composition hook off the public Root options and package exports.
+const exclusiveSidecarCreate = Symbol("exclusiveSidecarCreate");
+export const sidecarExclusiveCreate = Object.freeze({ [exclusiveSidecarCreate]: true });
+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;
+    const { signal } = 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 });
+    const { assertBeforeMutation } = options;
+    return {
+        ...options,
+        maxBytes,
+        signal,
+        assertBeforeMutation: () => {
+            signal?.throwIfAborted();
+            return assertBeforeMutation == null ? undefined : Reflect.apply(assertBeforeMutation, options, []);
+        },
+    };
+}
+export function rootWriteInput(params) {
+    if (params.atomic !== undefined && typeof params.atomic !== "boolean") {
+        throw new TypeError("atomic must be a boolean");
+    }
+    const data = params.data;
+    if (typeof data === "string" || Buffer.isBuffer(data)) {
+        return {
+            kind: "buffer", data, encoding: params.encoding,
+            stageBeforePublish: params[exclusiveSidecarCreate] ? false : params.atomic === true ? true : undefined,
+        };
+    }
+    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,12 @@
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.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, privateMode?: boolean): Promise<string>;
+export declare function mkdirPathFallback(root: RootContext, resolved: {
+    rootReal: string;
+    resolved: string;
+}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<void>;