@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -0,0 +1,8 @@
+import { type ResolvePathWithinRootParams } from "./path-scope-lexical.js";
+export declare function resolvePathWithinRoot(params: ResolvePathWithinRootParams): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};

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

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { resolvePathWithinNormalizedRoot } from "./path-scope-lexical.js";
+import { hasWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function invalidPath(scopeLabel) {
+    return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+}
+export function resolvePathWithinRoot(params) {
+    const rootDir = params.rootDir;
+    if (typeof rootDir !== "string")
+        path.resolve(rootDir);
+    const requestedPath = params.requestedPath;
+    const scopeLabel = params.scopeLabel;
+    const defaultFileName = params.defaultFileName;
+    if (hasWindowsPathAlias(rootDir, "filesystem") ||
+        hasWindowsPathAlias(requestedPath, "filesystem") ||
+        (defaultFileName !== undefined &&
+            hasWindowsPathAlias(defaultFileName, "filesystem"))) {
+        return invalidPath(scopeLabel);
+    }
+    const root = resolvePathPreservingWindowsRoot(rootDir);
+    return resolvePathWithinNormalizedRoot({ rootDir, requestedPath, scopeLabel, defaultFileName }, root);
+}

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

@@ -1,16 +1,10 @@
-import { FsSafeError } from "./errors.js";
+import { type DirectoryResult } from "./root-directory.js";
+export { resolvePathWithinRoot } from "./root-paths-lexical.js";
+export { ensureDirectoryWithinRoot } from "./root-directory.js";
 type InvalidPathResult = {
     ok: false;
     error: string;
 };
-type DirectoryResult = {
-    ok: true;
-    path: string;
-} | {
-    ok: false;
-    error: string;
-    diagnostic?: FsSafeError;
-};
 type ResolvePathsWithinRootParams = {
     rootDir: string;
     requestedPaths: string[];
@@ -50,18 +44,6 @@ export type PathScope = {
         mode?: number;
     }): Promise<DirectoryResult>;
 };
-export declare function resolvePathWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultFileName?: string;
-}): {
-    ok: true;
-    path: string;
-} | {
-    ok: false;
-    error: string;
-};
 export declare function resolveWritablePathWithinRoot(params: {
     rootDir: string;
     requestedPath: string;
@@ -74,16 +56,7 @@ export declare function resolveWritablePathWithinRoot(params: {
     ok: false;
     error: string;
 }>;
-export declare function ensureDirectoryWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultDirName?: string;
-    mode?: number;
-}): Promise<DirectoryResult>;
 export declare function resolvePathsWithinRoot(params: ResolvePathsWithinRootParams): ResolvePathsWithinRootResult;
 export declare function resolveExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;
 export declare function resolveStrictExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;
 export declare function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
-export {};
-//# sourceMappingURL=root-paths.d.ts.map

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

@@ -1,35 +1,44 @@
 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 { isNotFoundPathError, isPathInside, } from "./path.js";
+import { realpathSync } from "./realpath.js";
 import { root as openRoot } from "./root.js";
+import { hasWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { resolvePathWithinRoot } from "./root-paths-lexical.js";
+import { resolvePathWithinNormalizedRoot } from "./path-scope-lexical.js";
+import { assertNoSymlinkSegments, ensureDirectoryWithinRoot, resolveNearestExistingPath, } from "./root-directory.js";
+export { resolvePathWithinRoot } from "./root-paths-lexical.js";
+export { ensureDirectoryWithinRoot } from "./root-directory.js";
 function invalidPath(scopeLabel) {
     return {
         ok: false,
         error: `Invalid path: must stay within ${scopeLabel}`,
     };
 }
-function pathStaysWithinRoot(rootDir, candidatePath) {
-    const relative = path.relative(rootDir, candidatePath);
-    return Boolean(relative) && !isPathRelativeEscape(relative);
-}
+const INVALID_REAL_PATH = Symbol("invalid-real-path");
 async function resolveRealPathIfExists(targetPath) {
+    if (hasWindowsPathAlias(targetPath, "filesystem"))
+        return INVALID_REAL_PATH;
     try {
-        return fsSync.realpathSync.native(targetPath);
+        const realPath = realpathSync.native(pathForWindowsFilesystem(targetPath));
+        return hasWindowsPathAlias(realPath, "filesystem") ? INVALID_REAL_PATH : realPath;
     }
     catch {
         return undefined;
     }
 }
 async function resolveTrustedRootRealPath(rootDir) {
+    if (hasWindowsPathAlias(rootDir, "filesystem"))
+        return undefined;
     try {
-        const rootLstat = fsSync.lstatSync(rootDir);
+        const operationPath = pathForWindowsFilesystem(rootDir);
+        const rootLstat = fsSync.lstatSync(operationPath);
         if (!rootLstat.isDirectory() || rootLstat.isSymbolicLink()) {
             return undefined;
         }
-        return fsSync.realpathSync.native(rootDir);
+        const realPath = realpathSync.native(operationPath);
+        return hasWindowsPathAlias(realPath, "filesystem") ? undefined : realPath;
     }
     catch {
         return undefined;
@@ -37,7 +46,8 @@ async function resolveTrustedRootRealPath(rootDir) {
 }
 async function validateCanonicalPathWithinRoot(params) {
     try {
-        const candidateLstat = fsSync.lstatSync(params.candidatePath);
+        const operationPath = pathForWindowsFilesystem(params.candidatePath);
+        const candidateLstat = fsSync.lstatSync(operationPath);
         if (candidateLstat.isSymbolicLink()) {
             return "invalid";
         }
@@ -50,41 +60,33 @@ async function validateCanonicalPathWithinRoot(params) {
         if (params.expect === "file" && candidateLstat.nlink > 1) {
             return "invalid";
         }
-        const candidateRealPath = fsSync.realpathSync.native(params.candidatePath);
+        const candidateRealPath = realpathSync.native(operationPath);
+        if (hasWindowsPathAlias(candidateRealPath, "filesystem"))
+            return "invalid";
         return isPathInside(params.rootRealPath, candidateRealPath) ? "ok" : "invalid";
     }
     catch (err) {
         return isNotFoundPathError(err) ? "not-found" : "invalid";
     }
 }
-export function resolvePathWithinRoot(params) {
-    const root = path.resolve(params.rootDir);
-    const raw = params.requestedPath.trim();
-    if (!raw) {
-        if (!params.defaultFileName) {
-            return { ok: false, error: "path is required" };
-        }
-        const defaultPath = path.resolve(root, params.defaultFileName);
-        if (!pathStaysWithinRoot(root, defaultPath)) {
-            return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
-        }
-        return { ok: true, path: defaultPath };
-    }
-    const resolved = path.resolve(root, raw);
-    if (!pathStaysWithinRoot(root, resolved)) {
-        return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
-    }
-    return { ok: true, path: resolved };
-}
 export async function resolveWritablePathWithinRoot(params) {
-    const lexical = resolvePathWithinRoot(params);
+    const rootDirInput = params.rootDir;
+    const requestedPathInput = params.requestedPath;
+    const scopeLabel = params.scopeLabel;
+    const defaultFileName = params.defaultFileName;
+    const lexical = resolvePathWithinRoot({
+        rootDir: rootDirInput,
+        requestedPath: requestedPathInput,
+        scopeLabel,
+        defaultFileName,
+    });
     if (!lexical.ok) {
         return lexical;
     }
-    const rootDir = path.resolve(params.rootDir);
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
     const rootRealPath = await resolveTrustedRootRealPath(rootDir);
     if (!rootRealPath) {
-        return invalidPath(params.scopeLabel);
+        return invalidPath(scopeLabel);
     }
     const requestedPath = lexical.path;
     const parentDir = path.dirname(requestedPath);
@@ -94,7 +96,7 @@ export async function resolveWritablePathWithinRoot(params) {
         expect: "directory",
     });
     if (parentStatus !== "ok") {
-        return invalidPath(params.scopeLabel);
+        return invalidPath(scopeLabel);
     }
     const targetStatus = await validateCanonicalPathWithinRoot({
         rootRealPath,
@@ -102,139 +104,33 @@ export async function resolveWritablePathWithinRoot(params) {
         expect: "file",
     });
     if (targetStatus === "invalid") {
-        return invalidPath(params.scopeLabel);
+        return invalidPath(scopeLabel);
     }
     return lexical;
 }
-async function resolveNearestExistingPath(targetPath) {
-    let current = path.resolve(targetPath);
-    while (true) {
-        try {
-            fsSync.lstatSync(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;
-    }
-}
-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 {
-        assertNoNulPathInput(params.rootDir);
-        assertNoNulPathInput(params.requestedPath);
-        if (!params.requestedPath.trim())
-            assertNoNulPathInput(params.defaultDirName ?? "");
-        const lexical = resolvePathWithinRoot({
-            ...params, scopeLabel, defaultFileName: params.defaultDirName,
-        });
-        if (!lexical.ok)
-            return lexical;
-        const rootDir = path.resolve(params.rootDir);
-        const targetPath = lexical.path;
-        const rootStat = fsSync.lstatSync(rootDir);
-        if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-            return invalidPath(scopeLabel);
-        }
-        await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
-        const rootReal = fsSync.realpathSync.native(rootDir);
-        const nearestExistingPath = await resolveNearestExistingPath(targetPath);
-        const nearestExistingReal = fsSync.realpathSync.native(nearestExistingPath);
-        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: params.mode });
-                    }
-                    catch (mkdirErr) {
-                        if (hasNodeErrorCode(mkdirErr, "EEXIST")) {
-                            continue;
-                        }
-                        throw mkdirErr;
-                    }
-                }
-            }
-            const currentReal = fsSync.realpathSync.native(current);
-            if (!isPathInside(rootReal, currentReal)) {
-                return invalidPath(scopeLabel);
-            }
-        }
-        const targetReal = fsSync.realpathSync.native(targetPath);
-        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);
-        }
-        // Native messages include unbounded paths; display only bounded errno metadata.
-        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 };
-    }
-}
 export function resolvePathsWithinRoot(params) {
     const resolvedPaths = [];
+    let previousRootDir;
+    let previousResolvedRoot = "";
     for (const raw of params.requestedPaths) {
-        const pathResult = resolvePathWithinRoot({
+        const request = {
             rootDir: params.rootDir,
             requestedPath: raw,
             scopeLabel: params.scopeLabel,
-        });
+        };
+        // Each lexical request owns its admitted root without consuming later items.
+        if (typeof request.rootDir !== "string")
+            path.resolve(request.rootDir);
+        if (hasWindowsPathAlias(request.rootDir, "filesystem"))
+            return invalidPath(request.scopeLabel);
+        // Relative roots may follow cwd changes made by an input iterator or getter.
+        const resolvedRoot = process.platform !== "win32" && typeof request.rootDir === "string" &&
+            request.rootDir.startsWith("/") && request.rootDir === previousRootDir
+            ? previousResolvedRoot
+            : resolvePathPreservingWindowsRoot(request.rootDir);
+        previousRootDir = request.rootDir;
+        previousResolvedRoot = resolvedRoot;
+        const pathResult = resolvePathWithinNormalizedRoot(request, resolvedRoot);
         if (!pathResult.ok) {
             return { ok: false, error: pathResult.error };
         }
@@ -249,10 +145,11 @@ export async function resolveStrictExistingPathsWithinRoot(params) {
     return await resolveCheckedPathsWithinRoot(params, false);
 }
 export function pathScope(rootDir, options) {
-    const base = { rootDir, scopeLabel: options.label };
+    const label = options.label;
+    const base = { rootDir, scopeLabel: label };
     return {
         rootDir,
-        label: options.label,
+        label,
         resolve: (requestedPath, pathOptions) => resolvePathWithinRoot({
             ...base,
             requestedPath,
@@ -284,8 +181,19 @@ export function pathScope(rootDir, options) {
     };
 }
 async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
-    const rootDir = path.resolve(params.rootDir);
-    const rootRealPath = await resolveRealPathIfExists(rootDir);
+    const rootDirInput = params.rootDir;
+    const scopeLabel = params.scopeLabel;
+    if (hasWindowsPathAlias(rootDirInput, "filesystem")) {
+        return invalidPath(scopeLabel);
+    }
+    const requestedPaths = [...params.requestedPaths];
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+    if (hasWindowsPathAlias(rootDir, "filesystem"))
+        return invalidPath(scopeLabel);
+    const rootRealPathResult = await resolveRealPathIfExists(rootDir);
+    if (rootRealPathResult === INVALID_REAL_PATH)
+        return invalidPath(scopeLabel);
+    const rootRealPath = rootRealPathResult;
     const root = rootRealPath ? await openRoot(rootDir) : undefined;
     const isInRoot = (relativePath) => Boolean(relativePath) &&
         relativePath !== ".." &&
@@ -296,7 +204,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
         const lexicalPathResult = resolvePathWithinRoot({
             rootDir,
             requestedPath,
-            scopeLabel: params.scopeLabel,
+            scopeLabel,
         });
         if (lexicalPathResult.ok) {
             return {
@@ -305,11 +213,17 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
                 fallbackPath: lexicalPathResult.path,
             };
         }
-        if (!rootRealPath || !raw || !path.isAbsolute(raw)) {
+        if (!rootRealPath ||
+            !raw ||
+            !path.isAbsolute(raw) ||
+            hasWindowsPathAlias(raw, "filesystem")) {
             return lexicalPathResult;
         }
         try {
-            const resolvedExistingPath = fsSync.realpathSync.native(raw);
+            const resolvedExistingPath = realpathSync.native(pathForWindowsFilesystem(raw));
+            if (hasWindowsPathAlias(resolvedExistingPath, "filesystem")) {
+                return lexicalPathResult;
+            }
             const relativePath = path.relative(rootRealPath, resolvedExistingPath);
             if (!isInRoot(relativePath)) {
                 return lexicalPathResult;
@@ -325,7 +239,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
         }
     };
     const resolvedPaths = [];
-    for (const raw of params.requestedPaths) {
+    for (const raw of requestedPaths) {
         const pathResult = await resolveExistingRelativePath(raw);
         if (!pathResult.ok) {
             return { ok: false, error: pathResult.error };
@@ -348,16 +262,17 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
                     await assertNoSymlinkSegments({
                         rootDir,
                         targetPath: pathResult.fallbackPath,
-                        scopeLabel: params.scopeLabel,
+                        scopeLabel,
                     });
                     const existingPath = await resolveNearestExistingPath(pathResult.fallbackPath);
-                    const existingRealPath = fsSync.realpathSync.native(existingPath);
-                    if (!isPathInside(rootRealPath, existingRealPath)) {
-                        return invalidPath(params.scopeLabel);
+                    const existingRealPath = realpathSync.native(pathForWindowsFilesystem(existingPath));
+                    if (hasWindowsPathAlias(existingRealPath, "filesystem") ||
+                        !isPathInside(rootRealPath, existingRealPath)) {
+                        return invalidPath(scopeLabel);
                     }
                 }
                 catch {
-                    return invalidPath(params.scopeLabel);
+                    return invalidPath(scopeLabel);
                 }
                 resolvedPaths.push(pathResult.fallbackPath);
                 continue;
@@ -365,12 +280,12 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
             if (err instanceof FsSafeError && err.code === "outside-workspace") {
                 return {
                     ok: false,
-                    error: `File is outside ${params.scopeLabel}`,
+                    error: `File is outside ${scopeLabel}`,
                 };
             }
             return {
                 ok: false,
-                error: `Invalid path: must stay within ${params.scopeLabel} and be a regular non-symlink file`,
+                error: `Invalid path: must stay within ${scopeLabel} and be a regular non-symlink file`,
             };
         }
         finally {

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

@@ -0,0 +1,11 @@
+export type { OpenResult, WritableOpenResult, } from "./root-impl.js";
+export type { HardlinkPolicy, RootAppendOptions, RootCopyOptions, RootCopySource, RootCreateJsonOptions, RootCreateOptions, RootCreateStreamOptions, RootDefaults, RootMkdirOptions, RootMoveOptions, RootOpenOptions, RootOpenWritableOptions, RootOptions, RootReadOptions, RootRemoveOptions, RootWriteJsonOptions, RootWriteOptions, WritableOpenMode, } from "./root-options.js";
+export type { DenyMutationPolicy } from "./deny-mutations.js";
+export type { RenameIdentityPolicy } from "./pinned-write-types.js";
+export type { MutationSymlinkPolicy, SymlinkPolicy, } from "./root-symlink-policy.js";
+export type { ReadResult } from "./read-opened-file.js";
+export type { RootCopyPublicationReceipt } from "./copy-publication.js";
+export type { CopyCloneMode } from "./copy-policy.js";
+export type { RootEntriesOptions } from "./root-entries.js";
+export type { ContainmentGuarantee } from "./containment.js";
+export type { RootWalkDataEntry, RootWalkDataEntryKind, RootWalkDirectoryErrorBehavior, RootWalkEntry, RootWalkEntryFilter, RootWalkEntryFilterResult, RootWalkEntryKind, RootWalkLimitBehavior, RootWalkOptions, RootWalkSymlinkPolicy, } from "./root-walk.js";

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,25 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { type RootContext } from "./root-context.js";
+import type { HardlinkPolicy } from "./root-options.js";
+import type { SymlinkPolicy } from "./root-symlink-policy.js";
+export declare function inspectOpenedPathIdentitySync(filePath: string, symlinks: SymlinkPolicy | undefined): BigIntStats;
+type OwnedRootReadHandle = {
+    handle: FileHandle;
+    stat: {
+        nlink: number;
+    };
+};
+export declare function admitRootReadHandle<T extends OwnedRootReadHandle>(params: {
+    root: RootContext;
+    filePath: string;
+    opened: T;
+    identity: BigIntStats;
+    hardlinks?: HardlinkPolicy;
+    symlinks?: SymlinkPolicy;
+    beforeFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+    afterPathIdentityCheck?: (filePath: string, handle: FileHandle) => void;
+}): Promise<T & {
+    realPath: string;
+}>;
+export {};

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

@@ -0,0 +1,86 @@
+import fsSync, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { openedPathResolutionError, recordOpenedFileFailure } from "./opened-file-failure.js";
+import { isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootIdentityCurrentSync } from "./root-context.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+function resolveFinalOpenedRealPath(filePath) {
+    try {
+        return realpathSync.native(filePath);
+    }
+    catch (error) {
+        // Windows can report a deleted-but-open file through either resolver
+        // failure. Only the same-descriptor unlink proof may consume this receipt.
+        if (process.platform === "win32" && error instanceof Error &&
+            ["EPERM", "EBADF"].includes(error.code ?? "")) {
+            throw openedPathResolutionError(error);
+        }
+        throw error;
+    }
+}
+export function inspectOpenedPathIdentitySync(filePath, symlinks) {
+    const stat = symlinks === "follow-within-root"
+        ? fsSync.statSync(filePath, { bigint: true })
+        : fsSync.lstatSync(filePath, { bigint: true });
+    if (stat.isSymbolicLink() && symlinks !== "follow-within-root") {
+        throw new FsSafeError("symlink", "symlink not allowed");
+    }
+    return stat;
+}
+export async function admitRootReadHandle(params) {
+    try {
+        if (params.hardlinks !== "allow" && params.opened.stat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+        if (params.beforeFinalFence) {
+            await params.beforeFinalFence(params.filePath, params.opened.handle);
+        }
+        try {
+            assertRootIdentityCurrentSync(params.root);
+            let realPath;
+            try {
+                const current = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
+                if (params.hardlinks !== "allow" && current.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                const canonicalPath = resolveFinalOpenedRealPath(params.filePath);
+                assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
+                const admittedRealPath = admitPathInsideRoot({
+                    rootPath: params.root.rootReal,
+                    candidatePath: canonicalPath,
+                    rootIdentity: params.root.rootIdentity,
+                });
+                if (!admittedRealPath) {
+                    throw openedPathResolutionError(outsideWorkspaceError());
+                }
+                // This is a fresh no-follow observation even when canonicalPath and
+                // filePath have the same spelling; realpath may have raced a replacement.
+                const canonical = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
+                if (params.hardlinks !== "allow" && canonical.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                realPath = admittedRealPath.path;
+            }
+            catch (error) {
+                throw isNotFoundPathError(error)
+                    ? openedPathResolutionError(fileNotFoundError())
+                    : error;
+            }
+            params.afterPathIdentityCheck?.(params.filePath, params.opened.handle);
+            assertRootIdentityCurrentSync(params.root);
+            return { ...params.opened, realPath };
+        }
+        catch (error) {
+            if (params.identity.nlink <= 1n) {
+                await recordOpenedFileFailure(error, params.opened.handle, params.filePath, params.identity);
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        await params.opened.handle.close().catch(() => { });
+        throw error;
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { BigIntStats } from "node:fs";
+type ExactDirectoryIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
+export type RemovalDirectoryAssertion = Readonly<{
+    path: string;
+    dev: bigint;
+    ino: bigint;
+    numericDev?: number;
+    numericIno?: number;
+    platform: NodeJS.Platform;
+    realPath?: string;
+}>;
+export declare function createRemovalDirectoryAssertion(path: string, identity: ExactDirectoryIdentity, realPath?: string, platform?: NodeJS.Platform): RemovalDirectoryAssertion;
+export declare function assertRemovalDirectoryCurrent(assertion: RemovalDirectoryAssertion): void;
+export {};