@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -7,6 +7,7 @@ import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./fil
 import { isPathInside } from "./path.js";
 import { root } from "./root.js";
 import { tempFile } from "./temp-target.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 const NON_PORTABLE_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
 function tempFileNameForTarget(targetPath, fallbackFileName) {
     const fallback = sanitizeUntrustedFileName(fallbackFileName ?? "output.bin", "output.bin");
@@ -51,8 +52,16 @@ function assertFileTargetPath(targetPath) {
 }
 export async function writeExternalFileWithinRoot(options) {
     const maxBytes = normalizeMaxBytes(options.maxBytes);
-    const targetRoot = await root(options.rootDir);
+    const rootDir = options.rootDir;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "output root uses a Windows filesystem namespace alias");
     const requestedTargetPath = options.path;
+    assertNoWindowsPathAlias(path.dirname(requestedTargetPath), "filesystem", "output target parent uses a Windows filesystem namespace alias");
+    const producerIsolation = options.producerIsolation;
+    const write = options.write;
+    const mode = options.mode;
+    const staging = options.staging;
+    const fallbackFileName = options.fallbackFileName;
+    const targetRoot = await root(rootDir);
     if (requestedTargetPath.length === 0) {
         throw new FsSafeError("invalid-path", "target path is required");
     }
@@ -63,9 +72,11 @@ export async function writeExternalFileWithinRoot(options) {
         targetPath: requestedTargetPath,
     });
     assertFileTargetPath(rawTargetPath);
-    const targetPath = sanitizedTargetPath(rawTargetPath, options.fallbackFileName);
+    const targetPath = sanitizedTargetPath(rawTargetPath, fallbackFileName);
+    assertNoWindowsPathAlias(targetPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const finalPath = await targetRoot.resolve(targetPath);
-    if (options.staging === "sibling") {
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    if (staging === "sibling") {
         const parentPath = path.dirname(targetPath);
         if (parentPath !== ".") {
             await targetRoot.mkdir(parentPath);
@@ -73,22 +84,23 @@ export async function writeExternalFileWithinRoot(options) {
         const siblingFinalPath = await targetRoot.resolve(targetPath);
         const result = await writeExternalFileViaSibling({
             finalPath: siblingFinalPath,
-            write: options.write,
-            fallbackFileName: options.fallbackFileName,
+            write,
+            producerIsolation,
+            fallbackFileName,
             maxBytes,
-            mode: options.mode,
+            mode,
         });
         return { path: siblingFinalPath, result };
     }
     const staged = await tempFile({
         prefix: "fs-safe-output",
-        fileName: tempFileNameForTarget(targetPath, options.fallbackFileName),
+        fileName: tempFileNameForTarget(targetPath, fallbackFileName),
     });
     try {
-        const result = await options.write(staged.path);
+        const result = await Function.prototype.call.call(write, options, staged.path);
         await targetRoot.copyIn(targetPath, staged.path, {
             maxBytes,
-            mode: options.mode,
+            mode,
             mkdir: true,
             sourceHardlinks: "reject",
         });
@@ -98,7 +110,7 @@ export async function writeExternalFileWithinRoot(options) {
         await staged.cleanup();
     }
 }
-function buildSiblingTempPath(targetPath, fallbackFileName) {
+function buildSiblingTempName(targetPath, fallbackFileName) {
     const prefix = `.fs-safe-output-${process.pid}-${randomUUID()}-`;
     const suffix = ".part";
     const safeTail = fitFileNameToPortableComponent({
@@ -106,13 +118,17 @@ function buildSiblingTempPath(targetPath, fallbackFileName) {
         fileName: tempFileNameForTarget(targetPath, fallbackFileName),
         suffix,
     });
-    return path.join(path.dirname(targetPath), `${prefix}${safeTail}${suffix}`);
+    return `${prefix}${safeTail}${suffix}`;
 }
 async function writeExternalFileViaSibling(params) {
+    assertNoWindowsPathAlias(params.finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const finalPath = path.resolve(params.finalPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const { result } = await writeCallbackSibling({
-        tempPath: buildSiblingTempPath(finalPath, params.fallbackFileName),
+        tempDir: path.dirname(finalPath),
+        tempName: buildSiblingTempName(finalPath, params.fallbackFileName),
         write: params.write,
+        producerIsolation: params.producerIsolation,
         resolveFinalPath: () => finalPath,
         mode: params.mode,
         maxBytes: params.maxBytes,

package/node_modules/@openclaw/fs-safe/dist/overwrite-file-handle.d.ts

@@ -0,0 +1,7 @@
+import type { FileHandle } from "node:fs/promises";
+export type OverwriteFileHandleOptions = {
+    /** Admit the whole write once, after rollback preparation and before any mutation. */
+    beforeWrite?: () => void;
+};
+/** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
+export declare function overwriteFileHandle(handle: FileHandle, data: Uint8Array, options?: OverwriteFileHandleOptions): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/overwrite-file-handle.js

@@ -0,0 +1,46 @@
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { readFileWindowFully } from "./positional-read.js";
+import { writeAllToFile } from "./write-file-handle.js";
+/** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
+export async function overwriteFileHandle(handle, data, options = {}) {
+    // Snapshot caller-owned admission before the first await. Preserve the
+    // former method-call receiver while preventing a later getter mutation from
+    // replacing authority after rollback preparation.
+    const beforeWrite = options.beforeWrite;
+    const payload = data.subarray(0, data.byteLength);
+    const payloadBytes = payload.byteLength;
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "overwrite handle must be a regular file");
+    }
+    const originalSize = stat.size;
+    if (!Number.isSafeInteger(originalSize) || originalSize < 0) {
+        throw new RangeError("file size must be a non-negative safe integer");
+    }
+    const prefixBytes = Math.min(payloadBytes, originalSize);
+    const originalPrefix = Buffer.allocUnsafe(prefixBytes);
+    if (await readFileWindowFully(handle, originalPrefix, 0) !== prefixBytes) {
+        throw new FsSafeError("read-failed", "file ended before overwrite rollback preparation completed");
+    }
+    assertSynchronousCallbackResult(beforeWrite === undefined ? undefined : Reflect.apply(beforeWrite, options, []), "beforeWrite");
+    let prefixStarted = false;
+    try {
+        // Leave existing bytes intact until any additional storage has been written.
+        if (payloadBytes > originalSize) {
+            await writeAllToFile(handle, payload.subarray(originalSize), { position: originalSize });
+        }
+        prefixStarted = true;
+        await writeAllToFile(handle, payload.subarray(0, prefixBytes), { position: 0 });
+        if (payloadBytes < originalSize) {
+            await handle.truncate(payloadBytes);
+        }
+    }
+    catch (error) {
+        if (prefixStarted) {
+            await writeAllToFile(handle, originalPrefix, { position: 0 }).catch(() => undefined);
+        }
+        await handle.truncate(originalSize).catch(() => undefined);
+        throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/owner-dacl.d.ts

@@ -28,4 +28,3 @@ export type OwnerAndDaclResult = {
     platform: NodeJS.Platform;
 };
 export declare function readOwnerAndDacl(targetPath: string): OwnerAndDaclResult;
-//# sourceMappingURL=owner-dacl.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/owner-dacl.js

@@ -1,15 +1,23 @@
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { readWindowsSecurityFactsCommand } from "./windows-security-command.js";
 export function readOwnerAndDacl(targetPath) {
     if (process.platform !== "win32") {
         return { status: "unsupported-platform", platform: process.platform };
     }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
     const native = getNativeBinding();
-    if (!native) {
-        throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require the matching optional native platform package; " +
-            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
+    const inspect = native?.readOwnerAndDacl;
+    if (typeof inspect !== "function") {
+        if (getFsSafeNativeConfig().mode === "require") {
+            throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require an up-to-date native helper");
+        }
+        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
     }
-    const facts = native.readOwnerAndDacl(targetPath);
+    const facts = typeof inspect === "function" ? inspect.call(native, targetPath) : readWindowsSecurityFactsCommand(targetPath);
     return {
         status: "supported",
         ownerSid: facts.ownerSid,

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

@@ -0,0 +1,6 @@
+export type ProbePathCaseOptions = {
+    /** Allow an exclusively created empty probe when existing entries provide no answer. Defaults to true. */
+    allowTemporaryProbe?: boolean;
+};
+/** Observe local ASCII case behavior; unknown observations never imply an operating-system default. */
+export declare function probePathCaseInsensitiveSync(targetPath: string, options?: ProbePathCaseOptions): boolean | undefined;

package/node_modules/@openclaw/fs-safe/dist/path-case.js

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import fs, {} from "node:fs";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { writeTempFileSync } from "./replace-file-descriptor.js";
+import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+function swapAsciiCase(value) {
+    return value.replace(/[A-Za-z]/g, character => {
+        const lower = character.toLowerCase();
+        return character === lower ? character.toUpperCase() : lower;
+    });
+}
+function probeEntry(directory, name, names) {
+    const alternate = swapAsciiCase(name);
+    if (alternate === name)
+        return undefined;
+    const bothListed = names.has(name) && names.has(alternate);
+    const originalPath = path.join(directory, name);
+    let original;
+    let observed;
+    try {
+        original = inspectFileIdentitySync(() => fs.lstatSync(originalPath, { bigint: true }));
+        try {
+            const other = inspectFileIdentitySync(() => fs.lstatSync(path.join(directory, alternate), { bigint: true }));
+            const sameIdentity = sameFileIdentityForCleanup(original, other);
+            if (sameIdentity || bothListed) {
+                // Matching inodes can belong to newly linked case-distinct names.
+                const currentNames = new Set(fs.readdirSync(directory));
+                const bothCurrent = currentNames.has(name) && currentNames.has(alternate);
+                if (bothListed && !bothCurrent)
+                    return undefined;
+                observed = sameIdentity && !bothCurrent;
+            }
+            else {
+                observed = false;
+            }
+        }
+        catch (error) {
+            if (bothListed || !isNotFoundPathError(error))
+                return undefined;
+            observed = false;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    // Disappearance during lookup is not evidence that case variants are distinct.
+    inspectFileIdentitySync(() => fs.lstatSync(originalPath, { bigint: true }), original);
+    return observed;
+}
+function probeTemporaryEntry(directory) {
+    const name = `.fs-safe-case-probe-${randomUUID()}`;
+    const owner = new SyncAtomicTempOwner(path.join(directory, name));
+    try {
+        owner.start();
+        owner.adopt(writeTempFileSync({
+            fsModule: fs,
+            tempPath: owner.pathname,
+            content: "",
+            mode: 0o600,
+            sync: false,
+            onIdentity: owner.onIdentity,
+        }));
+        owner.assertCurrent(fs);
+        const observed = probeEntry(directory, name, new Set(fs.readdirSync(directory)));
+        owner.assertCurrent(fs);
+        return observed;
+    }
+    finally {
+        // Failed cleanup invalidates the observation; the existing owner retains its exit retry.
+        owner.finish({ fsModule: fs, throwOnCleanupError: true });
+    }
+}
+function probeDirectory(directory, allowTemporaryProbe, preferredName) {
+    const canonical = realpathSync.native(directory);
+    const identity = inspectDirectoryIdentitySync(canonical);
+    const names = new Set(fs.readdirSync(canonical));
+    let observed = preferredName === undefined ? undefined : probeEntry(canonical, preferredName, names);
+    for (const name of names) {
+        if (observed !== undefined)
+            break;
+        observed = probeEntry(canonical, name, names);
+    }
+    if (observed === undefined && allowTemporaryProbe)
+        observed = probeTemporaryEntry(canonical);
+    assertDirectoryIdentitySync(canonical, identity);
+    return realpathSync.native(directory) === canonical ? observed : undefined;
+}
+/** Observe local ASCII case behavior; unknown observations never imply an operating-system default. */
+export function probePathCaseInsensitiveSync(targetPath, options = {}) {
+    const resolved = path.resolve(targetPath);
+    const allowTemporaryProbe = options.allowTemporaryProbe !== false;
+    let targetExists = true;
+    try {
+        fs.lstatSync(resolved);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            return undefined;
+        targetExists = false;
+    }
+    if (targetExists) {
+        try {
+            return probeDirectory(path.dirname(resolved), allowTemporaryProbe, path.basename(resolved));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    let directory = path.dirname(resolved);
+    for (;;) {
+        let exists = false;
+        try {
+            exists = fs.statSync(directory).isDirectory();
+        }
+        catch {
+            // A missing or unreadable component can still have a readable existing ancestor.
+        }
+        if (exists) {
+            try {
+                return probeDirectory(directory, allowTemporaryProbe);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}

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

@@ -22,4 +22,3 @@ export declare function assertNoHardlinkedFinalPath(params: {
     boundaryLabel: string;
     allowFinalHardlinkForUnlink?: boolean;
 }): Promise<void>;
-//# sourceMappingURL=path-policy.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/path-policy.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath, } from "./root-path.js";
 import { isNotFoundPathError } from "./path.js";
 import { shortPath } from "./error-detail.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const PATH_ALIAS_POLICIES = ROOT_PATH_ALIAS_POLICIES;
 export async function assertNoPathAliasEscape(params) {
     const resolved = await resolveRootPath({
@@ -25,9 +26,13 @@ export async function assertNoHardlinkedFinalPath(params) {
     if (params.allowFinalHardlinkForUnlink) {
         return;
     }
+    const filePath = params.filePath;
+    const root = params.root;
+    const boundaryLabel = params.boundaryLabel;
+    assertNoWindowsPathAlias(filePath);
     let stat;
     try {
-        stat = fs.statSync(params.filePath);
+        stat = fs.statSync(filePath);
     }
     catch (err) {
         if (isNotFoundPathError(err)) {
@@ -39,6 +44,6 @@ export async function assertNoHardlinkedFinalPath(params) {
         return;
     }
     if (stat.nlink > 1) {
-        throw new Error(`Hardlinked path is not allowed under ${params.boundaryLabel} (${shortPath(params.root)}): ${shortPath(params.filePath)}`);
+        throw new Error(`Hardlinked path is not allowed under ${boundaryLabel} (${shortPath(root)}): ${shortPath(filePath)}`);
     }
 }

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

@@ -0,0 +1,6 @@
+export type ResolvedPathPrefix = {
+    readonly absolutePath: string;
+    readonly existingPath: string;
+    readonly unresolvedSegments: readonly string[];
+};
+export declare function resolvePathPrefixSync(input: string): ResolvedPathPrefix;

package/node_modules/@openclaw/fs-safe/dist/path-prefix.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatErrorDetail } from "./error-detail.js";
+import { assertNoNulPathInput, hasNodeErrorCode } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { absolutePathWithRawSegments } from "./root-path-existing.js";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+function rawRoot(absolutePath) {
+    if (path.sep === "\\" && /^\\\\[?.]\\UNC\\/i.test(absolutePath)) {
+        // Node parses only the namespace prefix as the root of an extended UNC path.
+        const shareRoot = path.parse(`\\\\${absolutePath.slice(8)}`).root;
+        return absolutePath.slice(0, shareRoot.length + 6);
+    }
+    return path.parse(absolutePath).root;
+}
+function resolutionError(code, absolutePath) {
+    const detail = code === "ELOOP" ? "too many symbolic links" : "not a directory";
+    return Object.assign(new Error(`${code}: ${detail}, resolvePathPrefix ${formatErrorDetail(absolutePath)}`), {
+        code, syscall: "resolvePathPrefix", path: absolutePath,
+    });
+}
+// Leave ample room for ordinary shallow paths to retain the legacy small-array
+// path. At 32 components, repeated front removal can reindex at most 496 array
+// positions per constructed queue; longer queues use a forward cursor instead.
+const SHIFT_QUEUE_COMPONENT_LIMIT = 32;
+export function resolvePathPrefixSync(input) {
+    assertNoNulPathInput(input);
+    const absolutePath = absolutePathWithRawSegments(input);
+    let resolved = rawRoot(absolutePath);
+    let remaining = absolutePath.slice(resolved.length).split(path.sep);
+    let shiftQueue = remaining.length <= SHIFT_QUEUE_COMPONENT_LIMIT;
+    let nextSegment = 0;
+    let remainingCount = remaining.length;
+    const visitedStates = new Set();
+    let symlinkHops = 0;
+    while (remainingCount > 0) {
+        const segment = shiftQueue ? remaining.shift() : remaining[nextSegment++];
+        remainingCount--;
+        if (segment === "")
+            continue;
+        if (segment === "." || segment === "..") {
+            const atRoot = resolved === rawRoot(resolved);
+            const lookup = segment === ".." && atRoot ? "." : segment;
+            // lstat(dir) does not test search permission, and realpath may erase dots.
+            const operationBase = pathForWindowsFilesystem(resolved);
+            fs.lstatSync(`${operationBase}${operationBase.endsWith(path.sep) ? "" : path.sep}${lookup}`, { bigint: true });
+            if (segment === ".." && !atRoot)
+                resolved = path.dirname(resolved);
+            continue;
+        }
+        const candidate = path.join(resolved, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(candidate, { bigint: true });
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                throw error;
+            return {
+                absolutePath,
+                existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)),
+                unresolvedSegments: shiftQueue ? [segment, ...remaining] : remaining.slice(nextSegment - 1),
+            };
+        }
+        if (!stat.isSymbolicLink()) {
+            if (!stat.isDirectory() && remainingCount > 0)
+                throw resolutionError("ENOTDIR", absolutePath);
+            resolved = candidate;
+            continue;
+        }
+        const pendingSuffix = shiftQueue ? remaining : remaining.slice(nextSegment);
+        const state = JSON.stringify([String(stat.dev), String(stat.ino), candidate, pendingSuffix]);
+        if (symlinkHops >= 64 || visitedStates.has(state))
+            throw resolutionError("ELOOP", absolutePath);
+        visitedStates.add(state);
+        symlinkHops++;
+        const target = fs.readlinkSync(candidate);
+        const rawTarget = path.sep === "\\" ? target.replaceAll("/", "\\") : target;
+        let targetSegments;
+        if (path.isAbsolute(rawTarget)) {
+            const targetRoot = rawRoot(rawTarget);
+            // A rooted Windows link target uses the link's drive/share, not cwd's.
+            resolved = path.sep === "\\" && targetRoot === "\\" ? rawRoot(resolved) : targetRoot;
+            targetSegments = rawTarget.slice(targetRoot.length).split(path.sep);
+        }
+        else {
+            // A target's parent traversal applies after resolving its preceding links.
+            targetSegments = rawTarget.split(path.sep);
+        }
+        const expandedCount = targetSegments.length + pendingSuffix.length;
+        if (expandedCount <= SHIFT_QUEUE_COMPONENT_LIMIT) {
+            // The spread is bounded by the same fixed limit as subsequent shifts.
+            remaining = pendingSuffix;
+            remaining.unshift(...targetSegments);
+        }
+        else {
+            remaining = targetSegments.concat(pendingSuffix);
+        }
+        remainingCount = remaining.length;
+        shiftQueue = remainingCount <= SHIFT_QUEUE_COMPONENT_LIMIT;
+        nextSegment = 0;
+    }
+    return { absolutePath, existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)), unresolvedSegments: [] };
+}

package/node_modules/@openclaw/fs-safe/dist/path-scope-lexical.d.ts

@@ -0,0 +1,13 @@
+export type ResolvePathWithinRootParams = {
+    rootDir: string;
+    requestedPath: string;
+    scopeLabel: string;
+    defaultFileName?: string;
+};
+export declare function resolvePathWithinNormalizedRoot(params: ResolvePathWithinRootParams, root: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};

package/node_modules/@openclaw/fs-safe/dist/path-scope-lexical.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { isPathInside, isPathRelativeEscape } from "./path.js";
+import { hasWindowsPathAlias, resolvePathFromBasePreservingWindowsRoot } from "./windows-path-alias.js";
+function pathStaysWithinRoot(rootDir, candidatePath) {
+    if (process.platform !== "win32") {
+        return candidatePath !== rootDir && isPathInside(rootDir, candidatePath);
+    }
+    const relative = path.relative(rootDir, candidatePath);
+    return Boolean(relative) && !isPathRelativeEscape(relative);
+}
+export function resolvePathWithinNormalizedRoot(params, root) {
+    const requestedPath = params.requestedPath;
+    const defaultFileName = params.defaultFileName;
+    const scopeLabel = params.scopeLabel;
+    if (hasWindowsPathAlias(params.rootDir, "filesystem") ||
+        hasWindowsPathAlias(root, "filesystem") ||
+        hasWindowsPathAlias(requestedPath, "filesystem") ||
+        (defaultFileName !== undefined && hasWindowsPathAlias(defaultFileName, "filesystem"))) {
+        return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+    }
+    const raw = requestedPath.trim();
+    if (!raw) {
+        if (!defaultFileName) {
+            return { ok: false, error: "path is required" };
+        }
+        const defaultPath = resolvePathFromBasePreservingWindowsRoot(root, defaultFileName);
+        if (hasWindowsPathAlias(defaultPath, "filesystem") || !pathStaysWithinRoot(root, defaultPath)) {
+            return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+        }
+        return { ok: true, path: defaultPath };
+    }
+    const resolved = resolvePathFromBasePreservingWindowsRoot(root, raw);
+    if (hasWindowsPathAlias(resolved, "filesystem") || !pathStaysWithinRoot(root, resolved)) {
+        return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+    }
+    return { ok: true, path: resolved };
+}

package/node_modules/@openclaw/fs-safe/dist/path-segment-route.d.ts

@@ -0,0 +1,6 @@
+export type PathSegmentRoute = Readonly<{
+    joined: string;
+    offsets: readonly number[];
+}>;
+export declare function createPathSegmentRoute(segments: readonly string[]): PathSegmentRoute;
+export declare function joinPathSegmentRoute(base: string, route: PathSegmentRoute, offset: number, tail?: string): string;

package/node_modules/@openclaw/fs-safe/dist/path-segment-route.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+export function createPathSegmentRoute(segments) {
+    const offsets = new Array(segments.length + 1);
+    let cursor = 0;
+    for (let index = 0; index < segments.length; index += 1) {
+        offsets[index] = cursor;
+        cursor += segments[index].length;
+        if (index + 1 < segments.length)
+            cursor += path.sep.length;
+    }
+    offsets[segments.length] = cursor;
+    return Object.freeze({ joined: segments.join(path.sep), offsets: Object.freeze(offsets) });
+}
+// Select the immutable suffix by character offset so callers perform at most
+// one path normalization without copying a shrinking segment array.
+export function joinPathSegmentRoute(base, route, offset, tail) {
+    const start = route.offsets[offset];
+    if (start === undefined)
+        throw new RangeError("path segment offset is outside the route");
+    const suffix = route.joined.slice(start);
+    if (suffix)
+        return tail === undefined ? path.join(base, suffix) : path.join(base, suffix, tail);
+    return tail === undefined ? base : path.join(base, tail);
+}

package/node_modules/@openclaw/fs-safe/dist/path-suffix-aliases.d.ts

@@ -0,0 +1,11 @@
+export type ProbePathSuffixAliasesOptions = {
+    directory: string;
+    left: string;
+    right: string;
+    /** Maximum relative component count; defaults to 32. */
+    maxDepth?: number;
+    /** Synchronous caller policy for differing NFC pairs not equivalent under ASCII case folding. */
+    shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
+};
+/** Observe bounded missing suffix aliases; the caller owns caching and ambiguity policy. */
+export declare function probePathSuffixAliasesSync(options: ProbePathSuffixAliasesOptions): boolean | undefined;