@openclaw/openshell-sandbox 2026.10.1-beta.2 → 2026.10.5-beta.1

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/temp-workspace-owner.d.ts

@@ -9,6 +9,7 @@ export declare class TempWorkspaceCleanupCapability {
     readonly parent: RetainedDirectory | undefined;
     constructor(root: string, safety: TempWorkspaceCleanupSafety, admission: TempWorkspaceRootAdmission, dirMode: number);
     get canRemoveOwnedTree(): boolean;
+    get canUseCompatibleCleanup(): boolean;
     prepareChildCreation(): void;
     admitChildDescriptor(canEnumerate: boolean): boolean;
     assertCurrent(): void;

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

@@ -8,6 +8,8 @@ import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { openTempWorkspaceCleanupParent, TempWorkspaceRetainedChild, } from "./temp-workspace-descriptor.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { isFsSafeNativeRequired } from "./native-config.js";
+import { cachedNoReplaceUnavailable, noReplaceUnavailable, rememberNoReplaceUnavailable } from "./native-noreplace.js";
 function isNativeCleanupBinding(binding) {
     return typeof binding?.renameNoReplace === "function" &&
         typeof binding.removeOwnedTree === "function" &&
@@ -94,6 +96,9 @@ export class TempWorkspaceCleanupCapability {
         return (this.#phase === "ready" || this.#phase === "sealed") &&
             this.#ownedTreeRemovalAvailable;
     }
+    get canUseCompatibleCleanup() {
+        return this.#safety === "compatible" && !isFsSafeNativeRequired();
+    }
     prepareChildCreation() {
         const replay = this.#phase === "ready";
         if (this.#phase !== "new" && !replay) {
@@ -269,11 +274,27 @@ export class TempWorkspaceCleanupOwner {
             }
             const name = `.fs-safe-workspace-cleanup-${randomUUID()}`;
             const quarantinePath = path.join(parent.receipt.path, name);
-            const nativeRemoval = this.#capability.canRemoveOwnedTree && this.#directory !== undefined;
+            let nativeRemoval = this.#capability.canRemoveOwnedTree && this.#directory !== undefined;
             if (nativeRemoval) {
-                this.#capability.binding.renameNoReplace(parent.fd, path.basename(this.#dir), parent.fd, name);
+                const binding = this.#capability.binding;
+                try {
+                    const cached = cachedNoReplaceUnavailable(binding, parent.fd, "workspace quarantine");
+                    if (cached)
+                        throw cached;
+                    binding.renameNoReplace(parent.fd, path.basename(this.#dir), parent.fd, name);
+                }
+                catch (error) {
+                    const unavailable = error instanceof FsSafeError && error.code === "helper-unavailable"
+                        ? error : noReplaceUnavailable(error, "workspace quarantine", true);
+                    if (!unavailable)
+                        throw error;
+                    rememberNoReplaceUnavailable(binding, parent.fd, unavailable);
+                    if (!this.#capability.canUseCompatibleCleanup)
+                        throw unavailable;
+                    nativeRemoval = false;
+                }
             }
-            else {
+            if (!nativeRemoval) {
                 // The admitted receipt is exact and descriptor-associated. Reuse it as
                 // the pre/post parent fence instead of layering a numeric guard over it.
                 this.#capability.assertCurrent();
@@ -288,7 +309,9 @@ export class TempWorkspaceCleanupOwner {
             }
             return { name, path: quarantinePath, nativeRemoval };
         }
-        catch {
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "helper-unavailable")
+                throw error;
             // A failed rename can still have committed on a remote filesystem.
             return "indeterminate";
         }

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;

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

@@ -55,15 +55,9 @@ export function mergeWatchRescan(scopes, before, slice, requested) {
         for (const name of slice.childPaths?.get(directory)?.values() ?? [])
             selected.add(name);
     }
-    for (const [name, previous] of before.entries) {
-        if (!selected.has(name))
-            continue;
-        const current = slice.entries.get(name);
-        if ((previous.startsWith("directory:") || current?.startsWith("directory:")) && identity(previous) !== identity(current))
-            return;
-    }
-    for (const [name, current] of slice.entries) {
-        if (selected.has(name) && current.startsWith("directory:") && identity(current) !== identity(before.entries.get(name)))
+    for (const name of selected) {
+        const previous = before.entries.get(name), current = slice.entries.get(name);
+        if ((previous?.startsWith("directory:") || current?.startsWith("directory:")) && identity(previous) !== identity(current))
             return;
     }
     // Exclusion changes can retire or admit a subtree, including callback-driven changes.

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

@@ -5,7 +5,6 @@ import { rootHandleContext } from "./root-handle-context.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { mergeWatchRescan, watchRescanScopes } from "./watch-rescan.js";
-import { watchStreamPaths } from "./watch-stream.js";
 import { admittedNativeChanges, changedEntries, excludedWatchPath, guardedHintChanges, scopedChanges } from "./watch-hints.js";
 import path from "node:path";
 import { watchBinding, NativeWatchBackend } from "./watch-native.js";
@@ -338,7 +337,7 @@ export function watch(root, input) {
                 }, maxPendingPaths, persistent);
                 backend = candidate;
                 if (snapshot)
-                    candidate.configure(watchStreamPaths(snapshot, g.scopes));
+                    candidate.configure(snapshot, g.scopes);
                 const hookResult = getFsSafeTestHooks()?.afterWatchBackendCreated?.(context.rootReal, batch => {
                     if (backend === candidate)
                         onHint(g, batch);
@@ -401,7 +400,7 @@ export function watch(root, input) {
             }
             try {
                 const entriesChanged = backend?.entries(next);
-                const streamsChanged = backend?.configure(watchStreamPaths(next, g.scopes));
+                const streamsChanged = backend?.configure(next, g.scopes);
                 if (entriesChanged || streamsChanged) {
                     // Complete a guarded pass with the new transport before publishing readiness.
                     // Bound handovers under churn; later passes still reconcile ongoing changes.

package/node_modules/@openclaw/fs-safe/docs/advanced.md

@@ -82,6 +82,7 @@ concurrent namespace changes.
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `retainEntryForPublication`, `RetainedEntryPublication`, `RetainEntryForPublicationOptions`, `EntryPublicationReceipt`, `EntryPublicationResult`, `EntryPublicationIssue`, `PublicationIdentity`, `PublicationParent` | [One-way entry publication](entry-publication.md) | Native no-replace directory/regular-file/symlink export, including Windows NTFS junctions, under caller-exclusive namespace; explicit transition receipts, close-only disposal, no source CAS. |
 | `retainFileInDirectory`, `RetainedFile`, related receipt/result types | [Retained Windows files](retained-file.md) | Existing-file native handle custody and explicit removal; local NTFS, producer authority required, no persistence guarantee. |
+| `copyRootFileSync`, `createRootFileCopyBatchSync`, `RootFileCopyBatchSync`, `CopyRootFileSyncOptions`, `CopiedRootFileSync` | [copy.md](copy.md#synchronous-guarded-file-copies) | Synchronous guarded exclusive file copy, optionally cloned and bound to an expected source identity, returning an owned destination descriptor and both identities. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |

package/node_modules/@openclaw/fs-safe/docs/archive.md

@@ -179,7 +179,8 @@ between native and JavaScript paths rather than reimplementing it in Rust.
 
 ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless internal separator and dot-component equivalence is allowed only after validation; every raw and Unicode interpretation must also agree on whether its name ends in `/` or `\`. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
 
-ZIP preflight and bounded reads apply extraction's case-insensitive NFC collision
+ZIP preflight and bounded reads use extraction's canonical path identity, including
+removing directory trailing separators, and apply its case-insensitive NFC collision
 policy to the complete archive, including entries that extraction would strip
 or skip. Known UTF-8 and Unicode Path names are checked during physical admission;
 legacy names retain backend-selected decoding and undergo the same collision
@@ -701,6 +702,9 @@ await extractArchive({
 
 ## `readArchiveEntry`
 
+The byte limit is selected and validated once before reading the archive; changing
+the options object during a read does not change the active limit.
+
 `readArchiveEntry(archivePath, entryPath, { maxBytes, kind? })` reads one
 regular-file entry into a bounded `Buffer` without extracting a tree. It reads
 the input through an identity-checked descriptor, rejects a requested link or

package/node_modules/@openclaw/fs-safe/docs/atomic.md

@@ -16,6 +16,11 @@ import {
 
 Write `content` to a sibling temp file in the destination directory, apply the parent-directory and final file modes through verified descriptors, optionally `fsync` the file descriptor, optionally `fsync` the parent directory after rename, then atomically rename over the destination. No permission change follows a caller-supplied pathname.
 
+On POSIX, non-durable asynchronous writes using Node inspect the staged file's
+complete permission bits with their final identity check and skip a redundant
+mode change when they already match. A restrictive umask or differing special
+bits still require descriptor mode correction before publication.
+
 On POSIX, the parent is opened with no-follow and directory-only flags, checked against its exact pre-open device/inode identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
 
 Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
@@ -258,7 +263,9 @@ opened, removed, or replaced. A successor at that name is left untouched.
 `details.cleanup: "restored"` means the retained original file's bytes and mode
 were restored and synchronized, not that the pathname still names it. The existing
 `writing` receipt identifies that file; no `published` receipt is emitted for a
-failed replacement. Restoration I/O failures report `"restore-failed"`.
+failed replacement. Restoration I/O failures report `"restore-failed"`, even if
+the thrown error itself carries a `cleanup: "restored"` receipt from another
+operation; the cause retains both the replacement and restoration failures.
 
 Callback refusals, detected identity/type/link changes, and other metadata errors
 remain terminal. Failed descriptor revalidation also stops restoration. These
@@ -539,8 +546,9 @@ remain a best-effort sequence, not atomic.
 `onDestinationPublished` runs exactly once after a successful rename resolves,
 before awaited post-rename directory checks or source cleanup. It receives a
 frozen receipt with the resolved absolute destination path and the exact bigint
-device/inode identity observed on the rename source before dispatch: the
-original source for a direct rename, or the staged copy for fallback. Failed
+device/inode identity observed on the rename source after the synchronous
+authority callbacks return and before dispatch: the source selected for a direct
+rename, or the staged copy for fallback. Failed
 rename attempts never emit receipts. The return contract remains `Promise<void>`.
 
 The receipt records an observed identity, not authorization, durable storage,

package/node_modules/@openclaw/fs-safe/docs/contributing.md

@@ -175,7 +175,7 @@ temporary storage; session scratch trees may suppress macOS filesystem events.
 ### Optional Linux Testbox
 
 The manual `testbox-validation.yml` workflow prepares a 16-vCPU Ubuntu 24.04
-Blacksmith Testbox with Node 24.21.0, pnpm 12.4.2, dependencies, the Rust WASM
+Blacksmith Testbox with Node 24.21.0, pnpm 12.10.1, dependencies, the Rust WASM
 target, and the pinned portable archive compiler. It leaves library builds and
 validation commands to the caller and does not replace required CI checks.
 

package/node_modules/@openclaw/fs-safe/docs/copy.md

@@ -58,7 +58,7 @@ Apple [strongly discourages general directory cloning](https://github.com/apple-
 | `"always"`         | Require native cloning. Unsupported operations fail without a byte-copy fallback.                                                            |
 | `"never"`          | Copy regular file bytes using reads and writes. No native cloning or copy-offload calls. Works without a native binding.                     |
 
-Automatic copying does not recover from permission errors, I/O errors, cancellation, or rejected source contents such as ReFS named streams. A failed clone must leave the destination absent before fallback can create it; otherwise copying fails rather than merging into a partial tree.
+On Linux XFS and ZFS, `FICLONE` capability failures (including an ioctl denied by container seccomp or LSM policy with `EPERM`) select byte copying in `"auto"` mode; `"always"` reports `unsupported-platform`. Automatic copying does not recover from ordinary file-access permission errors, I/O errors, cancellation, or rejected source contents such as ReFS named streams. Native reflink workers settle and remove partial output before returning a clone failure. A failed clone must leave the destination absent before fallback can create it; otherwise copying fails rather than merging into a partial tree.
 
 `concurrency` accepts integers from 1 through 32 and bounds active file copies. ReFS, XFS, and ZFS cloning default to 16 workers. Byte copying defaults to four concurrent files on Windows and one elsewhere. Btrfs uses its bulk operation. APFS uses a bulk clone followed by native directory-entry enumeration to restore directory timestamps; known regular files and symbolic links need no additional stat or open.
 
@@ -197,3 +197,111 @@ Run `node scripts/clone-xfs-proof.mjs MOUNT` on a real XFS volume to verify the
 Run `node scripts/clone-zfs-proof.mjs MOUNT POOL` on a dedicated, otherwise idle Linux ZFS pool with compression and deduplication disabled. It verifies both `copyTree` and `Root.copyIn` through hashes and changes in the documented `bclonesaved` pool counter. It requires `zfs`, `zpool`, and `findmnt`, including permission to run `zpool sync`. Add `no-reflink` for a pool without block cloning to verify strict refusal and automatic byte fallback. The script creates and removes only its temporary directory; it does not create pools or change their properties.
 
 Run `node benchmarks/clone.mjs SOURCE DESTINATION_PARENT` after `pnpm build` to compare one, four, and 16 workers on the same immutable source. Add `3 auto` or `3 never` to measure three samples of ordinary copying, including NTFS destinations. It records copying time separately from fixture preparation and full file-hash verification, and retains its uniquely named output directory for inspection. Prepare Btrfs sources with `createCloneSource` first.
+
+## Synchronous guarded file copies
+
+`copyRootFileSync` from `@openclaw/fs-safe/advanced` is for synchronous module
+hooks and capture owners. Both roots and file paths are absolute; destination
+parents must exist. The destination must be absent, and is created exclusively.
+
+```ts
+import { copyRootFileSync } from "@openclaw/fs-safe/advanced";
+
+using copied = copyRootFileSync({
+  source: { rootPath: "/srv/plugins", absolutePath: "/srv/plugins/plugin.js" },
+  destination: { rootPath: "/srv/capture", absolutePath: "/srv/capture/plugin.js" },
+  clone: "auto",
+  maxBytes: 16 * 1024 * 1024,
+  mode: 0o600,
+});
+// Hash or read copied.fd: this is the owned destination, never a reopened path.
+console.log(copied.bytes, copied.method, copied.identity, copied.sourceIdentity);
+```
+
+`CopyRootFileSyncOptions` selects the source and destination, `clone`, `maxBytes`,
+`mode`, `preserveSourceMode`, `sourceHardlinks`, and optional `expectedSourceIdentity`.
+`CopiedRootFileSync` owns a
+readable/writable `fd`, with idempotent `close()` and `Symbol.dispose`, and returns
+`path`, `bytes`, `method` (`"clone"`, `"copy-file-range"`, or `"copy"`), and exact
+bigint destination `identity` and `sourceIdentity` (`dev`, `ino`). Both identities
+are readonly and frozen. Closing releases the descriptor, not the file.
+
+Callers that already pinned a source can pass `expectedSourceIdentity: { dev, ino }`
+from `fs.fstatSync(pinnedSourceFd, { bigint: true })`. fs-safe still admits and
+opens its own source descriptor, and compares its exact bigint identity before
+creating any destination. A mismatch throws `FsSafeError("path-mismatch")`.
+Keep the caller's descriptor open across the call; it remains caller-owned and
+its cursor is unchanged. Do not derive the expectation from numeric stat fields,
+which may have lost identity bits. Omitting the option preserves ordinary source
+admission. Every successful copy method returns `sourceIdentity` for the source
+actually copied, verified current again at the end of the operation. This binds
+identity only; keep any existing source fingerprint/content and destination
+receipt checks for concurrent edits and later replacements.
+
+Clone policy matches `Root.copyIn`: the default is `"never"`; `"auto"` tries
+native cloning, then bounded copy offload and byte copying on capability failure;
+`"always"` requires cloning or throws `unsupported-platform`. APFS cloning
+creates the guarded destination name from the admitted source descriptor. Linux
+uses FICLONE and copy_file_range. Windows and native-disabled operation copy
+bytes; they cannot satisfy `"always"`.
+
+The source descriptor remains open through before/after source identity checks.
+Symlink components are rejected; source hardlinks are rejected unless
+`sourceHardlinks: "allow"` is selected. The byte limit is an EOF bound, not a
+prefix length: overflow throws `too-large`. Omitted limits are unlimited. An
+explicit mode wins over `preserveSourceMode`; otherwise new files use `0o600`
+subject to the process umask, consistently with `copyIn`.
+
+Failures attempt identity-checked removal of the owned destination and preserve
+replacement entries. This helper creates directly at the destination name, so
+other processes may observe partial bytes until it returns. It does not promise
+crash durability or a coherent snapshot of concurrent in-place source edits.
+Use a private capture directory and keep sources unchanged while capturing.
+
+### Batches of synchronous guarded copies
+
+`createRootFileCopyBatchSync()` on `advanced` returns a disposable
+`RootFileCopyBatchSync`. Its `copyFile(options)` takes the same
+`CopyRootFileSyncOptions` and returns the same owned `CopiedRootFileSync` as
+`copyRootFileSync`:
+
+```ts
+import { createRootFileCopyBatchSync } from "@openclaw/fs-safe/advanced";
+
+using batch = createRootFileCopyBatchSync();
+for (const name of ["plugin.js", "package.json"]) {
+  using copied = batch.copyFile({
+    source: { rootPath: "/srv/plugins", absolutePath: `/srv/plugins/${name}` },
+    destination: { rootPath: "/srv/capture", absolutePath: `/srv/capture/${name}` },
+    clone: "auto",
+    maxBytes: 16 * 1024 * 1024,
+  });
+  console.log(copied.bytes, copied.sourceIdentity);
+}
+```
+
+On canonical POSIX paths, the batch retains root and ancestor directory
+identities across files. Every use still checks those identities without
+following directory symlinks; root and parent canonical paths are rechecked.
+Source opens, source and destination file identities, hardlink policy, exclusive
+creation, bounds, permissions, and cleanup are checked separately for every file.
+No source descriptor, file contents, or successful file-admission result is cached.
+An ancestor replacement rejects even when the leaf parent has not changed.
+Windows and noncanonical path spellings keep the full per-file resolver and its
+alias handling. There is no option to bypass validation.
+
+Keep the batch scoped to one capture or materialization, with unchanged source
+and destination directory topology. `close()` and `Symbol.dispose` idempotently
+release its retained metadata; later calls reject with `invalid-path`. Returned
+file descriptors remain independently caller-owned. Successful earlier files
+are not rolled back if a later copy fails. A failed copy keeps the ordinary
+identity-checked cleanup contract; the batch is not an atomic tree transaction
+or a coherent snapshot of concurrent edits. The single-file helper also reuses
+directory admissions for the duration of its one copy.
+
+Both APIs reuse the freshly checked canonical root during initial POSIX path
+admission. This avoids repeatedly resolving every absolute root component while
+retaining lexical traversal and the before/after root and parent identity checks.
+Windows and root aliases retain the ordinary resolver, including its handling
+of dot segments in symlink targets. No caller changes are needed for the
+single-file improvement.