@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,13 +1,90 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isNotFoundPathError } from "./path.js";
-function isFilesystemRoot(candidate) {
-    return path.parse(candidate).root === candidate;
+import { FsSafeError } from "./errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { errorCauseOptions } from "./root-errors.js";
+export function absolutePathWithRawSegments(candidate) {
+    if (path.sep !== "\\") {
+        if (path.isAbsolute(candidate))
+            return candidate;
+        const base = process.cwd();
+        return `${base}${base.endsWith(path.sep) ? "" : path.sep}${candidate}`;
+    }
+    const raw = path.sep === "\\" ? candidate.replaceAll("/", "\\") : candidate;
+    const absolute = path.isAbsolute(raw);
+    if (absolute && raw[0] !== "\\")
+        return raw;
+    const drive = path.parse(raw).root;
+    if (absolute && drive !== "\\")
+        return raw;
+    const base = drive ? path.resolve(drive) : process.cwd();
+    return `${base}${base.endsWith(path.sep) ? "" : path.sep}${raw.slice(drive.length)}`;
+}
+export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, options = {}) {
+    assertNoWindowsPathAlias(candidate);
+    assertNoWindowsPathAlias(rootCanonicalPath);
+    const absolute = absolutePathWithRawSegments(candidate);
+    const raw = process.platform === "win32" ? absolute.replaceAll("/", path.sep) : absolute;
+    const filesystemRoot = path.parse(raw).root;
+    const segments = raw.slice(filesystemRoot.length).split(path.sep);
+    const finalComponentIndex = segments.findLastIndex(segment => segment !== "" && segment !== ".");
+    let prefix = filesystemRoot;
+    let traversedSymlink = false;
+    const identityCache = process.platform === "win32" ? new Map() : undefined;
+    for (let index = 0; index < segments.length; index += 1) {
+        prefix += `${prefix.endsWith(path.sep) ? "" : path.sep}${segments[index]}`;
+        let canonical;
+        let isSymlink = false;
+        try {
+            const operationPath = pathForWindowsFilesystem(prefix);
+            const stat = fs.lstatSync(operationPath);
+            isSymlink = stat.isSymbolicLink();
+            // Check the original leaf before canonicalization can erase an entry alias.
+            if (isSymlink && options.rejectFinalSymlink && index === finalComponentIndex) {
+                throw new FsSafeError("symlink", "final symlink not allowed");
+            }
+            if (!isSymlink && !stat.isDirectory() && index < segments.length - 1)
+                return undefined;
+            traversedSymlink ||= isSymlink;
+            canonical = realpathSync.native(operationPath);
+            assertNoWindowsPathAlias(canonical);
+            if (isSymlink && index < segments.length - 1 &&
+                !fs.statSync(pathForWindowsFilesystem(canonical)).isDirectory())
+                return undefined;
+            if (isSymlink && !isPathInside(rootCanonicalPath, canonical) && !isPathInside(canonical, rootCanonicalPath)) {
+                throw new FsSafeError("outside-workspace", `symlink prefix resolves outside the root ancestry: ${formatErrorDetail(candidate)}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof FsSafeError)
+                throw error;
+            if (isSymlink)
+                return undefined;
+            continue;
+        }
+        const admitted = admitPathInsideRoot({
+            rootPath: rootCanonicalPath,
+            candidatePath: canonical,
+            rootIdentity: options.rootIdentity,
+            identityCache,
+        });
+        if (!admitted)
+            continue;
+        if (options.rejectSymlinks && traversedSymlink) {
+            throw new FsSafeError("symlink", "symlink path component not allowed");
+        }
+        return [admitted.relativePath, ...segments.slice(index + 1)]
+            .filter(Boolean).join(path.sep);
+    }
+    return undefined;
 }
-async function pathExists(targetPath) {
+function pathExists(targetPath) {
     try {
-        fs.lstatSync(targetPath);
-        return true;
+        return fs.lstatSync(pathForWindowsFilesystem(targetPath), { throwIfNoEntry: false }) !== undefined;
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -17,52 +94,67 @@ async function pathExists(targetPath) {
     }
 }
 export async function resolvePathViaExistingAncestor(targetPath) {
-    const normalized = path.resolve(targetPath);
+    return resolveExistingAncestor(targetPath, "native");
+}
+function pathExistsSync(targetPath) {
+    return fs.existsSync(pathForWindowsFilesystem(targetPath));
+}
+export function resolvePathViaExistingAncestorSync(targetPath) {
+    return resolveExistingAncestor(targetPath, "ordinary");
+}
+export function resolveExistingAncestor(targetPath, mode) {
+    const exists = mode === "native" ? pathExists : pathExistsSync;
+    const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
+    assertNoWindowsPathAlias(targetPath);
+    const normalized = resolvePathPreservingWindowsRoot(targetPath);
+    assertNoWindowsPathAlias(normalized);
     let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) && !(await pathExists(cursor))) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
+    const filesystemRoot = path.parse(normalized).root;
+    while (cursor !== filesystemRoot &&
+        !exists(cursor)) {
+        cursor = path.dirname(cursor);
     }
-    if (!(await pathExists(cursor))) {
+    if (!exists(cursor)) {
         return normalized;
     }
+    let rawResolvedAncestor;
     try {
-        const resolvedAncestor = path.resolve(fs.realpathSync.native(cursor));
-        return missingSuffix.length === 0
-            ? resolvedAncestor
-            : path.resolve(resolvedAncestor, ...missingSuffix);
+        rawResolvedAncestor = canonicalize(pathForWindowsFilesystem(cursor));
     }
     catch {
         return normalized;
     }
+    assertNoWindowsPathAlias(rawResolvedAncestor);
+    const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
+    assertNoWindowsPathAlias(resolvedAncestor);
+    // Keep a leading suffix separator relative to the canonical ancestor.
+    const resolved = cursor === normalized
+        ? resolvedAncestor
+        : path.resolve(resolvedAncestor, `.${path.sep}${normalized.slice(cursor.length)}`);
+    assertNoWindowsPathAlias(resolved);
+    return resolved;
 }
-export function resolvePathViaExistingAncestorSync(targetPath) {
-    const normalized = path.resolve(targetPath);
-    let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) && !fs.existsSync(cursor)) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
-    }
-    if (!fs.existsSync(cursor)) {
-        return normalized;
-    }
+export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved) {
     try {
-        const resolvedAncestor = path.resolve(fs.realpathSync(cursor));
-        return missingSuffix.length === 0
-            ? resolvedAncestor
-            : path.resolve(resolvedAncestor, ...missingSuffix);
+        const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
+        const rawRealPath = canonicalize(symlinkPath);
+        assertNoWindowsPathAlias(rawRealPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        const realPath = resolvePathPreservingWindowsRoot(rawRealPath);
+        assertNoWindowsPathAlias(realPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return realPath;
     }
-    catch {
-        return normalized;
+    catch (error) {
+        if (isSymlinkOpenError(error) || (rejectUnresolved && isNotFoundPathError(error))) {
+            throw new FsSafeError("symlink", "symlink path could not be resolved", errorCauseOptions(error));
+        }
+        if (!isNotFoundPathError(error))
+            throw error;
+        const linkTarget = fs.readlinkSync(symlinkPath);
+        assertNoWindowsPathAlias(linkTarget, "filesystem", "symlink target uses a Windows filesystem namespace alias");
+        const linkDir = resolvePathPreservingWindowsRoot(path.dirname(symlinkPath));
+        const targetPath = resolvePathFromBasePreservingWindowsRoot(linkDir, linkTarget);
+        const resolved = resolveExistingAncestor(targetPath, mode);
+        assertNoWindowsPathAlias(resolved, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return resolved;
     }
 }

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

@@ -0,0 +1,62 @@
+import fs, { type BigIntStats } from "node:fs";
+import { type DirectoryObservationGuard } from "./directory-guard.js";
+import { type NativeDirectoryObservationBackend, type NativeDirectoryObservationGuard } from "./native-directory-observation.js";
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+import { type StatObservationReceipt } from "./stat-observation.js";
+export type RootPathObservationKind = "stat" | "directory";
+export type RootPathDirectoryObservationGuard = DirectoryObservationGuard | NativeDirectoryObservationGuard;
+export type RootPathTargetObservation = StatObservationReceipt | NativeDirectoryObservationGuard;
+/** An exact receipt owned by one stat/list operation. Never cache it. */
+export type RootPathObservationReceipt = {
+    kind: RootPathObservationKind;
+    rootGuard: DirectoryObservationGuard;
+    directoryGuard: RootPathDirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+    targetPath: string;
+    target: RootPathTargetObservation;
+};
+/** A failed initial target lookup must not discard its already admitted parent. */
+export type RootPathParentObservationReceipt = Omit<RootPathObservationReceipt, "kind" | "target"> & {
+    kind: "stat-parent";
+};
+export type RootPathObservationRequest = {
+    kind: RootPathObservationKind;
+    rootGuard: DirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+};
+export type RootPathTraversalObservation = {
+    enabled: boolean;
+    request: RootPathObservationRequest;
+    targetIndex: number;
+    directoryIndex: number;
+    directoryGuard?: RootPathDirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+    targetPath?: string;
+    target?: RootPathTargetObservation;
+};
+export type RootPathObservedTraversalEntry = StatObservationReceipt | {
+    stat: fs.Stats | BigIntStats;
+    identity?: undefined;
+} | NativeDirectoryObservationGuard;
+export declare class RootPathObservationError extends Error {
+    readonly error: unknown;
+    readonly parentReceipt?: RootPathParentObservationReceipt | undefined;
+    readonly traversalFailure: boolean;
+    constructor(error: unknown, parentReceipt?: RootPathParentObservationReceipt | undefined, traversalFailure?: boolean);
+}
+export type RootPathTraversalContext = {
+    observationEligible: boolean;
+    rootPath: string;
+    rootCanonicalPath: string;
+    resolveParams: {
+        rootIdentity?: RootBoundaryIdentity;
+    };
+    state: {
+        finalComponentIndex: number;
+        relativePath: string;
+        segments: string[];
+    };
+};
+export declare function createRootPathTraversalObservation(context: RootPathTraversalContext, request?: RootPathObservationRequest): RootPathTraversalObservation | undefined;
+export declare function inspectRootPathTraversalEntry(pathname: string, directorySlot: boolean, observation: RootPathTraversalObservation): RootPathObservedTraversalEntry;
+export declare function captureRootPathObservedDirectory(observation: RootPathTraversalObservation, observed: RootPathObservedTraversalEntry, publicPath: string, canonicalPath: string, rootCanonicalPath: string, rootIdentity?: RootBoundaryIdentity): boolean;

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

@@ -0,0 +1,180 @@
+import fs, {} from "node:fs";
+import { extendDirectoryObservationGuard, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { extendNativeDirectoryObservationGuard, inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
+import { admitPathInsideRoot, } from "./root-boundary.js";
+import { realpathSync } from "./realpath.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
+// Observation-only failures happen after ordinary traversal has admitted the
+// name. Keep them distinguishable so Root preserves existing error precedence.
+export class RootPathObservationError extends Error {
+    error;
+    parentReceipt;
+    traversalFailure;
+    constructor(error, parentReceipt, traversalFailure = false) {
+        super("root path observation failed", { cause: error });
+        this.error = error;
+        this.parentReceipt = parentReceipt;
+        this.traversalFailure = traversalFailure;
+        this.name = "RootPathObservationError";
+    }
+}
+function straightTraversalPath(value) {
+    if (value.length === 0)
+        return false;
+    const windows = process.platform === "win32";
+    let segmentStart = 0;
+    for (let index = 0; index <= value.length; index += 1) {
+        const separator = index === value.length || value[index] === "/" ||
+            (windows && value[index] === "\\");
+        if (!separator)
+            continue;
+        const segmentLength = index - segmentStart;
+        if (segmentLength === 0 ||
+            (segmentLength === 1 && value.charCodeAt(segmentStart) === 0x2e) ||
+            (segmentLength === 2 && value.charCodeAt(segmentStart) === 0x2e &&
+                value.charCodeAt(segmentStart + 1) === 0x2e))
+            return false;
+        segmentStart = index + 1;
+    }
+    return true;
+}
+export function createRootPathTraversalObservation(context, request) {
+    const { state } = context;
+    const rootTraversal = state.finalComponentIndex < 0 &&
+        (state.relativePath === "" || state.relativePath === ".");
+    if (!request || !context.observationEligible ||
+        request.rootGuard.dir !== context.rootCanonicalPath ||
+        request.rootGuard.realPath !== context.rootCanonicalPath ||
+        context.rootPath !== context.rootCanonicalPath ||
+        (!rootTraversal && !straightTraversalPath(state.relativePath)) ||
+        (!rootTraversal && state.finalComponentIndex !== state.segments.length - 1))
+        return undefined;
+    if (state.finalComponentIndex >= 0) {
+        const directoryIndex = request.kind === "stat"
+            ? state.finalComponentIndex - 1
+            : state.finalComponentIndex;
+        return {
+            enabled: true,
+            request,
+            targetIndex: state.finalComponentIndex,
+            directoryIndex,
+            directoryGuard: directoryIndex < 0 ? request.rootGuard : undefined,
+            // A direct-child stat has no selected-directory slot at which the
+            // optional helper can establish a receipt. Keep its final Root fence on
+            // the established JavaScript path so helper unavailability cannot first
+            // appear after the target has been admitted.
+            directoryObserver: directoryIndex < 0 ? undefined : request.directoryObserver,
+        };
+    }
+    if (!rootTraversal)
+        return undefined;
+    let directoryGuard = request.rootGuard;
+    // Root-only stat likewise has no pre-admission helper observation. Root
+    // listing below does establish one and may safely retain the backend.
+    let directoryObserver = request.kind === "stat" ? undefined : request.directoryObserver;
+    if (request.kind === "directory") {
+        if (directoryObserver) {
+            try {
+                const observed = inspectNativeDirectoryObservation(directoryObserver, request.rootGuard.dir, request.rootGuard.identity);
+                const admitted = admitPathInsideRoot({
+                    rootPath: context.rootCanonicalPath,
+                    candidatePath: observed.realPath,
+                    rootIdentity: context.resolveParams.rootIdentity,
+                });
+                if (!admitted || admitted.relativePath !== "") {
+                    throw new FsSafeError("path-mismatch", "root path changed during operation");
+                }
+                observed.realPath = admitted.path;
+                directoryGuard = extendNativeDirectoryObservationGuard(observed, request.rootGuard.dir);
+            }
+            catch (error) {
+                if (error instanceof FsSafeError && error.code === "path-mismatch") {
+                    throw new RootPathObservationError(error);
+                }
+                directoryObserver = undefined;
+            }
+        }
+        if (!directoryObserver) {
+            try {
+                const admitted = admitPathInsideRoot({
+                    rootPath: context.rootCanonicalPath,
+                    candidatePath: realpathSync.native(request.rootGuard.dir),
+                    rootIdentity: context.resolveParams.rootIdentity,
+                });
+                if (!admitted || admitted.relativePath !== "") {
+                    throw new FsSafeError("path-mismatch", "root path changed during operation");
+                }
+            }
+            catch (error) {
+                throw new RootPathObservationError(error);
+            }
+        }
+    }
+    return {
+        enabled: true,
+        request,
+        targetIndex: -1,
+        directoryIndex: -1,
+        directoryGuard,
+        directoryObserver,
+        targetPath: context.rootCanonicalPath,
+        target: directoryGuard,
+    };
+}
+export function inspectRootPathTraversalEntry(pathname, directorySlot, observation) {
+    if (directorySlot && observation.directoryObserver) {
+        try {
+            return extendNativeDirectoryObservationGuard(inspectNativeDirectoryObservation(observation.directoryObserver, pathname), pathname);
+        }
+        catch {
+            // This directory has not been admitted yet. Preserve the established
+            // resolver and error ordering when the optional observation is unusable.
+            observation.directoryObserver = undefined;
+        }
+    }
+    const first = process.platform === "win32"
+        ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname);
+    if (first.isSymbolicLink() || (directorySlot && !first.isDirectory()))
+        return { stat: first };
+    try {
+        return inspectStatObservationSync(bigint => bigint
+            ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname), undefined, first);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch") {
+            throw new RootPathObservationError(error);
+        }
+        throw error;
+    }
+}
+export function captureRootPathObservedDirectory(observation, observed, publicPath, canonicalPath, rootCanonicalPath, rootIdentity) {
+    if (!isNativeDirectoryObservationGuard(observed) && !observed.stat.isDirectory())
+        return false;
+    let realPath;
+    try {
+        realPath = isNativeDirectoryObservationGuard(observed)
+            ? observed.realPath
+            : realpathSync.native(canonicalPath);
+    }
+    catch (error) {
+        throw new RootPathObservationError(error);
+    }
+    const admitted = admitPathInsideRoot({
+        rootPath: rootCanonicalPath,
+        candidatePath: realPath,
+        rootIdentity,
+    });
+    if (!admitted) {
+        throw new RootPathObservationError(new FsSafeError("outside-workspace", "directory is outside workspace root"));
+    }
+    if (isNativeDirectoryObservationGuard(observed)) {
+        observed.dir = publicPath;
+        observed.realPath = admitted.path;
+        observation.directoryGuard = observed;
+    }
+    else {
+        observation.directoryGuard = extendDirectoryObservationGuard(observed, publicPath, admitted.path);
+    }
+    return true;
+}

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

@@ -0,0 +1,4 @@
+import type { RootContext } from "./root-context.js";
+import type { RootPathObservationReceipt } from "./root-path.js";
+import type { PathStat } from "./types.js";
+export declare function statResolvedPathInRoot(root: RootContext, resolvedPath: string, receipt?: RootPathObservationReceipt): Promise<PathStat>;

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

@@ -0,0 +1,151 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { fileObservation, recordFileObservationFailure } from "./file-observation.js";
+import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
+import { assertRootDirectoryObservationGuard, assertRootPathObservationReceiptCurrent, createRootDirectoryObservationGuard, pathStatFromStats, } from "./root-directory-list.js";
+import { errorCauseOptions, fileNotFoundError } from "./root-errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertStatObservationSync } from "./stat-observation.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function singleLinkFileIdentity(stat) {
+    if (!stat?.isFile() || stat.isSymbolicLink() || (stat.nlink !== 1 && stat.nlink !== 1n))
+        return;
+    const exact = (value) => typeof value === "bigint" ? value : Number.isSafeInteger(value) ? BigInt(value) : undefined;
+    const dev = exact(stat.dev), ino = exact(stat.ino);
+    if (dev === undefined || ino === undefined || dev < 0n || ino < 0n ||
+        (process.platform === "win32" && (dev === 0n || ino === 0n)))
+        return;
+    return { dev, ino };
+}
+async function captureChangedObservedFile(error, pathname, before, observed, assertParents, proof) {
+    try {
+        const previous = singleLinkFileIdentity(before), current = singleLinkFileIdentity(observed);
+        if (!previous || !current || (previous.dev === current.dev && previous.ino === current.ino))
+            return;
+        await assertParents();
+        // A changed metadata probe grants only a fresh acquisition attempt, never ownership.
+        proof.failure = { error, kind: `stat-leaf-changed:${pathname}` };
+    }
+    catch {
+        // Ambiguous file or ancestry observations retain the original public error.
+    }
+}
+async function missingObservedFileError(cause, pathname, before, assertParents, proof) {
+    const failure = new FsSafeError("path-mismatch", "file changed during operation", errorCauseOptions(cause));
+    if (hasNodeErrorCode(cause, "ENOENT") && before?.isFile() && !before.isSymbolicLink() &&
+        (before.nlink === 1 || before.nlink === 1n)) {
+        try {
+            await assertParents();
+            // Metadata loss permits discarding a probe, never reading or owning a file.
+            proof.failure = { error: failure, kind: `stat-leaf-missing:${pathname}` };
+        }
+        catch {
+            // Keep the public mismatch and withhold provenance when ancestry changed.
+        }
+    }
+    return failure;
+}
+export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
+    const proof = {};
+    try {
+        // Nested observations in a hook cannot grant this invocation discard authority.
+        return await fileObservation().run(() => statObservedPathInRoot(root, resolvedPath, proof, receipt));
+    }
+    catch (error) {
+        const failure = proof.failure;
+        if (failure && failure.error === error)
+            recordFileObservationFailure(error, failure.kind);
+        throw error;
+    }
+}
+async function statObservedPathInRoot(root, resolvedPath, proof, receipt) {
+    let admittedTarget = false;
+    try {
+        if (receipt) {
+            if (receipt.kind !== "stat" || receipt.targetPath !== resolvedPath) {
+                throw new FsSafeError("path-mismatch", "file observation receipt does not match target");
+            }
+            admittedTarget = true;
+            const beforeObservation = getFsSafeTestHooks()?.beforeRootStatObservation;
+            if (beforeObservation)
+                await beforeObservation(resolvedPath);
+            let observed;
+            let sample, samples = 0;
+            const comparison = fileObservation();
+            try {
+                observed = comparison.run(() => assertStatObservationSync(bigint => {
+                    sample = bigint ? fsSync.lstatSync(resolvedPath, { bigint: true }) : fsSync.lstatSync(resolvedPath);
+                    samples += 1;
+                    return sample;
+                }, receipt.target.identity));
+            }
+            catch (error) {
+                if (isNotFoundPathError(error)) {
+                    throw await missingObservedFileError(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
+                }
+                if (comparison.has(error, "identity"))
+                    await captureChangedObservedFile(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, samples === 1 ? sample : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
+                throw error;
+            }
+            if (observed.isSymbolicLink()) {
+                throw new FsSafeError("path-mismatch", "file changed during operation");
+            }
+            assertRootPathObservationReceiptCurrent(root, receipt, observed);
+            return pathStatFromStats(observed);
+        }
+        const guardPath = resolvedPath === root.rootReal ? root.rootReal : path.dirname(resolvedPath);
+        const parentGuard = guardPath === root.rootReal && root.rootGuard
+            ? root.rootGuard
+            : await createRootDirectoryObservationGuard(root, guardPath);
+        let expected;
+        try {
+            const beforeInitialObservation = getFsSafeTestHooks()?.beforeRootStatInitialObservation;
+            if (beforeInitialObservation)
+                await beforeInitialObservation(resolvedPath);
+            expected = inspectFileIdentitySync(() => fsSync.lstatSync(resolvedPath, { bigint: true }));
+            if (expected.isSymbolicLink()) {
+                throw new FsSafeError("path-mismatch", "file changed during operation");
+            }
+        }
+        catch (error) {
+            // No initial target error is safe to expose until the admitted parent is
+            // proven current; a redirect must win over an ordinary lookup failure.
+            await assertRootDirectoryObservationGuard(root, parentGuard);
+            throw error;
+        }
+        admittedTarget = true;
+        const beforeObservation = getFsSafeTestHooks()?.beforeRootStatObservation;
+        if (beforeObservation)
+            await beforeObservation(resolvedPath);
+        let observed;
+        let sample, samples = 0;
+        const comparison = fileObservation();
+        try {
+            observed = comparison.run(() => inspectFileIdentitySync(() => {
+                sample = fsSync.lstatSync(resolvedPath, { bigint: true });
+                samples += 1;
+                return sample;
+            }, expected));
+        }
+        catch (error) {
+            if (isNotFoundPathError(error)) {
+                throw await missingObservedFileError(error, resolvedPath, expected, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
+            }
+            if (comparison.has(error, "identity"))
+                await captureChangedObservedFile(error, resolvedPath, expected, samples === 1 ? sample : undefined, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
+            throw error;
+        }
+        if (observed.isSymbolicLink()) {
+            throw new FsSafeError("path-mismatch", "file changed during operation");
+        }
+        await assertRootDirectoryObservationGuard(root, parentGuard);
+        return pathStatFromStats(observed);
+    }
+    catch (error) {
+        if (!admittedTarget && isNotFoundPathError(error)) {
+            throw fileNotFoundError(error instanceof Error ? error : undefined);
+        }
+        throw error;
+    }
+}

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

@@ -1,4 +1,8 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+import { type RootPathObservationReceipt, type RootPathObservationRequest } from "./root-path-observation.js";
+import type { RemovalPathReceipts } from "./root-remove-receipt.js";
 export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
+export { RootPathObservationError, type RootPathDirectoryObservationGuard, type RootPathObservationKind, type RootPathObservationReceipt, type RootPathParentObservationReceipt, type RootPathObservationRequest, type RootPathTargetObservation, } from "./root-path-observation.js";
 type RootPathIntent = "read" | "write" | "create" | "delete" | "stat";
 export type RootPathAliasPolicy = {
     allowFinalSymlinkForUnlink?: boolean;
@@ -21,9 +25,11 @@ type ResolveRootPathParams = {
     intent?: RootPathIntent;
     policy?: RootPathAliasPolicy;
     rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
     rejectUnresolvedSymlinks?: boolean;
     skipLexicalRootCheck?: boolean;
     rootCanonicalPath?: string;
+    rootIdentity?: RootBoundaryIdentity;
 };
 type ResolvedRootPathKind = "missing" | "file" | "directory" | "symlink" | "other";
 export type ResolvedRootPath = {
@@ -35,6 +41,13 @@ export type ResolvedRootPath = {
     exists: boolean;
     kind: ResolvedRootPathKind;
 };
+export type ObservedRootPath = {
+    resolved: ResolvedRootPath;
+    receipt?: RootPathObservationReceipt;
+};
 export declare function resolveRootPath(params: ResolveRootPathParams): Promise<ResolvedRootPath>;
+export declare function resolveRootPathWithCanonicalRootObservation(params: ResolveRootPathParams, observeRoot: (rootCanonicalPath: string) => void): Promise<ResolvedRootPath>;
+export declare function resolveRootPathWithObservation(params: ResolveRootPathParams, request: RootPathObservationRequest): Promise<ObservedRootPath>;
+export declare function resolveRootPathForRemoval(params: ResolveRootPathParams, receipts: RemovalPathReceipts): Promise<ResolvedRootPath>;
 export declare function resolveRootPathSync(params: ResolveRootPathParams): ResolvedRootPath;
-//# sourceMappingURL=root-path.d.ts.map
+export declare function resolveRootPathSyncWithCanonicalRootObservation(params: ResolveRootPathParams, observeRoot: (rootCanonicalPath: string) => void): ResolvedRootPath;