@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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 = {
+    assertCurrent(): Promise<void>;
+    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>;

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

@@ -0,0 +1,382 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { assertAsyncDirectoryGuard, assertDirectoryObservationGuardSync, assertDirectoryObservationSync, createAsyncDirectoryGuard, extendDirectoryObservationGuard, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { realpathSync } from "./realpath.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+const METADATA_BATCH_SIZE = 32;
+export function pathStatFromStats(stat) {
+    const mtimeMs = typeof stat.mtimeMs === "bigint"
+        ? "mtimeNs" in stat && typeof stat.mtimeNs === "bigint"
+            ? Number(stat.mtimeNs) / 1_000_000
+            : stat.mtime.getTime()
+        : stat.mtimeMs;
+    return {
+        dev: Number(stat.dev),
+        gid: Number(stat.gid),
+        ino: Number(stat.ino),
+        isDirectory: stat.isDirectory(),
+        isFile: stat.isFile(),
+        isSymbolicLink: stat.isSymbolicLink(),
+        mode: Number(stat.mode),
+        mtimeMs,
+        nlink: Number(stat.nlink),
+        size: Number(stat.size),
+        uid: Number(stat.uid),
+    };
+}
+export async function createRootDirectoryObservationGuard(root, directory) {
+    const guard = await createAsyncDirectoryGuard(directory, { bigint: true });
+    const admittedRealPath = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: guard.realPath,
+        rootIdentity: root.rootIdentity,
+    });
+    if (!admittedRealPath) {
+        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
+    }
+    guard.dir = admittedRealPath.path;
+    guard.realPath = admittedRealPath.path;
+    return guard;
+}
+function directoryChangedError(error) {
+    if (error instanceof FsSafeError && error.code === "path-mismatch")
+        return error;
+    return new FsSafeError("path-mismatch", "directory changed during operation", errorCauseOptions(error));
+}
+export async function assertRootDirectoryObservationGuard(root, guard) {
+    if (isNativeDirectoryObservationGuard(guard)) {
+        throw new FsSafeError("path-mismatch", "native directory observation cannot be revalidated");
+    }
+    const identity = "identity" in guard ? guard.identity : guard.stat;
+    const guardPinsRoot = guard.dir === root.rootReal &&
+        identity.dev === root.rootIdentity.dev && identity.ino === root.rootIdentity.ino;
+    if (guardPinsRoot) {
+        try {
+            if ("identity" in guard)
+                assertDirectoryObservationGuardSync(guard);
+            else
+                await assertAsyncDirectoryGuard(guard);
+        }
+        catch (error) {
+            throw rootPathChangedError(error instanceof Error ? error : undefined);
+        }
+        return;
+    }
+    if ("identity" in guard && typeof root.rootIdentity.dev === "bigint" &&
+        typeof root.rootIdentity.ino === "bigint") {
+        try {
+            assertDirectoryObservationSync(root.rootReal, root.rootIdentity);
+        }
+        catch (error) {
+            throw rootPathChangedError(error instanceof Error ? error : undefined);
+        }
+    }
+    else {
+        await assertRootIdentityCurrent(root);
+    }
+    try {
+        if ("identity" in guard)
+            assertDirectoryObservationGuardSync(guard);
+        else
+            await assertAsyncDirectoryGuard(guard);
+    }
+    catch (error) {
+        throw directoryChangedError(error);
+    }
+}
+function sameObservationDirectory(left, right) {
+    return left.dir === right.dir && left.realPath === right.realPath &&
+        left.identity.dev === right.identity.dev && left.identity.ino === right.identity.ino;
+}
+function assertReceiptDirectoryGuardSync(root, guard, backend) {
+    if (backend) {
+        const observed = inspectNativeDirectoryObservation(backend, guard.dir, guard.identity);
+        const admitted = admitPathInsideRoot({
+            rootPath: root.rootReal,
+            candidatePath: observed.realPath,
+            rootIdentity: root.rootIdentity,
+        });
+        if (!admitted || admitted.path !== guard.realPath) {
+            throw new FsSafeError("path-mismatch", "directory changed during operation");
+        }
+        return;
+    }
+    if (isNativeDirectoryObservationGuard(guard)) {
+        throw new FsSafeError("path-mismatch", "native directory observation cannot be revalidated");
+    }
+    assertDirectoryObservationGuardSync(guard);
+}
+/**
+ * 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 function assertRootPathObservationReceiptCurrent(root, receipt, finalTarget) {
+    const { rootGuard, directoryGuard } = receipt;
+    if (rootGuard.dir !== root.rootReal || rootGuard.realPath !== root.rootReal ||
+        rootGuard.identity.dev !== root.rootIdentity.dev || rootGuard.identity.ino !== root.rootIdentity.ino) {
+        throw rootPathChangedError();
+    }
+    if (sameObservationDirectory(rootGuard, directoryGuard)) {
+        try {
+            if (receipt.kind === "stat" && receipt.target === rootGuard && finalTarget &&
+                !receipt.directoryObserver) {
+                if (finalTarget.isSymbolicLink() || !finalTarget.isDirectory() ||
+                    realpathSync.native(rootGuard.dir) !== rootGuard.realPath) {
+                    throw new FsSafeError("path-mismatch", "root path changed during operation");
+                }
+            }
+            else {
+                assertReceiptDirectoryGuardSync(root, directoryGuard, receipt.directoryObserver);
+            }
+        }
+        catch (error) {
+            throw rootPathChangedError(error instanceof Error ? error : undefined);
+        }
+        return;
+    }
+    try {
+        assertDirectoryObservationSync(rootGuard.dir, rootGuard.identity);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
+    }
+    try {
+        assertReceiptDirectoryGuardSync(root, directoryGuard, receipt.directoryObserver);
+    }
+    catch (error) {
+        throw directoryChangedError(error);
+    }
+}
+function normalizeDirectoryError(error) {
+    if (isNotFoundPathError(error)) {
+        return new FsSafeError("not-found", "directory not found", errorCauseOptions(error));
+    }
+    return error;
+}
+function normalizeInitialDirectoryError(error) {
+    if (error instanceof FsSafeError && error.code === "not-file") {
+        return new FsSafeError("not-found", "directory not found", { cause: error });
+    }
+    return normalizeDirectoryError(error);
+}
+export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
+    let guard;
+    if (receipt) {
+        if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
+            receipt.directoryGuard.dir !== directory ||
+            receipt.target !== receipt.directoryGuard ||
+            (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
+                !receipt.directoryGuard.stat.isDirectory())) {
+            throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
+        }
+        guard = receipt.directoryGuard;
+    }
+    else {
+        try {
+            guard = await createRootDirectoryObservationGuard(root, directory);
+        }
+        catch (error) {
+            throw normalizeInitialDirectoryError(error);
+        }
+    }
+    return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);
+}
+async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
+    let entries;
+    try {
+        const beforeObservation = getFsSafeTestHooks()?.beforeRootListObservation;
+        if (beforeObservation)
+            await beforeObservation(guard.realPath, withFileTypes);
+        const names = (await fs.readdir(guard.realPath)).sort();
+        entries = withFileTypes
+            ? names.map(name => ({
+                name,
+                ...pathStatFromStats(fsSync.lstatSync(path.join(guard.realPath, name))),
+            }))
+            : names;
+    }
+    catch (error) {
+        // Preserve ordinary observation errors only while the admitted directory is
+        // still current. A post-admission replacement is an identity failure.
+        if (receipt)
+            assertRootPathObservationReceiptCurrent(root, receipt);
+        else
+            await assertRootDirectoryObservationGuard(root, guard);
+        throw normalizeDirectoryError(error);
+    }
+    if (receipt)
+        assertRootPathObservationReceiptCurrent(root, receipt);
+    else
+        await assertRootDirectoryObservationGuard(root, guard);
+    return entries;
+}
+export async function openRootDirectoryListing(root, directory, options) {
+    const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
+        throw normalizeDirectoryError(error);
+    });
+    // Retain exact admission identities; metadata rechecks can use numeric Stats
+    // only when every identity component is losslessly representable.
+    const guard = extendDirectoryObservationGuard({
+        stat: admitted.stat,
+        identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
+    }, admitted.dir, admitted.realPath);
+    const assertCurrent = async () => {
+        options.signal?.throwIfAborted();
+        await assertRootDirectoryObservationGuard(root, guard);
+        options.signal?.throwIfAborted();
+    };
+    let handle;
+    let names;
+    let snapshot;
+    let index = 0;
+    let prepared = [];
+    let preparedIndex = 0;
+    let pendingFailure;
+    let pendingLimit;
+    let preparedBatch = false;
+    const close = async () => {
+        const owned = handle;
+        handle = undefined;
+        await owned?.close();
+    };
+    try {
+        await assertCurrent();
+        if (options.order === "filesystem") {
+            // A one-entry buffer keeps the truncation lookahead independent of width.
+            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+        }
+        else if (options.snapshot) {
+            snapshot = await listGuardedDirectoryPath(root, guard, true);
+        }
+        else if (options.maxNames !== undefined) {
+            names = [];
+            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            while (true) {
+                await assertCurrent();
+                const name = (await handle.read())?.name;
+                await assertCurrent();
+                if (name === undefined)
+                    break;
+                if (names.length >= options.maxNames) {
+                    throw new FsSafeError("too-large", "directory entry budget exceeded");
+                }
+                names.push(name);
+            }
+            await close();
+        }
+        else {
+            names = await fs.readdir(guard.realPath);
+        }
+        await assertCurrent();
+        names?.sort();
+    }
+    catch (error) {
+        const operationError = normalizeDirectoryError(error);
+        try {
+            await close();
+        }
+        catch (closeError) {
+            throw createSuppressedError(closeError, operationError, "directory setup and close both failed");
+        }
+        throw operationError;
+    }
+    const prepareBatch = async (sortedNames) => {
+        let name = sortedNames[index++];
+        if (name === undefined) {
+            await assertCurrent();
+            return;
+        }
+        if (!options.admitEntry()) {
+            pendingLimit = name;
+            return;
+        }
+        if (preparedBatch)
+            await yieldToEventLoop();
+        await assertCurrent();
+        preparedBatch = true;
+        prepared = [];
+        preparedIndex = 0;
+        while (true) {
+            try {
+                const entry = { name, ...pathStatFromStats(fsSync.lstatSync(path.join(guard.realPath, name))) };
+                prepared.push(entry);
+                // No later sibling can be observed before a possible recursive descent.
+                if (entry.isDirectory || entry.isSymbolicLink || prepared.length >= (options.metadataBatchSize ?? METADATA_BATCH_SIZE))
+                    break;
+            }
+            catch (error) {
+                pendingFailure = { error: normalizeDirectoryError(error) };
+                break;
+            }
+            name = sortedNames[index++];
+            if (name === undefined)
+                break;
+            if (!options.admitEntry()) {
+                pendingLimit = name;
+                break;
+            }
+        }
+        try {
+            await assertCurrent();
+        }
+        catch (error) {
+            if (pendingFailure) {
+                throw createSuppressedError(error, pendingFailure.error, "directory observation and identity checks both failed");
+            }
+            throw error;
+        }
+    };
+    return {
+        assertCurrent,
+        async next() {
+            try {
+                options.signal?.throwIfAborted();
+                if (snapshot) {
+                    const entry = snapshot[index++];
+                    if (!entry)
+                        return;
+                    return options.admitEntry() ? { kind: "entry", entry } : { kind: "limit", name: entry.name };
+                }
+                if (names) {
+                    if (preparedIndex >= prepared.length && !pendingFailure && pendingLimit === undefined) {
+                        await prepareBatch(names);
+                    }
+                    const entry = prepared[preparedIndex++];
+                    if (entry)
+                        return { kind: "entry", entry };
+                    if (pendingFailure)
+                        throw pendingFailure.error;
+                    if (pendingLimit !== undefined)
+                        return { kind: "limit", name: pendingLimit };
+                    return;
+                }
+                await assertCurrent();
+                const name = (await handle.read())?.name;
+                await assertCurrent();
+                if (name === undefined)
+                    return;
+                if (!options.admitEntry())
+                    return { kind: "limit", name };
+                // The stream's post-read fence is also the pre-stat fence in this owned operation.
+                const stat = fsSync.lstatSync(path.join(guard.realPath, name));
+                await assertCurrent();
+                return { kind: "entry", entry: { name, ...pathStatFromStats(stat) } };
+            }
+            catch (error) {
+                throw normalizeDirectoryError(error);
+            }
+        },
+        [Symbol.asyncDispose]: close,
+    };
+}

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

@@ -0,0 +1,22 @@
+import { FsSafeError } from "./errors.js";
+export type DirectoryResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+    diagnostic?: FsSafeError;
+};
+export declare function resolveNearestExistingPath(targetPath: string): string;
+export declare function assertNoSymlinkSegments(params: {
+    rootDir: string;
+    targetPath: string;
+    scopeLabel: string;
+}): Promise<void>;
+export declare function ensureDirectoryWithinRoot(params: {
+    rootDir: string;
+    requestedPath: string;
+    scopeLabel: string;
+    defaultDirName?: string;
+    mode?: number;
+}): Promise<DirectoryResult>;

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

@@ -0,0 +1,141 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { formatErrorDetail } from "./error-detail.js";
+import { FsSafeError } from "./errors.js";
+import { assertNoNulPathInput, hasNodeErrorCode, isNodeError, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { resolvePathWithinRoot } from "./root-paths-lexical.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function invalidPath(scopeLabel) {
+    return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+}
+export function resolveNearestExistingPath(targetPath) {
+    assertNoWindowsPathAlias(targetPath);
+    let current = resolvePathPreservingWindowsRoot(targetPath);
+    assertNoWindowsPathAlias(current);
+    while (true) {
+        try {
+            fsSync.lstatSync(pathForWindowsFilesystem(current));
+            return current;
+        }
+        catch (err) {
+            if (!isNotFoundPathError(err))
+                throw err;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`failed to resolve existing path for ${targetPath}`);
+        }
+        current = parent;
+    }
+}
+export async function assertNoSymlinkSegments(params) {
+    const relative = path.relative(params.rootDir, params.targetPath);
+    if (isPathRelativeEscape(relative)) {
+        throw new FsSafeError("outside-workspace", `Invalid path: must stay within ${params.scopeLabel}`);
+    }
+    let current = params.rootDir;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = fsSync.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `Invalid path: must not traverse symlinks within ${params.scopeLabel}`);
+            }
+            if (!stat.isDirectory()) {
+                throw new FsSafeError("not-file", `Invalid path: existing segment must be a directory within ${params.scopeLabel}`);
+            }
+        }
+        catch (err) {
+            if (isNotFoundPathError(err))
+                return;
+            throw err;
+        }
+    }
+}
+export async function ensureDirectoryWithinRoot(params) {
+    const scopeLabel = formatErrorDetail(params.scopeLabel.slice(0, 80));
+    try {
+        const rootDirInput = params.rootDir;
+        const requestedPathInput = params.requestedPath;
+        const useDefault = !requestedPathInput.trim();
+        const defaultDirName = useDefault ? params.defaultDirName : undefined;
+        const mode = params.mode;
+        assertNoNulPathInput(rootDirInput);
+        assertNoNulPathInput(requestedPathInput);
+        if (useDefault)
+            assertNoNulPathInput(defaultDirName ?? "");
+        assertNoWindowsPathAlias(rootDirInput);
+        assertNoWindowsPathAlias(requestedPathInput);
+        if (useDefault)
+            assertNoWindowsPathAlias(defaultDirName ?? "");
+        const lexical = resolvePathWithinRoot({
+            rootDir: rootDirInput,
+            requestedPath: requestedPathInput,
+            scopeLabel,
+            defaultFileName: defaultDirName,
+        });
+        if (!lexical.ok)
+            return lexical;
+        const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+        const targetPath = lexical.path;
+        const rootStat = fsSync.lstatSync(pathForWindowsFilesystem(rootDir));
+        if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
+            return invalidPath(scopeLabel);
+        await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
+        const rootReal = realpathSync.native(pathForWindowsFilesystem(rootDir));
+        assertNoWindowsPathAlias(rootReal);
+        const nearestExistingPath = resolveNearestExistingPath(targetPath);
+        const nearestExistingReal = realpathSync.native(pathForWindowsFilesystem(nearestExistingPath));
+        assertNoWindowsPathAlias(nearestExistingReal);
+        if (!isPathInside(rootReal, nearestExistingReal))
+            return invalidPath(scopeLabel);
+        const relative = path.relative(rootDir, targetPath);
+        let current = rootDir;
+        for (const segment of relative.split(path.sep).filter(Boolean)) {
+            current = path.join(current, segment);
+            while (true) {
+                try {
+                    const stat = fsSync.lstatSync(current);
+                    if (stat.isSymbolicLink() || !stat.isDirectory())
+                        return invalidPath(scopeLabel);
+                    break;
+                }
+                catch (err) {
+                    if (!isNotFoundPathError(err))
+                        throw err;
+                    try {
+                        await fs.mkdir(current, { mode });
+                    }
+                    catch (mkdirErr) {
+                        if (hasNodeErrorCode(mkdirErr, "EEXIST"))
+                            continue;
+                        throw mkdirErr;
+                    }
+                }
+            }
+            const currentReal = realpathSync.native(current);
+            assertNoWindowsPathAlias(currentReal);
+            if (!isPathInside(rootReal, currentReal))
+                return invalidPath(scopeLabel);
+        }
+        const targetReal = realpathSync.native(pathForWindowsFilesystem(targetPath));
+        assertNoWindowsPathAlias(targetReal);
+        if (!isPathInside(rootReal, targetReal))
+            return invalidPath(scopeLabel);
+        return { ok: true, path: targetPath };
+    }
+    catch (cause) {
+        if ((cause instanceof FsSafeError && cause.category === "policy") ||
+            hasNodeErrorCode(cause, "ENOTDIR")) {
+            return invalidPath(scopeLabel);
+        }
+        const code = isNodeError(cause) && typeof cause.code === "string"
+            ? formatErrorDetail(cause.code.slice(0, 40)) : "filesystem operation failed";
+        const syscall = isNodeError(cause) && typeof cause.syscall === "string"
+            ? ` during ${formatErrorDetail(cause.syscall.slice(0, 40))}` : "";
+        const diagnostic = new FsSafeError("helper-failed", `Could not prepare ${scopeLabel}: ${code}${syscall}`, { cause });
+        return { ok: false, error: diagnostic.message, diagnostic };
+    }
+}

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

@@ -0,0 +1,10 @@
+import { type RootContext } from "./root-context.js";
+import { type SymlinkPolicy } from "./root-symlink-policy.js";
+import type { DirEntry } from "./types.js";
+export type RootEntriesOptions = {
+    maxEntries?: number;
+    order?: "filesystem" | "sorted";
+    signal?: AbortSignal;
+    symlinks?: SymlinkPolicy;
+};
+export declare function entriesInRoot(root: RootContext, relativePath: string, options: RootEntriesOptions): AsyncGenerator<DirEntry>;

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

@@ -0,0 +1,61 @@
+import { FsSafeError } from "./errors.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
+import { resolvePathInRoot } from "./root-context.js";
+import { openRootDirectoryListing } from "./root-directory-list.js";
+import { readSymlinkResolution } from "./root-symlink-policy.js";
+import { createSuppressedError } from "./suppressed-error.js";
+export async function* entriesInRoot(root, relativePath, options) {
+    const maxEntries = options.maxEntries;
+    if (maxEntries !== undefined && (!Number.isSafeInteger(maxEntries) || maxEntries < 0)) {
+        throw new RangeError("maxEntries must be a non-negative safe integer");
+    }
+    if (options.order !== undefined && options.order !== "filesystem" && options.order !== "sorted") {
+        throw new TypeError(`invalid root entries order: ${String(options.order)}`);
+    }
+    options.signal?.throwIfAborted();
+    validatePinnedRelativePath(relativePath);
+    const resolved = await resolvePathInRoot(root, relativePath, {
+        ...readSymlinkResolution(options.symlinks),
+        resolveCanonical: true,
+    });
+    options.signal?.throwIfAborted();
+    let examined = 0;
+    const listing = await openRootDirectoryListing(root, resolved.resolved, {
+        order: options.order ?? "filesystem",
+        signal: options.signal,
+        snapshot: false,
+        maxNames: maxEntries,
+        metadataBatchSize: 1,
+        admitEntry: () => maxEntries === undefined || examined++ < maxEntries,
+    });
+    let failed = false;
+    let operationError;
+    try {
+        while (true) {
+            const next = await listing.next();
+            options.signal?.throwIfAborted();
+            if (next === undefined)
+                return;
+            if (next.kind === "limit") {
+                throw new FsSafeError("too-large", "directory entry budget exceeded");
+            }
+            yield next.entry;
+        }
+    }
+    catch (error) {
+        failed = true;
+        operationError = error;
+        throw error;
+    }
+    finally {
+        try {
+            await listing[Symbol.asyncDispose]();
+        }
+        catch (closeError) {
+            if (failed) {
+                throw createSuppressedError(closeError, operationError, "directory iteration and close both failed");
+            }
+            throw closeError;
+        }
+    }
+}

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

@@ -1,12 +1,16 @@
-import { FsSafeError } from "./errors.js";
-export declare function fileNotFoundError(cause?: unknown): FsSafeError;
+import { FsSafeError, type FsSafeErrorDetails } from "./errors.js";
+export declare function fileNotFoundError(cause?: unknown, details?: FsSafeErrorDetails): FsSafeError;
 export declare function outsideWorkspaceError(): FsSafeError;
+export declare function rootPathChangedError(cause?: Error): FsSafeError;
 export declare function directoryComponentNotDirectoryError(cause?: unknown): FsSafeError;
 export declare function hardlinkedPathNotAllowedError(): FsSafeError;
 export declare function isAlreadyExistsError(error: unknown): boolean;
 export declare function normalizePinnedWriteError(error: unknown): Error;
-export declare function normalizePinnedPathError(error: unknown): Error;
-export declare function normalizeRemoveGuardError(error: unknown): Error;
-export declare function normalizeRemovePathError(error: unknown): Error;
+export declare function normalizePinnedPathError(error: unknown, details?: FsSafeErrorDetails): Error;
+export declare function normalizeRemoveGuardError(error: unknown, details?: FsSafeErrorDetails): Error;
+export declare function normalizeRemovePathError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function throwFsSafeReadError(error: unknown, label: string): never;
-//# sourceMappingURL=root-errors.d.ts.map
+/** Existing boundaries retain only Error instances as their cause. */
+export declare function errorCauseOptions(error: unknown): {
+    cause: Error | undefined;
+};