@openclaw/openshell-sandbox 2026.9.6 → 2026.9.8

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

@@ -7,7 +7,7 @@ function helperUnavailable(message, cause) {
         ...(cause instanceof Error ? { cause } : {}),
     });
 }
-function copyOperationalCode(target, source) {
+export function copyOperationalCode(target, source) {
     const code = source?.code;
     if (typeof code === "string") {
         Object.defineProperty(target, "code", { configurable: true, value: code });

package/node_modules/@openclaw/fs-safe/dist/retained-file-types.d.ts

@@ -0,0 +1,50 @@
+import type { StagedFileReceipt } from "./staged-file-types.js";
+/** Exact producer observations: never supply rounded Number identities. */
+export type RetainedFileExpected = Readonly<Pick<StagedFileReceipt["identity"], "dev" | "ino" | "size" | "mtimeNs" | "ctimeNs"> & {
+    /** Lowercase SHA-256 of the producer's expected bytes. */
+    sha256: string;
+}>;
+export type RetainedFileIssue = Readonly<{
+    phase: string;
+    code: string;
+    message: string;
+    cause?: unknown;
+}>;
+/** Descriptive facts, not a deletion capability or a durable transaction receipt. */
+export type RetainedFileResult = Readonly<{
+    status: "unsupported" | "not-attempted" | "preserved-mismatch" | "disposition-accepted" | "name-absent-after-settlement" | "failed" | "indeterminate";
+    phase: string;
+    /** Full native 64-bit volume serial and 128-bit file ID, when observed. */
+    identity?: string;
+    disposition: "not-attempted" | "accepted" | "rejected" | "indeterminate";
+    namespace: "not-observed" | "absent" | "original" | "foreign" | "unknown";
+    resources: "closed" | "close-failed";
+    persistence: "not-proven";
+    errors: readonly RetainedFileIssue[];
+}>;
+export type RetainedFileReceipt = Readonly<{
+    directory: string;
+    parent: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>;
+    basename: string;
+    expected: RetainedFileExpected;
+    identity: string;
+}>;
+export interface RetainedFile extends Disposable {
+    readonly receipt: RetainedFileReceipt;
+    /** One-shot, synchronous authority admission; always settles owned resources. */
+    remove(): RetainedFileResult;
+    /** Closes only. Never requests deletion, including after an exception. */
+    dispose(): RetainedFileResult;
+}
+export type RetainedFileAdmission = Readonly<{
+    status: "retained";
+    file: RetainedFile;
+}> | RetainedFileResult;
+export type RetainFileInDirectoryOptions = Readonly<Pick<RetainedFileReceipt, "directory" | "parent" | "basename" | "expected"> & {
+    assertBeforeMutation: () => void;
+    /** Synchronous verification budget, default 16 MiB; maximum 64 MiB. */
+    maxBytes?: number;
+}>;

package/node_modules/@openclaw/fs-safe/dist/retained-file-types.js

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

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

@@ -0,0 +1,3 @@
+import type { RetainedFileAdmission, RetainFileInDirectoryOptions } from "./retained-file-types.js";
+/** Retain one existing regular file on supported local Windows NTFS. No fallback. */
+export declare function retainFileInDirectory(options: RetainFileInDirectoryOptions): RetainedFileAdmission;

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

@@ -0,0 +1,121 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+function freeze(result) {
+    return Object.freeze({ ...result, errors: Object.freeze(result.errors.map((error) => Object.freeze({ ...error }))) });
+}
+function unsupported(cause) {
+    return freeze({ status: "unsupported", phase: "admission", disposition: "not-attempted",
+        namespace: "not-observed", resources: "closed", persistence: "not-proven",
+        errors: [{ phase: "admission", code: "helper-unavailable",
+                message: "existing-file retention requires the maintained Windows native capability", cause }] });
+}
+function exact(value, name, zero = false) {
+    if (typeof value !== "bigint" || value < (zero ? 0n : 1n) || value > 0xffffffffffffffffn) {
+        throw new TypeError(`${name} must be an exact ${zero ? "nonnegative" : "positive"} unsigned 64-bit bigint`);
+    }
+    return value;
+}
+class Owner {
+    receipt;
+    #native;
+    #assert;
+    #result;
+    #running = false;
+    #reentered = false;
+    constructor(native, receipt, assertion) {
+        this.#native = native;
+        this.receipt = receipt;
+        this.#assert = assertion;
+        Object.freeze(this);
+    }
+    #settle(remove) {
+        if (this.#result)
+            return this.#result;
+        if (this.#running) {
+            this.#reentered = true;
+            throw new TypeError("retained-file settlement cannot be reentered");
+        }
+        this.#running = true;
+        let rejection;
+        if (remove) {
+            try {
+                assertSynchronousCallbackResult(this.#assert(), "assertBeforeMutation");
+                if (this.#reentered)
+                    throw new TypeError("retained-file authority reentered settlement");
+            }
+            catch (cause) {
+                rejection = { cause };
+            }
+        }
+        try {
+            const result = this.#native.settle(remove && !rejection);
+            this.#result = freeze(rejection ? { ...result, phase: "authority", errors: [
+                    { phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause },
+                    ...result.errors,
+                ] } : result);
+        }
+        catch (cause) {
+            // An unexpected binding exception cannot establish native effect or close.
+            // Do not retry or release a dependency on an unknown native outcome.
+            this.#result = freeze({ status: "indeterminate", phase: "binding", identity: this.receipt.identity,
+                disposition: remove && !rejection ? "indeterminate" : "not-attempted", namespace: "unknown",
+                resources: "close-failed", persistence: "not-proven", errors: [
+                    ...(rejection ? [{ phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause }] : []),
+                    { phase: "binding", code: "helper-failed", message: "native settlement did not return a result", cause },
+                ] });
+        }
+        return this.#result;
+    }
+    remove() { return this.#settle(true); }
+    dispose() { return this.#settle(false); }
+    [Symbol.dispose]() {
+        const result = this.dispose();
+        if (result.resources !== "closed") {
+            throw new FsSafeError("helper-failed", "retained-file resource settlement is uncertain", { details: { result } });
+        }
+    }
+}
+/** Retain one existing regular file on supported local Windows NTFS. No fallback. */
+export function retainFileInDirectory(options) {
+    // Snapshot once before any native resource admission or caller authority runs.
+    const directory = options.directory;
+    const basename = options.basename;
+    const sourceParent = options.parent;
+    const parent = Object.freeze({ dev: exact(sourceParent.dev, "parent.dev"), ino: exact(sourceParent.ino, "parent.ino") });
+    const source = options.expected;
+    const expected = Object.freeze({ dev: exact(source.dev, "expected.dev"), ino: exact(source.ino, "expected.ino"),
+        size: exact(source.size, "expected.size", true), mtimeNs: exact(source.mtimeNs, "expected.mtimeNs", true),
+        ctimeNs: exact(source.ctimeNs, "expected.ctimeNs", true), sha256: source.sha256 });
+    const assertion = options.assertBeforeMutation;
+    const maxBytes = options.maxBytes ?? 16 * 1024 * 1024;
+    if (typeof directory !== "string" || typeof basename !== "string" || typeof assertion !== "function"
+        || typeof expected.sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(expected.sha256)
+        || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > 64 * 1024 * 1024 || expected.size > BigInt(maxBytes)) {
+        throw new TypeError("invalid retained-file directory, authority or bounded expected-byte contract");
+    }
+    if (process.platform !== "win32")
+        return unsupported();
+    let binding;
+    try {
+        binding = getNativeBinding();
+    }
+    catch (cause) {
+        return unsupported(cause);
+    }
+    if (!binding?.retainWindowsFile)
+        return unsupported();
+    let native;
+    try {
+        native = binding.retainWindowsFile(directory, basename, parent.dev, parent.ino, expected.dev, expected.ino, expected.size, expected.mtimeNs, expected.ctimeNs, expected.sha256, maxBytes);
+    }
+    catch (cause) {
+        // Factory errors have no returned owner; never infer absence or deletion.
+        return freeze({ ...unsupported(cause), status: "indeterminate", resources: "close-failed" });
+    }
+    const admission = native.admission;
+    if (admission.status !== "retained")
+        return freeze(admission);
+    const receipt = Object.freeze({ directory, parent, basename, expected, identity: admission.identity });
+    return Object.freeze({ status: "retained", file: new Owner(native, receipt, assertion) });
+}

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

@@ -107,7 +107,7 @@ export function rootRelativeReadPath(root, filePath) {
                 resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
             });
             if (admitted)
-                return admitted.relativePath;
+                return `.${path.sep}${admitted.relativePath}`;
             continue;
         }
         const prefix = ensureTrailingSep(base);
@@ -116,7 +116,8 @@ export function rootRelativeReadPath(root, filePath) {
             let start = prefix.length;
             while (raw[start] === path.sep)
                 start += 1;
-            return raw.slice(start);
+            // An admitted absolute tail stays literal, including a leading home marker.
+            return `.${path.sep}${raw.slice(start)}`;
         }
     }
     return raw;

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

@@ -0,0 +1,9 @@
+import { type RootContext } from "./root-context.js";
+import { type RootDirectoryObservationGuard } from "./root-directory-list.js";
+import { type ExactStatIdentity } from "./stat-observation.js";
+import type { DirEntry } from "./types.js";
+/** One literal entry lookup under an operation-local admitted parent; never follow the leaf. */
+export declare function lookupRootDirectoryEntry(root: RootContext, guard: RootDirectoryObservationGuard, name: string): Promise<{
+    entry: DirEntry;
+    identity: ExactStatIdentity;
+} | undefined>;

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

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertValidRootRelativePath } from "./root-context.js";
+import { assertRootDirectoryObservationGuard, pathStatFromStats } from "./root-directory-list.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
+/** One literal entry lookup under an operation-local admitted parent; never follow the leaf. */
+export async function lookupRootDirectoryEntry(root, guard, name) {
+    if (!name || name === "." || name === ".." || path.basename(name) !== name || path.isAbsolute(name)) {
+        throw new FsSafeError("invalid-path", "directory lookup requires one literal name");
+    }
+    assertValidRootRelativePath(name);
+    await assertRootDirectoryObservationGuard(root, guard);
+    try {
+        const pathname = path.join(guard.realPath, name);
+        const observed = inspectStatObservationSync(bigint => bigint
+            ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname));
+        await assertRootDirectoryObservationGuard(root, guard);
+        return { entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+    }
+    catch (error) {
+        await assertRootDirectoryObservationGuard(root, guard);
+        if (isNotFoundPathError(error))
+            return undefined;
+        throw error;
+    }
+}

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

@@ -2,6 +2,7 @@ import type { BigIntStats, Stats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type RootContext } from "./root-context.js";
 import type { RootPathDirectoryObservationGuard, RootPathObservationReceipt, RootPathParentObservationReceipt } from "./root-path.js";
+import { type ExactStatIdentity } from "./stat-observation.js";
 import type { DirEntry, PathStat } from "./types.js";
 export declare function pathStatFromStats(stat: Stats | BigIntStats): PathStat;
 export type RootDirectoryObservationGuard = AsyncDirectoryGuard<BigIntStats>;
@@ -21,6 +22,7 @@ export type RootDirectoryListing = {
     next(): Promise<{
         kind: "entry";
         entry: DirEntry;
+        identity?: ExactStatIdentity;
     } | {
         kind: "limit";
         name: string;
@@ -33,6 +35,12 @@ export type RootDirectoryListingOptions = {
     snapshot: boolean;
     maxNames?: number;
     metadataBatchSize?: number;
+    /** Internal exact metadata lane, supported by streaming filesystem order. */
+    exactIdentity?: boolean;
+    /** Advisory scans may omit vanished leaves after revalidating their parent. */
+    skipVanished?: boolean;
+    /** Internal owner receives cleanup failures, including acquisition rollback. */
+    onCleanupFailure?: (error: unknown) => void;
     admitEntry(): boolean;
 };
-export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;

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

@@ -1,3 +1,4 @@
+import { isUtf8 } from "node:buffer";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -11,8 +12,25 @@ import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { realpathSync } from "./realpath.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
+function directoryEntryName(bytes) {
+    if (!isUtf8(bytes)) {
+        throw new FsSafeError("invalid-path", "directory entry name is not valid UTF-8");
+    }
+    return bytes.toString("utf8");
+}
+async function readDirectoryEntryName(handle) {
+    const entry = await handle.read();
+    // Bun returns the raw Buffer directly; Node returns a Dirent whose name is a Buffer.
+    // Node's Dir types still declare only string names.
+    return entry === null ? undefined
+        : directoryEntryName(Buffer.isBuffer(entry) ? entry : entry.name);
+}
+function openDirectoryNames(directory) {
+    return fs.opendir(directory, { bufferSize: 1, encoding: "buffer" });
+}
 export function pathStatFromStats(stat) {
     const mtimeMs = typeof stat.mtimeMs === "bigint"
         ? "mtimeNs" in stat && typeof stat.mtimeNs === "bigint"
@@ -173,14 +191,7 @@ function normalizeInitialDirectoryError(error) {
 export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
     let guard;
     if (receipt) {
-        if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
-            receipt.directoryGuard.dir !== directory ||
-            receipt.target !== receipt.directoryGuard ||
-            (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
-                !receipt.directoryGuard.stat.isDirectory())) {
-            throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
-        }
-        guard = receipt.directoryGuard;
+        guard = directoryGuardFromReceipt(directory, receipt);
     }
     else {
         try {
@@ -192,13 +203,23 @@ export async function listDirectoryPath(root, directory, withFileTypes, receipt)
     }
     return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);
 }
+function directoryGuardFromReceipt(directory, receipt) {
+    if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
+        receipt.directoryGuard.dir !== directory ||
+        receipt.target !== receipt.directoryGuard ||
+        (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
+            !receipt.directoryGuard.stat.isDirectory())) {
+        throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
+    }
+    return receipt.directoryGuard;
+}
 async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
     let entries;
     try {
         const beforeObservation = getFsSafeTestHooks()?.beforeRootListObservation;
         if (beforeObservation)
             await beforeObservation(guard.realPath, withFileTypes);
-        const names = (await fs.readdir(guard.realPath)).sort();
+        const names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName).sort();
         entries = withFileTypes
             ? names.map(name => ({
                 name,
@@ -221,19 +242,30 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
         await assertRootDirectoryObservationGuard(root, guard);
     return entries;
 }
-export async function openRootDirectoryListing(root, directory, options) {
-    const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
-        throw normalizeDirectoryError(error);
-    });
-    // Retain exact admission identities; metadata rechecks can use numeric Stats
-    // only when every identity component is losslessly representable.
-    const guard = extendDirectoryObservationGuard({
-        stat: admitted.stat,
-        identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
-    }, admitted.dir, admitted.realPath);
+export async function openRootDirectoryListing(root, directory, options, receipt) {
+    if (options.exactIdentity && options.order !== "filesystem")
+        throw new TypeError("exact entry identities require filesystem order");
+    let guard;
+    if (receipt) {
+        guard = directoryGuardFromReceipt(directory, receipt);
+    }
+    else {
+        const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
+            throw normalizeDirectoryError(error);
+        });
+        // Retain exact admission identities; metadata rechecks can use numeric Stats
+        // only when every identity component is losslessly representable.
+        guard = extendDirectoryObservationGuard({
+            stat: admitted.stat,
+            identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
+        }, admitted.dir, admitted.realPath);
+    }
     const assertCurrent = async () => {
         options.signal?.throwIfAborted();
-        await assertRootDirectoryObservationGuard(root, guard);
+        if (receipt)
+            assertRootPathObservationReceiptCurrent(root, receipt);
+        else
+            await assertRootDirectoryObservationGuard(root, guard);
         options.signal?.throwIfAborted();
     };
     let handle;
@@ -248,23 +280,29 @@ export async function openRootDirectoryListing(root, directory, options) {
     const close = async () => {
         const owned = handle;
         handle = undefined;
-        await owned?.close();
+        try {
+            await owned?.close();
+        }
+        catch (error) {
+            options.onCleanupFailure?.(error);
+            throw error;
+        }
     };
     try {
         await assertCurrent();
         if (options.order === "filesystem") {
             // A one-entry buffer keeps the truncation lookahead independent of width.
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
         }
         else if (options.snapshot) {
-            snapshot = await listGuardedDirectoryPath(root, guard, true);
+            snapshot = await listGuardedDirectoryPath(root, guard, true, receipt);
         }
         else if (options.maxNames !== undefined) {
             names = [];
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
             while (true) {
                 await assertCurrent();
-                const name = (await handle.read())?.name;
+                const name = await readDirectoryEntryName(handle);
                 await assertCurrent();
                 if (name === undefined)
                     break;
@@ -276,7 +314,7 @@ export async function openRootDirectoryListing(root, directory, options) {
             await close();
         }
         else {
-            names = await fs.readdir(guard.realPath);
+            names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName);
         }
         await assertCurrent();
         names?.sort();
@@ -361,17 +399,30 @@ export async function openRootDirectoryListing(root, directory, options) {
                         return { kind: "limit", name: pendingLimit };
                     return;
                 }
-                await assertCurrent();
-                const name = (await handle.read())?.name;
-                await assertCurrent();
-                if (name === undefined)
-                    return;
-                if (!options.admitEntry())
-                    return { kind: "limit", name };
-                // The stream's post-read fence is also the pre-stat fence in this owned operation.
-                const stat = fsSync.lstatSync(path.join(guard.realPath, name));
-                await assertCurrent();
-                return { kind: "entry", entry: { name, ...pathStatFromStats(stat) } };
+                for (;;) {
+                    await assertCurrent();
+                    const name = await readDirectoryEntryName(handle);
+                    await assertCurrent();
+                    if (name === undefined)
+                        return;
+                    if (!options.admitEntry())
+                        return { kind: "limit", name };
+                    // The stream's post-read fence is also the pre-stat fence in this owned operation.
+                    const pathname = path.join(guard.realPath, name);
+                    let observed;
+                    try {
+                        observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
+                            ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : { stat: fsSync.lstatSync(pathname) };
+                    }
+                    catch (error) {
+                        await assertCurrent();
+                        if (options.skipVanished && isNotFoundPathError(error))
+                            continue;
+                        throw error;
+                    }
+                    await assertCurrent();
+                    return { kind: "entry", entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+                }
             }
             catch (error) {
                 throw normalizeDirectoryError(error);

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

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import type { PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
+import { type PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
 export type RootFileAdmissionFs = Pick<typeof fs, "lstatSync" | "realpathSync">;
 type ExactIdentity = Readonly<{
     dev: bigint;

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

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
+import { isExpectedPathError } from "./pinned-open.js";
 import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { hardlinkedPathNotAllowedError } from "./root-errors.js";
@@ -8,12 +9,6 @@ import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-pa
 function rootIdentityMismatch(cause) {
     return new FsSafeError("path-mismatch", "canonical root directory identity changed or could not be verified", cause === undefined ? {} : { cause });
 }
-function isExpectedPathError(error) {
-    const code = typeof error === "object" && error !== null && "code" in error
-        ? String(error.code)
-        : "";
-    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
-}
 function inspectCanonicalRoot(ioFs, rootPath, expected) {
     try {
         assertNoWindowsPathAlias(rootPath);

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

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveRootPathSyncWithCanonicalRootObservation, resolveRootPathWithCanonicalRootObservation, } from "./root-path.js";
 import { readSymlinkResolution } from "./root-symlink-policy.js";
-import { openPinnedFileSync, } from "./pinned-open.js";
+import { isExpectedPathError, openPinnedFileSync, } from "./pinned-open.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { FsSafeError } from "./errors.js";
 import { createRootFileFinalAdmission, observeCanonicalRoot, } from "./root-file-final-admission.js";
@@ -198,10 +198,7 @@ function snapshotAsyncResolution(params, absolutePath) {
 function toRootObservationError(error) {
     if (error instanceof FsSafeError)
         return toBoundaryValidationError(error);
-    const code = typeof error === "object" && error !== null && "code" in error
-        ? String(error.code)
-        : "";
-    if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") {
+    if (isExpectedPathError(error)) {
         return { ok: false, reason: "path", error };
     }
     return { ok: false, reason: "io", error };

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

@@ -0,0 +1,4 @@
+import type { RootContext } from "./root-context.js";
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export declare function registerRootHandleContext(handle: object, context: RootContext): void;
+export declare function rootHandleContext(handle: object): RootContext;

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

@@ -0,0 +1,12 @@
+import { FsSafeError } from "./errors.js";
+const contexts = new WeakMap();
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export function registerRootHandleContext(handle, context) {
+    contexts.set(handle, context);
+}
+export function rootHandleContext(handle) {
+    const context = contexts.get(handle);
+    if (!context)
+        throw new FsSafeError("invalid-path", "watch requires a genuine fs-safe Root");
+    return context;
+}

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

@@ -5,7 +5,7 @@ import { type ReadResult } from "./read-opened-file.js";
 import { type RootEntriesOptions } from "./root-entries.js";
 import { type RootContext } from "./root-context.js";
 import type { DirEntry, PathStat } from "./types.js";
-import { type RootWalkEntry, type RootWalkOptions } from "./root-walk.js";
+import { type RootWalkEntry, type RootWalkOptions, type RootWalkSymlinkPolicy } from "./root-walk.js";
 import { type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions } from "./root-options.js";
 export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
@@ -54,7 +54,7 @@ export interface Root {
     }): Promise<DirEntry[]>;
     entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
-    walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare class RootHandle implements Root {
     private readonly context;
@@ -97,7 +97,7 @@ export declare class RootHandle implements Root {
     }): Promise<DirEntry[]>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
     entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
-    walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 export declare function rootFromDirectoryGuard(guard: {

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

@@ -51,6 +51,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { randomUUID } from "node:crypto";
+import { registerRootHandleContext } from "./root-handle-context.js";
 import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -85,7 +86,7 @@ import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-li
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
-import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -199,6 +200,7 @@ export class RootHandle {
         this.rootWithSep = context.rootWithSep;
         this.defaults = defaults;
         registerFileLockSyncRootAdapter(this, context, defaults);
+        registerRootHandleContext(this, context);
     }
     mutationOptions(options) {
         return {
@@ -409,9 +411,13 @@ export class RootHandle {
         assertValidRootRelativePath(relativePath);
         return walkRoot({
             rootReal: this.context.rootReal,
+            observeRoot: () => createRootObservationGuard(this.context),
             stat: relative => this.stat(relative),
-            list: async (relative, listingOptions) => {
+            list: async (relative, listingOptions, receipt) => {
                 validatePinnedRelativePath(relative);
+                if (receipt) {
+                    return await openRootDirectoryListing(this.context, receipt.targetPath, listingOptions, receipt);
+                }
                 const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
                 return await openRootDirectoryListing(this.context, resolved.resolved, listingOptions);
             },
@@ -798,7 +804,6 @@ async function mkdirPathInRoot(root, params) {
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
-            rootWithSep: ensureTrailingSep(resolved.rootReal),
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved.resolved,
             originalPath: params.relativePath,
@@ -1045,10 +1050,8 @@ async function resolvePinnedRootPathInRoot(root, params) {
             throw err;
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
-    const rootWithSep = ensureTrailingSep(resolved.rootCanonicalPath);
     return {
         rootReal: resolved.rootCanonicalPath,
-        rootWithSep,
         canonicalPath: resolved.canonicalPath,
     };
 }