@openclaw/openshell-sandbox 2026.10.2 → 2026.10.5-beta.2

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

@@ -0,0 +1,187 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { hasErrorCode } from "./file-cleanup.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { nativeOpenFlags } from "./native-operations.js";
+import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+function mismatch(check) {
+    return new FsSafeError("path-mismatch", `created sidecar lock ${check} changed; replacement preserved`);
+}
+function assertOwnerRecord(fd, expected) {
+    if (fs.fstatSync(fd, { bigint: true }).size !== BigInt(expected.length))
+        throw mismatch("owner record");
+    const bytes = Buffer.alloc(expected.length);
+    let offset = 0;
+    while (offset < bytes.length) {
+        const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+        if (read === 0)
+            throw mismatch("owner record");
+        offset += read;
+    }
+    if (!bytes.equals(expected))
+        throw mismatch("owner record");
+}
+/** Borrowed creation authority: never reopens a path or closes the writer's fds. */
+export function cleanupCreatedSidecar(lockPath, raw, fd, parent, identity) {
+    const name = path.basename(lockPath);
+    const windows = process.platform === "win32";
+    try {
+        if (windows) {
+            if (!parent.binding.rootRemovalStat || !parent.binding.rootRemovalUnlink) {
+                throw new FsSafeError("helper-unavailable", "creator cleanup is unavailable");
+            }
+            const entry = parent.binding.rootRemovalStat(parent.fd, name);
+            if (entry.directory || entry.symlink || !sameFileIdentityForCleanup(identity, entry))
+                throw mismatch("identity");
+        }
+        else if (!parent.binding.stagedFileMatches || !parent.binding.removeStagedFile) {
+            throw new FsSafeError("helper-unavailable", "creator cleanup is unavailable");
+        }
+        else if (!parent.binding.stagedFileMatches(parent.fd, name, fd)) {
+            throw mismatch("identity");
+        }
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return;
+        throw error;
+    }
+    const stat = fs.fstatSync(fd, { bigint: true });
+    if (!stat.isFile() || stat.nlink !== 1n || !sameFileIdentityForCleanup(identity, stat))
+        throw mismatch("identity");
+    assertOwnerRecord(fd, Buffer.from(raw));
+    if (windows) {
+        try {
+            parent.binding.rootRemovalUnlink(parent.fd, name, identity.dev, identity.ino, false);
+        }
+        catch (error) {
+            if (!hasErrorCode(error, "ENOENT"))
+                throw error;
+        }
+    }
+    else {
+        if (parent.binding.removeStagedFile(parent.fd, name, fd) === "preserved")
+            throw mismatch("identity");
+    }
+}
+/** Called only by the exclusive creator while its verified descriptor is alive. */
+export function retainCreatedSidecar(lockPath, raw, createdFd, guard, nativeParent) {
+    const binding = nativeParent?.binding;
+    if (!binding)
+        return undefined;
+    const created = fs.fstatSync(createdFd, { bigint: true });
+    if (!created.isFile() || created.nlink !== 1n)
+        throw mismatch("identity");
+    const identity = Object.freeze({ dev: created.dev, ino: created.ino });
+    const name = path.basename(lockPath);
+    if (process.platform === "win32") {
+        if (!binding.retainWindowsSidecar)
+            return undefined;
+        const native = binding.retainWindowsSidecar(nativeParent.fd, guard.realPath, name, BigInt(guard.stat.dev), BigInt(guard.stat.ino), created.dev, created.ino, BigInt(Buffer.byteLength(raw)), sha256Hex(raw), 1024 * 1024);
+        const admitted = native.admission;
+        if (admitted.status === "unsupported" && admitted.resources === "closed")
+            return undefined;
+        if (admitted.status !== "retained") {
+            throw new FsSafeError("helper-failed", "could not retain created sidecar lock", { details: { result: admitted } });
+        }
+        return { identity, settle(remove, reportMismatch = true) {
+                const result = native.settle(remove);
+                if (result.status === "preserved-mismatch") {
+                    if (reportMismatch || result.resources !== "closed") {
+                        throw mismatch(result.errors.some(error => /digest|size changed/u.test(error.message)) ? "owner record" : "identity");
+                    }
+                    return;
+                }
+                if (result.errors.length || result.resources !== "closed" ||
+                    (remove && result.disposition !== "accepted" && result.namespace !== "absent")) {
+                    throw new FsSafeError("helper-failed", "retained sidecar lock settlement failed", { details: { result } });
+                }
+            } };
+    }
+    if (!binding.stagedFileMatches || !binding.removeStagedFile)
+        return undefined;
+    const closeFile = captureNativeFdClose(binding);
+    const parentFd = binding.openBeneath(nativeParent.fd, "", nativeOpenFlags(fs.constants.O_RDONLY | fs.constants.O_DIRECTORY)).fd;
+    let fd;
+    try {
+        const parentStat = fs.fstatSync(parentFd, { bigint: true });
+        if (!parentStat.isDirectory() || !sameFileIdentityForCleanup(guard.stat, parentStat))
+            throw mismatch("identity");
+        fd = binding.openBeneath(parentFd, name, nativeOpenFlags(fs.constants.O_RDONLY | fs.constants.O_NONBLOCK)).fd;
+        const ownedFd = fd;
+        const assertIdentity = () => {
+            try {
+                if (!binding.stagedFileMatches(parentFd, name, ownedFd))
+                    throw mismatch("identity");
+            }
+            catch (error) {
+                if (hasErrorCode(error, "ENOENT"))
+                    return false;
+                throw error;
+            }
+            const current = fs.fstatSync(ownedFd, { bigint: true });
+            if (!current.isFile() || current.nlink !== 1n || !sameFileIdentityForCleanup(created, current))
+                throw mismatch("identity");
+            return true;
+        };
+        const expected = Buffer.from(raw);
+        const assertOwner = () => assertOwnerRecord(ownedFd, expected);
+        if (!assertIdentity())
+            throw mismatch("identity");
+        assertOwner();
+        let settled = false;
+        return { identity, settle(remove, reportMismatch = true) {
+                if (settled)
+                    return;
+                settled = true;
+                const errors = [];
+                try {
+                    if (remove && assertIdentity()) {
+                        assertOwner();
+                        if (assertIdentity() && binding.removeStagedFile(parentFd, name, ownedFd) === "preserved")
+                            throw mismatch("identity");
+                    }
+                }
+                catch (error) {
+                    if (reportMismatch || !(error instanceof FsSafeError && error.code === "path-mismatch"))
+                        errors.push(error);
+                }
+                try {
+                    closeFile(ownedFd);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+                try {
+                    closeFile(parentFd);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+                if (errors.length === 1)
+                    throw errors[0];
+                if (errors.length)
+                    throw new AggregateError(errors, "sidecar lock cleanup and close failed");
+            } };
+    }
+    catch (error) {
+        const errors = [error];
+        try {
+            if (fd !== undefined)
+                closeFile(fd);
+        }
+        catch (closeError) {
+            errors.push(closeError);
+        }
+        try {
+            closeFile(parentFd);
+        }
+        catch (closeError) {
+            errors.push(closeError);
+        }
+        if (errors.length > 1)
+            throw new AggregateError(errors, "sidecar retention and close failed");
+        throw error;
+    }
+}

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

@@ -108,7 +108,10 @@ function releaseAllLocksSync(state, options) {
         void held.handle.close().catch(() => undefined);
         try {
             const retained = options?.preserveRetained === true && held.retainOnExit;
-            if (!retained && !held.lockRoot && snapshotMatchesSync(held.lockPath, held.snapshot)) {
+            if (held.retainedSidecar) {
+                held.retainedSidecar.settle(!retained);
+            }
+            else if (!retained && !held.lockRoot && snapshotMatchesSync(held.lockPath, held.snapshot)) {
                 fsSync.rmSync(held.lockPath, { force: true });
             }
         }
@@ -186,6 +189,17 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
     }
     held.releasePromise = (async () => {
         await held.handle.close().catch(() => undefined);
+        if (held.retainedSidecar) {
+            try {
+                held.retainedSidecar.settle(true);
+            }
+            finally {
+                if (state.held.get(normalizedTargetPath) === held)
+                    state.held.delete(normalizedTargetPath);
+                stopSidecarLockMonitoring(held);
+            }
+            return;
+        }
         await removeSidecarLockIfUnchanged(held.lockPath, held.snapshot, {
             lockRoot: held.lockRoot,
             parsePayload: held.parsePayload,

package/node_modules/@openclaw/fs-safe/dist/temp-directory-diagnostics.d.ts

@@ -0,0 +1,10 @@
+export declare function tempDirectoryMode(mode: number | bigint): string;
+export declare function privateTempDirectoryFix(uid: number | undefined): string;
+type TempDirectoryStat = {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    uid?: number | bigint;
+    mode?: number | bigint;
+};
+export declare function secureTempDirectoryFailure(stat: TempDirectoryStat, uid: number | undefined, windows: boolean): string;
+export {};

package/node_modules/@openclaw/fs-safe/dist/temp-directory-diagnostics.js

@@ -0,0 +1,29 @@
+export function tempDirectoryMode(mode) {
+    return (typeof mode === "bigint" ? mode & 4095n : mode & 0o7777).toString(8).padStart(4, "0");
+}
+export function privateTempDirectoryFix(uid) {
+    return `use a real private directory${uid === undefined ? "" : ` owned by uid ${uid}`} with mode 0700 under trusted ancestors (or use resolveSecureTempRoot()); do not chmod a shared temp directory to 0700`;
+}
+// Called only after failed admission; diagnostics never authorize repair.
+export function secureTempDirectoryFailure(stat, uid, windows) {
+    if (stat.isSymbolicLink())
+        return "is a symbolic link; choose a real directory, not a symlink";
+    if (!stat.isDirectory())
+        return "is not a directory; choose a real directory";
+    if (!windows && uid !== undefined) {
+        if (stat.uid !== undefined && stat.uid !== uid && stat.uid !== BigInt(uid)) {
+            return `has owner uid ${stat.uid}, expected uid ${uid}; ${privateTempDirectoryFix(uid)}`;
+        }
+        const mode = stat.mode;
+        if (mode !== undefined) {
+            if ((typeof mode === "number" && (!Number.isSafeInteger(mode) || mode < 0)) ||
+                (typeof mode === "bigint" && mode < 0n)) {
+                return `has invalid mode bits; ${privateTempDirectoryFix(uid)}`;
+            }
+            if (typeof mode === "bigint" ? (mode & 18n) !== 0n : (mode & 0o022) !== 0) {
+                return `has group/world-writable mode ${tempDirectoryMode(mode)} (a sticky bit does not make a private root safe); ${privateTempDirectoryFix(uid)}`;
+            }
+        }
+    }
+    return `directory identity, permissions, or write/search access could not be verified; ${privateTempDirectoryFix(uid)}`;
+}

package/node_modules/@openclaw/fs-safe/dist/temp-target.js

@@ -143,7 +143,7 @@ export async function createOwnedTempFile(params) {
             capability.assertCurrent();
             const initial = inspectDirectoryIdentitySync(dir);
             identity = Object.freeze({ dev: initial.dev, ino: initial.ino });
-            const needsModeInitialization = validateInitialTempWorkspaceChild(initial, admission.ownerUid, 0o700);
+            const needsModeInitialization = validateInitialTempWorkspaceChild(initial, admission.ownerUid, 0o700, dir);
             retainedChild = TempWorkspaceRetainedChild.retain(dir, identity);
             if (needsModeInitialization) {
                 await retainedChild.initializeMode(0o700, admission.ownerUid, admission.assertCurrent);

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-admission.js

@@ -46,7 +46,7 @@ function snapshotFromExactObservation(dir, uid, realPath, stat, privateDirectory
     if (stat.symbolicLink || !stat.directory) {
         throw new FsSafeError("not-file", "temp workspace root component must be a real directory");
     }
-    assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory);
+    assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory, dir);
     const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
     // Retain copied immutable scalars, never a mutable Stats object supplied by
     // an observation hook. Every later permission check uses a fresh snapshot.
@@ -106,7 +106,7 @@ function inspectSnapshotIdentity(entry) {
 }
 function assertSnapshot(entry, uid) {
     const stat = inspectSnapshotIdentity(entry);
-    assertTrustedTempWorkspaceDirectory(stat, uid, entry.privateDirectory);
+    assertTrustedTempWorkspaceDirectory(stat, uid, entry.privateDirectory, entry.dir);
     assertCanonicalRoot(entry);
 }
 function snapshotMissingRootComponent(parent, dir, ownerUid, privateDirectory) {
@@ -115,7 +115,7 @@ function snapshotMissingRootComponent(parent, dir, ownerUid, privateDirectory) {
         return snapshot(dir, ownerUid, undefined, privateDirectory);
     }
     const current = inspectSnapshotIdentity(parent);
-    assertTrustedTempWorkspaceDirectory(current, ownerUid, parent.privateDirectory);
+    assertTrustedTempWorkspaceDirectory(current, ownerUid, parent.privateDirectory, parent.dir);
     let realPath;
     try {
         realPath = canonicalTempWorkspacePath(dir);
@@ -136,7 +136,7 @@ function snapshotMissingRootComponent(parent, dir, ownerUid, privateDirectory) {
 function assertChain(chain, uid) {
     for (const entry of chain) {
         const current = inspectSnapshotIdentity(entry);
-        assertTrustedTempWorkspaceDirectory(current, uid, entry.privateDirectory);
+        assertTrustedTempWorkspaceDirectory(current, uid, entry.privateDirectory, entry.dir);
     }
     const last = chain[chain.length - 1];
     assertCanonicalRoot(last);
@@ -159,7 +159,7 @@ function associateTempWorkspaceRoot(entry, ownerUid, descriptorFd) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new FsSafeError("not-file", "temp workspace cleanup parent must be a real directory");
     }
-    assertTrustedTempWorkspaceDirectory(stat, ownerUid, entry.privateDirectory);
+    assertTrustedTempWorkspaceDirectory(stat, ownerUid, entry.privateDirectory, entry.dir);
 }
 function discoverMissingTempWorkspaceAncestor(ancestor, missing, missingError) {
     // The caller already classified the first ENOENT. Keep this handoff out of
@@ -290,7 +290,7 @@ function canonicalRootAdmission(discovery, ownerUid) {
                     return snapshot(dir, ownerUid, dir, index === ancestry.length - 1 && discovery.privateDirectory).entry;
                 }
                 const current = inspectSnapshotIdentity(discovery);
-                assertTrustedTempWorkspaceDirectory(current, ownerUid, discovery.privateDirectory);
+                assertTrustedTempWorkspaceDirectory(current, ownerUid, discovery.privateDirectory, discovery.dir);
                 return discovery;
             });
             const current = candidate[candidate.length - 1];

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-child-admission.d.ts

@@ -14,10 +14,10 @@ export declare function projectTempWorkspaceNumericIdentity(identity: TempWorksp
 export declare function inspectTempWorkspaceDescriptorIdentitySync(fd: number, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
 export declare function inspectTempWorkspaceDirectoryIdentitySync(dir: string, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
 export declare function validateTempWorkspaceDirMode(mode: number): void;
-export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "gid" | "mode"> | Pick<Stats, "uid" | "gid" | "mode">, uid: number | undefined, privateDirectory?: boolean): void;
-export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined): void;
-export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number): boolean;
+export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "gid" | "mode"> | Pick<Stats, "uid" | "gid" | "mode">, uid: number | undefined, privateDirectory: boolean, dir: string): void;
+export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined, dir: string): void;
+export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number, dir: string): boolean;
 export declare function childHasRequestedMode(stat: BigIntStats | Stats, mode: number): boolean;
 export declare function admitTempWorkspaceChild(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): Promise<void> | undefined;
 export declare function admitTempWorkspaceChildSync(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): void;
-export declare function validateAdmittedTempWorkspaceChild(current: TempWorkspaceIdentityStat, ownerUid: number | undefined, mode: number): void;
+export declare function validateAdmittedTempWorkspaceChild(current: TempWorkspaceIdentityStat, ownerUid: number | undefined, mode: number, dir: string): void;

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-child-admission.js

@@ -4,6 +4,7 @@ import { pinNodeDirectoryForMode, pinNodeDirectoryForModeSync } from "./director
 import { FsSafeError } from "./errors.js";
 import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { classifyTempWorkspaceOwner, warnUnmappedTempWorkspaceAncestor } from "./temp-workspace-ownership.js";
+import { privateTempDirectoryFix, tempDirectoryMode } from "./temp-directory-diagnostics.js";
 export const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY = process.platform === "linux" || process.platform === "darwin";
 export function projectTempWorkspaceNumericIdentity(identity) {
     const dev = Number(identity.dev);
@@ -43,12 +44,12 @@ export function validateTempWorkspaceDirMode(mode) {
         throw new FsSafeError("insecure-permissions", "temp workspace must not be group/world writable");
     }
 }
-export function assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory = false) {
+export function assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory, dir) {
     if (uid === undefined)
         return;
     const ownership = classifyTempWorkspaceOwner(stat, uid);
     if (ownership === "foreign" || (privateDirectory && ownership !== "user")) {
-        throw new FsSafeError("not-owned", "temp workspace directory has an untrusted owner; use a private temp root owned by the effective user under a trusted directory hierarchy");
+        throw new FsSafeError("not-owned", `temp workspace directory ${JSON.stringify(dir)} has an untrusted owner uid ${stat.uid}; expected uid ${uid}${privateDirectory || uid === 0 ? "" : " or root uid 0"}; ${privateTempDirectoryFix(uid)}`);
     }
     // Unmapped host owners are unverifiable; trust the host directory hierarchy.
     // Admit sticky ancestors so PrivateUsers keeps host /tmp and PrivateTmp usable.
@@ -60,18 +61,18 @@ export function assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory
         ? (stat.mode & 512n) !== 0n
         : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o1000) !== 0;
     if (typeof stat.mode !== "bigint" && (!Number.isSafeInteger(stat.mode) || stat.mode < 0)) {
-        throw new FsSafeError("insecure-permissions", "temp workspace directory permissions are invalid");
+        throw new FsSafeError("insecure-permissions", `temp workspace directory ${JSON.stringify(dir)} permissions are invalid; ${privateTempDirectoryFix(uid)}`);
     }
     if (writable && (privateDirectory || !sticky)) {
         throw new FsSafeError("insecure-permissions", privateDirectory
-            ? "temp workspace root and child must not be group/world writable; use a private temp directory"
-            : "temp workspace ancestor is group/world writable without sticky protection");
+            ? `temp workspace directory ${JSON.stringify(dir)} has group/world-writable mode ${tempDirectoryMode(stat.mode)}; root and child must not be group/world writable, even with the sticky bit; ${privateTempDirectoryFix(uid)}`
+            : `temp workspace ancestor ${JSON.stringify(dir)} has group/world-writable mode ${tempDirectoryMode(stat.mode)} without sticky protection (sticky bit missing); have its administrator restore safe permissions (1777 for a shared system temp directory), or move the private root under trusted ancestors`);
     }
     if (ownership === "unmapped")
         warnUnmappedTempWorkspaceAncestor();
 }
 const WINDOWS = process.platform === "win32";
-export function assertTempWorkspaceChildState(stat, ownerUid) {
+export function assertTempWorkspaceChildState(stat, ownerUid, dir) {
     const exactIdentity = typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&
         (!WINDOWS || (stat.dev !== 0n && stat.ino !== 0n));
     const safeNumericIdentity = TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY &&
@@ -81,12 +82,12 @@ export function assertTempWorkspaceChildState(stat, ownerUid) {
         throw new FsSafeError("path-mismatch", "temp workspace child identity could not be verified");
     }
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new FsSafeError("not-file", "temp workspace child must be a real directory");
+        throw new FsSafeError("not-file", `temp workspace child ${JSON.stringify(dir)} ${stat.isSymbolicLink() ? "is a symbolic link" : "is not a directory"}; ${privateTempDirectoryFix(ownerUid)}`);
     }
-    assertTrustedTempWorkspaceDirectory(stat, ownerUid, true);
+    assertTrustedTempWorkspaceDirectory(stat, ownerUid, true, dir);
 }
-export function validateInitialTempWorkspaceChild(stat, ownerUid, mode) {
-    assertTempWorkspaceChildState(stat, ownerUid);
+export function validateInitialTempWorkspaceChild(stat, ownerUid, mode, dir) {
+    assertTempWorkspaceChildState(stat, ownerUid, dir);
     return !childHasRequestedMode(stat, mode);
 }
 export function childHasRequestedMode(stat, mode) {
@@ -105,7 +106,7 @@ async function initializeTempWorkspaceChildMode(dir, expected, parent, mode) {
     try {
         await owner.apply(mode, { check: parent.assertCurrent });
         const current = inspectDirectoryIdentitySync(dir, expected);
-        validateAdmittedTempWorkspaceChild(current, parent.ownerUid, mode);
+        validateAdmittedTempWorkspaceChild(current, parent.ownerUid, mode, dir);
         parent.assertCurrent();
     }
     finally {
@@ -113,12 +114,12 @@ async function initializeTempWorkspaceChildMode(dir, expected, parent, mode) {
     }
 }
 export function admitTempWorkspaceChild(dir, expected, parent, mode) {
-    if (!validateInitialTempWorkspaceChild(expected, parent.ownerUid, mode))
+    if (!validateInitialTempWorkspaceChild(expected, parent.ownerUid, mode, dir))
         return undefined;
     return initializeTempWorkspaceChildMode(dir, expected, parent, mode);
 }
 export function admitTempWorkspaceChildSync(dir, expected, parent, mode) {
-    if (!validateInitialTempWorkspaceChild(expected, parent.ownerUid, mode))
+    if (!validateInitialTempWorkspaceChild(expected, parent.ownerUid, mode, dir))
         return;
     parent.assertCurrent();
     const owner = pinNodeDirectoryForModeSync(dir, {
@@ -128,15 +129,15 @@ export function admitTempWorkspaceChildSync(dir, expected, parent, mode) {
     try {
         owner.apply(mode, parent.assertCurrent);
         const current = inspectDirectoryIdentitySync(dir, expected);
-        validateAdmittedTempWorkspaceChild(current, parent.ownerUid, mode);
+        validateAdmittedTempWorkspaceChild(current, parent.ownerUid, mode, dir);
         parent.assertCurrent();
     }
     finally {
         owner.close();
     }
 }
-export function validateAdmittedTempWorkspaceChild(current, ownerUid, mode) {
-    assertTempWorkspaceChildState(current, ownerUid);
+export function validateAdmittedTempWorkspaceChild(current, ownerUid, mode, dir) {
+    assertTempWorkspaceChildState(current, ownerUid, dir);
     if (!childHasRequestedMode(current, mode)) {
         throw new FsSafeError("path-mismatch", "temp workspace final mode could not be verified");
     }

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-descriptor.js

@@ -133,9 +133,8 @@ export class TempWorkspaceRetainedChild {
             // the synchronous caller validates it and decides whether to correct.
             const stat = fsSync.fstatSync(descriptor.fd, { bigint: true });
             Object.freeze(stat);
-            const receipt = Object.freeze({ stat });
             return {
-                retained: new TempWorkspaceRetainedChild(dir, stat, descriptor, receipt),
+                retained: new TempWorkspaceRetainedChild(dir, stat, descriptor, stat),
                 stat,
             };
         }
@@ -151,23 +150,27 @@ export class TempWorkspaceRetainedChild {
         // Clear first so validation failures, procfs checks, and later admission
         // can never reuse the creation observation.
         this.#initialReceipt = undefined;
-        return receipt?.stat;
+        return receipt;
     }
     finalizeAdmission(ownerUid, mode) {
         this.#assertModeLeaseReleased();
         this.discardInitialReceipt();
-        if (this.#fd === undefined) {
-            throw new FsSafeError("path-mismatch", "temp workspace child descriptor is unavailable");
-        }
+        const fd = this.#requireDescriptor();
         // A failed revalidation must never leave an earlier receipt transferable.
         this.#transferAuthorized = false;
-        const current = inspectTempWorkspaceDescriptorIdentitySync(this.#fd, this.#identity, this.#numericIdentity);
-        validateAdmittedTempWorkspaceChild(current, ownerUid, mode);
+        const current = inspectTempWorkspaceDescriptorIdentitySync(fd, this.#identity, this.#numericIdentity);
+        validateAdmittedTempWorkspaceChild(current, ownerUid, mode, this.#dir);
         const named = inspectTempWorkspaceDirectoryIdentitySync(this.#dir, this.#identity, this.#numericIdentity);
-        validateAdmittedTempWorkspaceChild(named, ownerUid, mode);
+        validateAdmittedTempWorkspaceChild(named, ownerUid, mode, this.#dir);
         this.#transferAuthorized = true;
         return named;
     }
+    #requireDescriptor() {
+        if (this.#fd === undefined) {
+            throw new FsSafeError("path-mismatch", "temp workspace child descriptor is unavailable");
+        }
+        return this.#fd;
+    }
     #assertModeLeaseReleased() {
         if (this.#modeLease) {
             throw new FsSafeError("path-mismatch", "temp workspace child mode operation is active");
@@ -175,9 +178,9 @@ export class TempWorkspaceRetainedChild {
     }
     #inspectModeTarget(fd, ownerUid, initial) {
         const descriptor = initial ?? inspectTempWorkspaceDescriptorIdentitySync(fd, this.#identity, this.#numericIdentity);
-        assertTempWorkspaceChildState(descriptor, ownerUid);
+        assertTempWorkspaceChildState(descriptor, ownerUid, this.#dir);
         const named = inspectTempWorkspaceDirectoryIdentitySync(this.#dir, this.#identity, this.#numericIdentity);
-        assertTempWorkspaceChildState(named, ownerUid);
+        assertTempWorkspaceChildState(named, ownerUid, this.#dir);
         return descriptor;
     }
     async #assertProcAuthority(fd, ownerUid) {
@@ -196,16 +199,13 @@ export class TempWorkspaceRetainedChild {
         const opened = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), this.#identity);
         const followed = inspectFileIdentitySync(() => fsSync.statSync(procPath, { bigint: true }), this.#identity);
         assertOwnedDirectory(opened, followed);
-        assertTempWorkspaceChildState(opened, ownerUid);
-        assertTempWorkspaceChildState(followed, ownerUid);
+        assertTempWorkspaceChildState(opened, ownerUid, this.#dir);
+        assertTempWorkspaceChildState(followed, ownerUid, this.#dir);
     }
     async initializeMode(mode, ownerUid, assertParent) {
         this.#assertModeLeaseReleased();
         this.discardInitialReceipt();
-        if (this.#fd === undefined) {
-            throw new FsSafeError("path-mismatch", "temp workspace child descriptor is unavailable");
-        }
-        const fd = this.#fd;
+        const fd = this.#requireDescriptor();
         this.#transferAuthorized = false;
         this.#modeLease = true;
         try {
@@ -238,10 +238,7 @@ export class TempWorkspaceRetainedChild {
     }
     initializeModeSync(mode, ownerUid, assertParent) {
         this.#assertModeLeaseReleased();
-        if (this.#fd === undefined) {
-            throw new FsSafeError("path-mismatch", "temp workspace child descriptor is unavailable");
-        }
-        const fd = this.#fd;
+        const fd = this.#requireDescriptor();
         this.#transferAuthorized = false;
         this.#modeLease = true;
         try {
@@ -270,9 +267,7 @@ export class TempWorkspaceRetainedChild {
         this.discardInitialReceipt();
         if (this.canEnumerate)
             return true;
-        if (this.#fd === undefined) {
-            throw new FsSafeError("path-mismatch", "temp workspace child descriptor is unavailable");
-        }
+        this.#requireDescriptor();
         // Opening or validating a replacement crosses a new pathname boundary.
         // Even failure must revoke any earlier final-admission receipt.
         this.#transferAuthorized = false;
@@ -312,13 +307,10 @@ export class TempWorkspaceRetainedChild {
     transfer(retainDescriptor) {
         this.#assertModeLeaseReleased();
         this.discardInitialReceipt();
-        if (this.#fd === undefined) {
-            throw new FsSafeError("path-mismatch", "temp workspace child descriptor is unavailable");
-        }
+        const fd = this.#requireDescriptor();
         if (!this.#transferAuthorized) {
             throw new FsSafeError("path-mismatch", "temp workspace child has not completed final admission");
         }
-        const fd = this.#fd;
         this.#fd = undefined;
         if (retainDescriptor && !this.canEnumerate) {
             closeAfterAdmissionFailure(fd, new FsSafeError("helper-unavailable", "temp workspace cleanup requires a readable child descriptor"), "temp workspace child descriptor rejection and close failed");

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

@@ -32,17 +32,6 @@ function kindForDirent(dirent) {
 function shouldStop(result, options) {
     return options.maxEntries !== undefined && result.scannedEntryCount >= Math.max(0, options.maxEntries);
 }
-function buildEntry(params) {
-    const fullPath = params.fullPath;
-    return {
-        name: params.dirent.name,
-        path: fullPath,
-        relativePath: params.relativePath,
-        depth: params.depth,
-        kind: params.kind,
-        dirent: params.dirent,
-    };
-}
 function recordFailedDir(result, root, dir, depth, error) {
     const relativePath = path.relative(root, dir);
     result.failedDirs.push({
@@ -138,7 +127,7 @@ export function walkDirectorySync(rootDir, options = {}) {
                 if (!kind)
                     continue;
                 const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
-                const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
+                const entry = { name: dirent.name, path: fullPath, relativePath, depth, kind, dirent };
                 if (options.include?.(entry) ?? true) {
                     result.entries.push(entry);
                 }
@@ -229,7 +218,7 @@ export async function walkDirectory(rootDir, options = {}) {
                 if (!kind)
                     continue;
                 const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
-                const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
+                const entry = { name: dirent.name, path: fullPath, relativePath, depth, kind, dirent };
                 const include = options.include;
                 const included = include == null ? true : Reflect.apply(include, options, [entry]);
                 if ((isObjectResult(included) ? await included : included) ?? true) {

package/node_modules/@openclaw/fs-safe/dist/watch-native.d.ts

@@ -1,7 +1,7 @@
 import { type NativeBinding } from "./native.js";
 import type { RootContext } from "./root-context.js";
 import type { DirectoryIdentity, WatchSnapshot } from "./watch-scan.js";
-import type { WatchStreamPaths } from "./watch-stream.js";
+import type { WatchScope } from "./watch-types.js";
 export type NativeWatchHint = {
     directory: string;
     name: string;
@@ -50,6 +50,6 @@ export declare class NativeWatchBackend {
     add(name: string, identity: DirectoryIdentity): void;
     testEvent(path: string, flags: number): void;
     entries(snapshot: WatchSnapshot): boolean;
-    configure(paths: WatchStreamPaths): boolean;
+    configure(snapshot: WatchSnapshot, scopes: readonly WatchScope[]): boolean;
     close(): void;
 }

package/node_modules/@openclaw/fs-safe/dist/watch-native.js

@@ -1,6 +1,7 @@
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
+import { watchStreamPaths } from "./watch-stream.js";
 export function watchBinding(mode) {
     if (mode === "poll")
         return;
@@ -61,9 +62,10 @@ export class NativeWatchBackend {
             throw watchError(cause);
         }
     }
-    configure(paths) {
+    configure(snapshot, scopes) {
         if (process.platform !== "darwin")
             return false;
+        const paths = watchStreamPaths(snapshot, scopes);
         const key = JSON.stringify(paths);
         if (this.streamPaths === key)
             return false;