@openclaw/openshell-sandbox 2026.9.2 → 2026.9.4

package/node_modules/@openclaw/fs-safe/dist/json.js

@@ -0,0 +1,343 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import path from "node:path";
+import { readFileDescriptorBoundedSync } from "./bounded-read.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { stringifyJsonDocument } from "./json-stringify.js";
+import { readRegularFile, readRegularFileSync, statRegularFile } from "./regular-file.js";
+import { openRootFileSync } from "./root-file.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { writeTextAtomic } from "./text-atomic.js";
+import { sleep } from "./timing.js";
+const READ_RETRY_MAX_ATTEMPTS = 5;
+const READ_RETRY_BASE_DELAY_MS = 50;
+function isRetryableReadError(err, options) {
+    if (err instanceof FsSafeError && err.code === "path-mismatch") {
+        return true;
+    }
+    if (options.retryOpenRaceErrors !== true) {
+        return false;
+    }
+    const code = getErrorCode(err);
+    return code === "ENOENT" || code === "EPERM";
+}
+async function readRegularFileWithRetry(filePath, options = {}) {
+    let lastErr;
+    for (let attempt = 0; attempt < READ_RETRY_MAX_ATTEMPTS; attempt++) {
+        try {
+            return (await readRegularFile({ filePath, maxBytes: options.maxBytes })).buffer;
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isRetryableReadError(err, options) || attempt === READ_RETRY_MAX_ATTEMPTS - 1) {
+                throw err;
+            }
+            await sleep(READ_RETRY_BASE_DELAY_MS * Math.pow(2, attempt));
+        }
+    }
+    throw lastErr;
+}
+async function readRegularFileIfExistsWithRetry(filePath, options = {}) {
+    const initial = await statRegularFile(filePath);
+    if (initial.missing) {
+        return null;
+    }
+    return await readRegularFileWithRetry(filePath, {
+        maxBytes: options.maxBytes,
+        retryOpenRaceErrors: true,
+    });
+}
+const JSON_FILE_MODE = 0o600;
+const JSON_DIR_MODE = 0o700;
+function getErrorCode(err) {
+    return err instanceof Error ? err.code : undefined;
+}
+function trySetSecureMode(pathname, expectedIdentity) {
+    let fd;
+    try {
+        const before = fsSync.lstatSync(pathname, { bigint: true });
+        if (before.isSymbolicLink() ||
+            !before.isFile() ||
+            before.nlink !== 1n ||
+            !sameFileIdentityForCleanup(before, expectedIdentity)) {
+            return;
+        }
+        fd = fsSync.openSync(pathname, resolveReadOpenFlags());
+        const opened = fsSync.fstatSync(fd, { bigint: true });
+        const current = fsSync.lstatSync(pathname, { bigint: true });
+        if (!opened.isFile() ||
+            opened.nlink !== 1n ||
+            current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(opened, expectedIdentity) ||
+            !sameFileIdentityForCleanup(current, opened)) {
+            return;
+        }
+        fsSync.fchmodSync(fd, JSON_FILE_MODE);
+    }
+    catch {
+        // Best-effort mode application never falls back to a mutable pathname.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function trySyncDirectory(pathname) {
+    let fd;
+    try {
+        fd = fsSync.openSync(path.dirname(pathname), "r");
+        fsSync.fsyncSync(fd);
+    }
+    catch {
+        // best-effort; some platforms/filesystems do not support syncing directories.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function renameJsonFileWithFallback(tmpPath, pathname) {
+    try {
+        fsSync.renameSync(tmpPath, pathname);
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EPERM" || code === "EEXIST") {
+            const existing = (() => {
+                try {
+                    return fsSync.lstatSync(pathname);
+                }
+                catch (lstatError) {
+                    if (lstatError.code === "ENOENT") {
+                        return null;
+                    }
+                    throw lstatError;
+                }
+            })();
+            if (existing?.isSymbolicLink()) {
+                fsSync.rmSync(pathname, { force: true });
+                fsSync.renameSync(tmpPath, pathname);
+                return;
+            }
+            fsSync.rmSync(pathname, { force: true });
+            fsSync.renameSync(tmpPath, pathname);
+            return;
+        }
+        throw error;
+    }
+}
+function writeTempJsonFile(pathname, payload) {
+    const fd = fsSync.openSync(pathname, "wx", JSON_FILE_MODE);
+    try {
+        fsSync.writeFileSync(fd, payload, "utf8");
+        fsSync.fsyncSync(fd);
+        return fsSync.fstatSync(fd, { bigint: true });
+    }
+    finally {
+        fsSync.closeSync(fd);
+    }
+}
+export function tryReadJsonSync(pathname, options = {}) {
+    try {
+        const raw = readRegularFileSync({
+            filePath: pathname,
+            maxBytes: options.maxBytes,
+        }).buffer.toString("utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeJsonSync(pathname, data) {
+    // Keep literal parent segments so staging follows the same symlinks as the target.
+    const tmpPath = path.format({ ...path.parse(pathname), base: `.fs-safe-${randomUUID()}.tmp` });
+    const payload = `${stringifyJsonDocument(data, null, 2)}\n`;
+    fsSync.mkdirSync(path.dirname(pathname), { recursive: true, mode: JSON_DIR_MODE });
+    try {
+        const tempIdentity = writeTempJsonFile(tmpPath, payload);
+        trySetSecureMode(tmpPath, tempIdentity);
+        renameJsonFileWithFallback(tmpPath, pathname);
+        trySetSecureMode(pathname, tempIdentity);
+        trySyncDirectory(pathname);
+    }
+    finally {
+        try {
+            fsSync.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup when rename does not happen
+        }
+    }
+}
+export class JsonFileReadError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason, cause) {
+        super(`Failed to ${reason} JSON file: ${filePath}`, { cause });
+        this.name = "JsonFileReadError";
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveInvalidMessage(invalidMessage, relativePath) {
+    if (typeof invalidMessage === "function") {
+        return invalidMessage(relativePath);
+    }
+    return invalidMessage ?? `${relativePath} has an unexpected shape`;
+}
+export function readRootStructuredFileSync(options) {
+    const absolutePath = path.resolve(options.rootDir, options.relativePath);
+    const opened = openRootFileSync({
+        absolutePath,
+        rootPath: options.rootDir,
+        ...(options.rootRealPath !== undefined ? { rootRealPath: options.rootRealPath } : {}),
+        boundaryLabel: options.boundaryLabel,
+        rejectHardlinks: options.rejectHardlinks,
+        maxBytes: options.maxBytes,
+        allowedType: "file",
+    });
+    if (!opened.ok) {
+        return { ok: false, reason: "open", failure: opened };
+    }
+    try {
+        const raw = options.maxBytes === undefined
+            ? fsSync.readFileSync(opened.fd, "utf8")
+            : readFileDescriptorBoundedSync(opened.fd, options.maxBytes).toString("utf8");
+        const parsed = options.parse(raw);
+        if (options.validate && !options.validate(parsed)) {
+            return {
+                ok: false,
+                reason: "invalid",
+                error: resolveInvalidMessage(options.invalidMessage, options.relativePath),
+            };
+        }
+        return {
+            ok: true,
+            value: parsed,
+            stat: opened.stat,
+            path: opened.path,
+            rootRealPath: opened.rootRealPath,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "parse",
+            error: `failed to parse ${options.relativePath}: ${String(error)}`,
+        };
+    }
+    finally {
+        fsSync.closeSync(opened.fd);
+    }
+}
+export function readRootJsonSync(options) {
+    return readRootStructuredFileSync({
+        ...options,
+        parse: (raw) => JSON.parse(raw),
+    });
+}
+export function readRootJsonObjectSync(options) {
+    return readRootStructuredFileSync({
+        ...options,
+        parse: (raw) => JSON.parse(raw),
+        validate: isRecord,
+        invalidMessage: (relativePath) => `${relativePath} must contain a JSON object`,
+    });
+}
+export async function tryReadJson(filePath, options = {}) {
+    try {
+        const buffer = await readRegularFileIfExistsWithRetry(filePath, options);
+        if (buffer === null) {
+            return null;
+        }
+        const raw = buffer.toString("utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readJson(filePath, options = {}) {
+    let raw;
+    try {
+        raw = (await readRegularFileWithRetry(filePath, {
+            maxBytes: options.maxBytes,
+            retryOpenRaceErrors: true,
+        })).toString("utf8");
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export async function readJsonIfExists(filePath, options = {}) {
+    let raw;
+    try {
+        const buffer = await readRegularFileIfExistsWithRetry(filePath, options);
+        if (buffer === null) {
+            return null;
+        }
+        raw = buffer.toString("utf8");
+    }
+    catch (err) {
+        if (getErrorCode(err) === "ENOENT") {
+            return null;
+        }
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export function readJsonSync(filePath, options = {}) {
+    let raw;
+    try {
+        raw = readRegularFileSync({ filePath, maxBytes: options.maxBytes }).buffer.toString("utf8");
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export async function writeJson(filePath, value, options) {
+    const text = stringifyJsonDocument(value, null, 2);
+    await writeTextAtomic(filePath, text, {
+        mode: options?.mode,
+        dirMode: options?.dirMode,
+        trailingNewline: options?.trailingNewline,
+        durable: options?.durable,
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/local-file-access.d.ts

@@ -0,0 +1,9 @@
+export declare function isFileUrl(input: string): boolean;
+export declare function hasEncodedFileUrlSeparator(pathname: string): boolean;
+export declare function isWindowsNetworkPath(filePath: string, platform?: NodeJS.Platform): boolean;
+export declare function isWindowsDriveLetterPath(filePath: string, platform?: NodeJS.Platform): boolean;
+export declare function assertNoWindowsNetworkPath(filePath: string, label?: string): void;
+export declare function safeFileURLToPath(fileUrl: string, platform?: NodeJS.Platform): string;
+export declare function trySafeFileURLToPath(fileUrl: string, platform?: NodeJS.Platform): string | undefined;
+export declare function basenameFromMediaSource(source?: string): string | undefined;
+//# sourceMappingURL=local-file-access.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/local-file-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAOA,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD;AAOD,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAeT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAqBR;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}

package/node_modules/@openclaw/fs-safe/dist/local-file-access.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { fileURLToPath, URL } from "node:url";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const ENCODED_FILE_URL_SEPARATOR_RE = /%(?:2f|5c)/i;
+const FILE_URL_PREFIX_RE = /^file:\/\//i;
+export function isFileUrl(input) {
+    return FILE_URL_PREFIX_RE.test(input);
+}
+function isLocalFileUrlHost(hostname) {
+    const normalized = normalizeLowercaseStringOrEmpty(hostname);
+    return normalized === "" || normalized === "localhost";
+}
+export function hasEncodedFileUrlSeparator(pathname) {
+    return ENCODED_FILE_URL_SEPARATOR_RE.test(pathname);
+}
+export function isWindowsNetworkPath(filePath, platform = process.platform) {
+    if (platform !== "win32") {
+        return false;
+    }
+    const normalized = filePath.replace(/\//g, "\\");
+    const extendedDrive = normalized.length >= 7 &&
+        normalized.startsWith("\\\\?\\") &&
+        /^[a-z]$/i.test(normalized[4] ?? "") &&
+        normalized[5] === ":" &&
+        normalized[6] === "\\";
+    if (extendedDrive) {
+        return false;
+    }
+    return normalized.startsWith("\\\\");
+}
+export function isWindowsDriveLetterPath(filePath, platform = process.platform) {
+    return platform === "win32" && /^[A-Za-z]:[\\/]/.test(filePath);
+}
+export function assertNoWindowsNetworkPath(filePath, label = "Path") {
+    if (isWindowsNetworkPath(filePath)) {
+        throw new Error(`${label} cannot use Windows network paths: ${filePath}`);
+    }
+}
+export function safeFileURLToPath(fileUrl, platform = process.platform) {
+    let parsed;
+    try {
+        parsed = new URL(fileUrl);
+    }
+    catch {
+        throw new Error(`Invalid file:// URL: ${fileUrl}`);
+    }
+    if (parsed.protocol !== "file:") {
+        throw new Error(`Invalid file:// URL: ${fileUrl}`);
+    }
+    if (!isLocalFileUrlHost(parsed.hostname)) {
+        throw new Error(`file:// URLs with remote hosts are not allowed: ${fileUrl}`);
+    }
+    if (hasEncodedFileUrlSeparator(parsed.pathname)) {
+        throw new Error(`file:// URLs cannot encode path separators: ${fileUrl}`);
+    }
+    const filePath = fileURLToPath(parsed, { windows: platform === "win32" });
+    if (isWindowsNetworkPath(filePath, platform)) {
+        throw new Error(`Local file URL cannot use Windows network paths: ${filePath}`);
+    }
+    return filePath;
+}
+export function trySafeFileURLToPath(fileUrl, platform = process.platform) {
+    try {
+        return safeFileURLToPath(fileUrl, platform);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function basenameFromMediaSource(source) {
+    if (!source) {
+        return undefined;
+    }
+    if (isFileUrl(source)) {
+        const filePath = trySafeFileURLToPath(source);
+        return filePath ? path.basename(filePath) || undefined : undefined;
+    }
+    if (/^https?:\/\//i.test(source)) {
+        try {
+            return path.basename(new URL(source).pathname) || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path.basename(source) || undefined;
+}

package/node_modules/@openclaw/fs-safe/dist/local-roots.d.ts

@@ -0,0 +1,26 @@
+import { type HardlinkPolicy, type ReadResult, type SymlinkPolicy } from "./root.js";
+export type LocalRootsPathResult = {
+    path: string;
+    root: string;
+};
+export type LocalRootsReadResult = ReadResult & {
+    root: string;
+};
+export type LocalRootsInputOptions = {
+    filePath: string;
+    roots: readonly string[];
+    label?: string;
+};
+export type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
+    allowMissing?: boolean;
+    requireFile?: boolean;
+};
+export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
+    hardlinks?: HardlinkPolicy;
+    maxBytes?: number;
+    nonBlockingRead?: boolean;
+    symlinks?: SymlinkPolicy;
+};
+export declare function resolveLocalPathFromRootsSync(options: ResolveLocalPathFromRootsSyncOptions): LocalRootsPathResult | null;
+export declare function readLocalFileFromRoots(options: ReadLocalFileFromRootsOptions): Promise<LocalRootsReadResult | null>;
+//# sourceMappingURL=local-roots.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/local-roots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAQA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAgDF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CAuC7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA2CtC"}

package/node_modules/@openclaw/fs-safe/dist/local-roots.js

@@ -0,0 +1,135 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { expandHomePrefix, resolveHomeRelativePath } from "./home-dir.js";
+import { isFileUrl, safeFileURLToPath } from "./local-file-access.js";
+import { isPathInside } from "./path.js";
+import { resolveRootPathSync } from "./root-path.js";
+import { root } from "./root.js";
+function resolveLocalPathInput(input, label) {
+    if (isFileUrl(input)) {
+        try {
+            return safeFileURLToPath(input);
+        }
+        catch {
+            const location = label === "file path" ? "" : ` in ${label}`;
+            throw new Error(`Invalid file:// URL${location}: ${input}`);
+        }
+    }
+    if (input.includes("\0")) {
+        throw new FsSafeError("invalid-path", `${label} must not contain NUL bytes`);
+    }
+    return resolveHomeRelativePath(input);
+}
+function resolveLocalRootInput(input, label) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new FsSafeError("invalid-path", `${label} entry is required`);
+    }
+    const resolved = isFileUrl(trimmed)
+        ? resolveLocalPathInput(trimmed, label)
+        : expandHomePrefix(trimmed);
+    if (resolved.includes("\0")) {
+        throw new FsSafeError("invalid-path", `${label} entry must not contain NUL bytes`);
+    }
+    if (!path.isAbsolute(resolved)) {
+        throw new FsSafeError("invalid-path", `${label} entries must be absolute paths: ${input}`);
+    }
+    return path.resolve(resolved);
+}
+function resolveRootRealSync(rootDir) {
+    try {
+        // Configured roots may themselves be symlinks. Follow only this trusted
+        // root entry, then use its canonical directory for containment checks.
+        const stat = fsSync.statSync(rootDir);
+        if (!stat.isDirectory()) {
+            return null;
+        }
+        return fsSync.realpathSync(rootDir);
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveLocalPathFromRootsSync(options) {
+    const label = options.label ?? "local roots";
+    const requestedPath = path.resolve(resolveLocalPathInput(options.filePath, "file path"));
+    const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
+    for (const rootDir of rootDirs) {
+        const rootReal = resolveRootRealSync(rootDir);
+        if (!rootReal) {
+            continue;
+        }
+        let candidate;
+        try {
+            candidate = resolveRootPathSync({
+                absolutePath: requestedPath,
+                rootPath: rootDir,
+                rootCanonicalPath: rootReal,
+                boundaryLabel: label,
+                rejectUnresolvedSymlinks: true,
+            });
+        }
+        catch {
+            continue;
+        }
+        if (!candidate.exists && options.allowMissing !== true) {
+            continue;
+        }
+        if (candidate.exists && options.requireFile === true) {
+            try {
+                if (!fsSync.lstatSync(requestedPath).isFile()) {
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return { path: candidate.canonicalPath, root: rootReal };
+    }
+    return null;
+}
+export async function readLocalFileFromRoots(options) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const label = options.label ?? "local roots";
+    const requestedPath = path.resolve(resolveLocalPathInput(options.filePath, "file path"));
+    const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
+    for (const rootDir of rootDirs) {
+        let scopedRoot;
+        try {
+            scopedRoot = await root(rootDir);
+        }
+        catch {
+            continue;
+        }
+        const readOptions = {
+            hardlinks: options.hardlinks,
+            symlinks: options.symlinks,
+        };
+        // Leave maxBytes absent when the caller omits it so Root's own default
+        // cap remains in force instead of being overwritten by undefined.
+        if (maxBytes !== undefined) {
+            readOptions.maxBytes = maxBytes;
+        }
+        // A trusted root symlink has two valid spellings. Preserve the caller's
+        // lexical spelling when possible so Root.read() still enforces its
+        // symlink policy, while also accepting a path expressed below rootReal.
+        const relativePaths = [scopedRoot.rootDir, scopedRoot.rootReal]
+            .filter((rootPath, index, roots) => roots.indexOf(rootPath) === index)
+            .filter((rootPath) => isPathInside(rootPath, requestedPath))
+            .map((rootPath) => path.relative(rootPath, requestedPath))
+            .filter(Boolean);
+        for (const relativePath of relativePaths) {
+            try {
+                const result = await scopedRoot.read(relativePath, readOptions);
+                return { ...result, root: scopedRoot.rootReal };
+            }
+            catch {
+                // Try the canonical spelling before moving to the next configured root.
+            }
+        }
+    }
+    return null;
+}

package/node_modules/@openclaw/fs-safe/dist/lock-config.d.ts

@@ -0,0 +1,10 @@
+import type { SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export type FsSafeLockConfig = {
+    staleRecovery: SidecarLockStaleRecovery;
+    staleMs?: number;
+    timeoutMs?: number;
+    retry?: SidecarLockRetryOptions;
+};
+export declare function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
+export declare function getFsSafeLockConfig(): FsSafeLockConfig;
+//# sourceMappingURL=lock-config.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/lock-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-config.d.ts","sourceRoot":"","sources":["../src/lock-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE3F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,EAAE,wBAAwB,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAQF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAI5E;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD"}

package/node_modules/@openclaw/fs-safe/dist/lock-config.js

@@ -0,0 +1,12 @@
+const DEFAULT_LOCK_CONFIG = {
+    staleRecovery: "fail-closed",
+};
+let lockConfig = { ...DEFAULT_LOCK_CONFIG };
+export function configureFsSafeLocks(config) {
+    // Process defaults only fill lock options after a caller explicitly enables
+    // locking for a resource; this must never turn sidecar locks on globally.
+    lockConfig = { ...lockConfig, ...config };
+}
+export function getFsSafeLockConfig() {
+    return { ...lockConfig, retry: lockConfig.retry ? { ...lockConfig.retry } : undefined };
+}

package/node_modules/@openclaw/fs-safe/dist/move-path-cleanup.d.ts

@@ -0,0 +1,43 @@
+export type EntryIdentity = {
+    ctimeMs: number;
+    dev: number;
+    ino: number;
+    mode: number;
+    mtimeMs: number;
+    nlink: number;
+    size: number;
+};
+export type CopiedEntryManifest = (EntryIdentity & {
+    children: Array<{
+        name: string;
+        manifest: CopiedEntryManifest;
+    }>;
+    kind: "directory";
+}) | (EntryIdentity & {
+    kind: "leaf";
+});
+type CleanupCopiedEntryResult = "removed" | "stale";
+type CleanupAliasGroup = {
+    expected: EntryIdentity;
+    remainingPaths: Set<string>;
+    stale: boolean;
+};
+export type CleanupCopiedEntryState = {
+    aliasGroups: Map<string, CleanupAliasGroup>;
+};
+export declare function entryIdentity(stat: {
+    ctimeMs: number;
+    dev: number;
+    ino: number;
+    mode: number;
+    mtimeMs: number;
+    nlink: number;
+    size: number;
+}): EntryIdentity;
+export declare function sameIdentity(a: EntryIdentity, b: EntryIdentity): boolean;
+export declare function sourceChangedError(sourcePath: string): Error;
+export declare function assertSourceStillMatches(sourcePath: string, identity: EntryIdentity): Promise<void>;
+export declare function createCleanupCopiedEntryState(sourcePath: string, manifest: CopiedEntryManifest): CleanupCopiedEntryState;
+export declare function cleanupCopiedEntry(sourcePath: string, manifest: CopiedEntryManifest, state: CleanupCopiedEntryState, assertBeforeMutation: () => void): Promise<CleanupCopiedEntryResult>;
+export {};
+//# sourceMappingURL=move-path-cleanup.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/move-path-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"move-path-cleanup.d.ts","sourceRoot":"","sources":["../src/move-path-cleanup.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,CAAC,aAAa,GAAG;IACf,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IACjE,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,GACF,CAAC,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvC,KAAK,wBAAwB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CAUhB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAUxE;AAMD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAI5D;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAIf;AA0BD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,GAC5B,uBAAuB,CAuBzB;AAsDD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,uBAAuB,EAC9B,oBAAoB,EAAE,MAAM,IAAI,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAyDnC"}