@openclaw/openshell-sandbox 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/dist/windows-security-command.d.ts

@@ -1,6 +1,14 @@
 import type { NativeWindowsDescriptorSecurityFacts, NativeWindowsSecurityFacts } from "./native-binding.js";
+import type { FsSafeNativeMode } from "./native-config.js";
+import { type DescriptorFacts } from "./windows-security-facts.js";
+export declare const WINDOWS_SECURITY_BATCH_MAX_BYTES: number;
 /** Cleanup must preserve stages still reachable by an unsettled command. */
 export declare function hasUnsettledWindowsSecurityCommand(error: unknown): boolean;
+export declare function readWindowsSecurityFactsBatch(paths: readonly string[], options: {
+    timeoutMs: number;
+    native: boolean;
+    mode: FsSafeNativeMode;
+}): Promise<DescriptorFacts[]>;
 export declare function readWindowsSecurityFactsCommand(targetPath: string): NativeWindowsSecurityFacts;
 export declare function inspectWindowsDescriptorCommand(fd: number): Promise<NativeWindowsDescriptorSecurityFacts>;
 export declare function createPrivateWindowsDirectoryCommand(targetPath: string, expectedParentIdentity?: string): Promise<{

package/node_modules/@openclaw/fs-safe/dist/windows-security-command.js

@@ -3,10 +3,11 @@ import { fileURLToPath } from "node:url";
 import { FsSafeError } from "./errors.js";
 import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
-import { parseWindowsSecurityCommandFacts } from "./windows-security-facts.js";
+import { parseWindowsOwnerAndDaclFacts, parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TERMINATION_GRACE_MS = 1_000;
 const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
+export const WINDOWS_SECURITY_BATCH_MAX_BYTES = 16 * 1024 * 1024;
 function isFullIdentity(identity) {
     return typeof identity === "string" && identity.length === 49 && FULL_IDENTITY.test(identity);
 }
@@ -50,9 +51,6 @@ function command(operation, params) {
         },
     };
 }
-function unverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -79,6 +77,10 @@ function parseReplyValue(stdout, operation) {
         unverified("Windows security command returned an incomplete response");
     }
     if (!response.ok) {
+        if (operation === "paths" &&
+            (response.code === "helper-unavailable" || response.code === "too-large") && typeof response.message === "string") {
+            throw new FsSafeError(response.code, response.message);
+        }
         const codes = new Set(["EACCES", "EPERM", "EEXIST", "ENOENT", "ENOTSUP", "EIO", "EBADF", "ELOOP", "ENOTDIR", "EINVAL", "ENOSPC", "EBUSY"]);
         if (typeof response.code !== "string" || !codes.has(response.code) || typeof response.message !== "string") {
             unverified("Windows security command returned an invalid failure");
@@ -115,13 +117,13 @@ class WindowsSecurityCommandError extends PermissionCommandError {
     timedOut;
     creationOutcome;
     processExitConfirmed;
-    constructor(file, durationMs, receipt, timedOut) {
-        super(file, durationMs, receipt);
+    constructor(file, durationMs, receipt, timedOut, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+        super(file, durationMs, receipt, timeoutMs);
         this.timedOut = timedOut;
         this.creationOutcome = receipt.creationOutcome;
         this.processExitConfirmed = receipt.processExitConfirmed;
         if (timedOut)
-            this.message = `Windows permission inspection timed out after ${DEFAULT_PERMISSION_EXEC_TIMEOUT_MS}ms`;
+            this.message = `Windows permission inspection timed out after ${timeoutMs}ms`;
         if (!receipt.processExitConfirmed)
             this.message += "; process exit was not confirmed";
         else if (!receipt.outputClosed)
@@ -159,11 +161,12 @@ export function hasUnsettledWindowsSecurityCommand(error) {
     return pending.length > 0;
 }
 function ignoreLateError() { }
-async function execute(operation, params) {
-    const { file, args, env } = command(operation, params);
+async function execute(operation, params, request) {
+    const selected = request ?? command(operation, params);
+    const { file, args, env, input, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, maxOutputBytes = MAX_OUTPUT_BYTES } = selected;
     const startedAt = performance.now();
     return await new Promise((resolve, reject) => {
-        const child = spawn(file, args, { windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"] });
+        const child = spawn(file, args, { windowsHide: true, env, stdio: [input === undefined ? params.fd ?? "ignore" : "pipe", "pipe", "pipe"] });
         const output = [];
         const errors = [];
         let bytes = 0;
@@ -183,7 +186,7 @@ async function execute(operation, params) {
         const timeout = setTimeout(() => {
             timedOut = true;
             fail(deadlineError());
-        }, DEFAULT_PERMISSION_EXEC_TIMEOUT_MS);
+        }, timeoutMs);
         const finish = (outputClosed) => {
             if (settled)
                 return;
@@ -196,6 +199,18 @@ async function execute(operation, params) {
             child.removeListener("error", onChildError);
             child.on("error", ignoreLateError);
             const cleanupErrors = [];
+            if (input !== undefined && child.stdin) {
+                child.stdin.removeListener("error", fail);
+                child.stdin.on("error", ignoreLateError);
+                if (!outputClosed) {
+                    try {
+                        child.stdin.destroy();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+            }
             for (const [stream, collect] of [[child.stdout, collectOutput], [child.stderr, collectErrors]]) {
                 if (!stream)
                     continue;
@@ -224,7 +239,7 @@ async function execute(operation, params) {
                     cause: failure, pid: child.pid ?? null, code: exitCode, signal: exitSignal, stderr: Buffer.concat(errors),
                     processExitConfirmed, outputClosed, terminationSignalSent, terminationError, cleanupErrors,
                     ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
-                }, timedOut));
+                }, timedOut, timeoutMs));
             }
             else {
                 try {
@@ -263,7 +278,7 @@ async function execute(operation, params) {
             if (failed || settled)
                 return;
             bytes += chunk.length;
-            if (bytes <= MAX_OUTPUT_BYTES)
+            if (bytes <= maxOutputBytes)
                 chunks.push(chunk);
             else
                 fail(new Error("Windows security command exceeded its output budget"));
@@ -285,7 +300,7 @@ async function execute(operation, params) {
         };
         const onClose = (code, signal) => {
             onExit(code, signal);
-            if (!failed && performance.now() - startedAt >= DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+            if (!failed && performance.now() - startedAt >= timeoutMs) {
                 timedOut = true;
                 failed = true;
                 failure = deadlineError();
@@ -301,11 +316,47 @@ async function execute(operation, params) {
         child.stderr?.on("error", fail);
         child.stdout?.on("data", collectOutput);
         child.stderr?.on("data", collectErrors);
-        if (!child.stdout || !child.stderr) {
+        if (!child.stdout || !child.stderr || (input !== undefined && !child.stdin)) {
             // Node reports spawn errors on nextTick, which can follow the current microtask.
             missingPipes = setImmediate(() => { if (!failed && !settled)
                 fail(new Error("Windows security command output pipes are unavailable")); });
         }
+        if (input !== undefined && child.stdin) {
+            child.stdin.on("error", fail);
+            try {
+                child.stdin.end(input, "utf8");
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+    });
+}
+export async function readWindowsSecurityFactsBatch(paths, options) {
+    const invocation = command("paths", {});
+    const request = {
+        ...invocation,
+        input: JSON.stringify(paths),
+        timeoutMs: options.timeoutMs,
+        maxOutputBytes: WINDOWS_SECURITY_BATCH_MAX_BYTES,
+    };
+    if (options.native) {
+        request.file = process.execPath;
+        request.args = ["--", fileURLToPath(new URL("./owner-dacl-batch-worker.js", import.meta.url))];
+        request.env = {
+            ...Object.fromEntries(Object.entries(invocation.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH", "FS_SAFE_OWNER_DACL_BATCH_MODE"].includes(key.toUpperCase()))),
+            FS_SAFE_OWNER_DACL_BATCH_MODE: options.mode,
+        };
+    }
+    const response = await execute("paths", {}, request);
+    if (!Array.isArray(response) || response.length !== paths.length) {
+        unverified("Windows security command returned an incomplete path batch");
+    }
+    return response.map((row, index) => {
+        if (!record(row) || row.path !== paths[index]) {
+            unverified("Windows security command returned a mismatched path batch");
+        }
+        return parseWindowsOwnerAndDaclFacts(row.security);
     });
 }
 export function readWindowsSecurityFactsCommand(targetPath) {

package/node_modules/@openclaw/fs-safe/dist/windows-security-facts.d.ts

@@ -1,4 +1,8 @@
 import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+export type DescriptorFacts = Pick<NativeWindowsSecurityFacts, "ownerSid" | "currentUserSid" | "daclPresent" | "isLocal" | "aceListComplete" | "unsupportedAceTypes" | "aces">;
+export declare function unverified(message: string, cause?: unknown): never;
+/** Validate policy-free observations crossing the isolated batch transport. */
+export declare function parseWindowsOwnerAndDaclFacts(value: unknown): DescriptorFacts;
 /** Raw reporting retains unknown flag bits; secure admission validates them below. */
 export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
 /** Native and command observations share the same fail-closed admission policy. */

package/node_modules/@openclaw/fs-safe/dist/windows-security-facts.js

@@ -6,8 +6,8 @@ const WORLD_SIDS = new Set([
     "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
     "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
 ]);
-function unverified(message) {
-    throw new FsSafeError("permission-unverified", message);
+export function unverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
 }
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -46,6 +46,10 @@ function validateDescriptor(value, allowUnknownFlags) {
     }
     return value;
 }
+/** Validate policy-free observations crossing the isolated batch transport. */
+export function parseWindowsOwnerAndDaclFacts(value) {
+    return validateDescriptor(value, true);
+}
 function summarize(facts) {
     const ownerClass = facts.ownerSid === facts.currentUserSid ? "current-user"
         : facts.ownerSid === SYSTEM_SID ? "system"

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

@@ -77,10 +77,11 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
+| `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. |
 | `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`. |
-| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
+| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks, inspecting raw segments before `..` normalization. A `..` may undo an inspected real directory, but cannot leave the root or undo an allowed root-child symlink. Raw paths outside the root that normalize inside are rejected. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
 `pathExists()` and `pathExistsSync()` intentionally retain ordinary `stat`
@@ -240,6 +241,7 @@ atomic replacement, use [`Root.write()`](writing.md).
 | Export | Page | Notes |
 |---|---|---|
 | `stageFileInDirectory`, `StagedFile`, `StagedFileReceipt`, `PublishedFileReceipt`, `StagedFilePublication`, `StagedFileCleanupReceipt`, `StagedFileFailureDetails` | [staged-file.md](staged-file.md) | Native-required Linux/macOS lifecycle retaining the original directory for abort cleanup. |
+| `retainSymlinkInDirectory`, `StagedSymlink`, `StagedSymlinkExpected`, `StagedSymlinkReceipt`, `PublishedSymlinkReceipt`, `StagedSymlinkPublication`, `StagedSymlinkRemoval`, `StagedSymlinkCleanupReceipt`, `StagedSymlinkFailureDetails` | [staged-symlink.md](staged-symlink.md) | Native-required retained symlink identity, no-replace publication and explicit recovery; never same-target ownership adoption. |
 | `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.md) | One-file temp primitive; prefer `tempWorkspace` from `@openclaw/fs-safe/temp` for the stable surface. |
 | `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Callback-produced file staging: verified sibling publication or private-workspace copy through a root. |
 
@@ -256,7 +258,7 @@ atomic replacement, use [`Root.write()`](writing.md).
 |---|---|---|
 | `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
 | `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `Error` by default, or an error supplied by `createError`. |
-| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. |
+| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. Allowed roots constrain the real parent of the moved entry, including symlinks; the referent is not moved. Parent identity is rechecked before mutation. |
 
 ## Stability
 

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

@@ -179,6 +179,12 @@ 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
+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
+check before callbacks or selected bytes are returned.
+
 ZIP end-record admission searches the bounded comment window for signatures
 while retaining complete comment-length and ambiguity checks. Dense signature
 sequences fall back to the bounded byte scan.
@@ -211,6 +217,14 @@ loading, including failure. Public preflight still returns ordinary JSZip entry
 objects, with directory keys ending in `/` and recognizable symlink type bits.
 Compressed data is retained even for declared-zero entries, so an empty-size
 claim cannot bypass payload-size or CRC verification during extraction or reads.
+Extraction and bounded reads retain the admitted CRC and size independently of
+mutable decoder objects, so later decoder changes cannot redefine the expected
+payload integrity. Public preflight archives retain ordinary JSZip mutation
+and entry-reading behavior.
+Portable bounded reads select the admitted canonical name and reject a selected
+decoder entry that no longer belongs to that archive and name before reading its
+payload. Extraction retains the admitted names and physical order independently
+of later changes to the decoder's public `files` object.
 
 Within one ZIP entry, identical local and central name bytes reuse the same
 decoded validation. Unicode Path admission is shared only when both the raw names
@@ -238,6 +252,8 @@ directory paths. For example, `./pkg//state\cache/value` is presented as
 `pkg/state/cache/value`, even with `stripComponents: 1`. Case and Unicode
 spelling are preserved. Local PAX `path`, GNU long-name, and supported ZIP
 Unicode Path names use the same canonicalization.
+A leading `~` is a literal archive entry name and is never expanded to the
+user's home directory during extraction, publication, or durability checks.
 Callbacks follow physical archive order, including ZIP names that look like
 integer object keys. The public ZIP loader's `files` object retains ordinary
 JavaScript object enumeration and mutation behavior.

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

@@ -60,6 +60,8 @@ type ReplaceFileAtomicOptions = {
   syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
   syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
   throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
+  assertBeforeMutation?: () => void;
+  onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
   fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
 };
@@ -108,6 +110,66 @@ descriptor is still closed, and a close failure remains reportable.
 
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
+### Atomic write authority and destination state
+
+Use `assertBeforeMutation` when a write depends on a lease or other revocable
+application authority. Both atomic variants capture the callback at entry and
+run it synchronously before directory creation or mode changes, compatibility
+lock acquisition, staging creation and writes, each rename attempt, and fallback
+removal, destination acquisition, truncation, and each content write. Asynchronous destination identity checks
+finish before the final authority check; no await separates that check from the
+write dispatch. A dispatched operation still owns its completion.
+
+`onDestinationState` captures facts that a caller may need if the operation later
+rejects:
+
+```ts
+type ReplaceFileAtomicDestinationState =
+  | Readonly<{ state: "removed"; path: string }>
+  | Readonly<{
+      state: "writing" | "published";
+      path: string;
+      dev: bigint;
+      ino: bigint;
+    }>;
+```
+
+- `removed` follows successful removal of an existing fallback destination.
+- `writing` records the fallback's retained descriptor after exclusive creation
+  or the first successful truncation of an existing `restore-original` target.
+  Opening an existing target leaves it untouched and emits no receipt. This state
+  does not claim that all requested bytes were written.
+- `published` follows successful rename and destination identity verification,
+  before parent synchronization or descriptor close can fail. Copy fallback
+  reports it after its content, mode, and requested file synchronization complete.
+  The explicit `verify-content-with-lock` policy first applies its existing
+  locked content verification to admit the replacement descriptor.
+
+Receipts are frozen and use the destination spelling captured by the operation.
+File identities come from retained descriptors, never from reopening a pathname
+after a failed copy. Failed or indeterminate admission can leave no identity
+receipt; a rename followed by replacement before verification also has no
+publication receipt. Do not infer ownership from a fresh post-failure stat. A later writer
+can replace the pathname, so compare the recorded identity with the current
+entry and recheck application authority before compensation. Receipts do not
+promise durable storage or authorize rollback.
+
+Both callbacks must complete synchronously; Promise, thenable, and synchronous
+or asynchronous generator results are rejected. Returned generators are never
+advanced; other ordinary return values are ignored. The first callback refusal
+is terminal, including falsy thrown values; an `EPERM`, `EEXIST`, or `EBUSY` code
+from a callback never starts fallback or retry. Refusal during an in-place
+fallback also stops new restoration writes. Final mode, synchronization, close,
+and private-stage cleanup may still settle against owned identities after
+revocation. Callback refusal does not delete a published destination or a
+competing file at a staging name. An observer that throws must retain its receipt
+first if recovery needs it.
+
+`beforeRename` remains the hook for preparing backups. Effects performed inside
+that hook remain the caller's responsibility; the authority option guards the
+atomic writer's own effects. Omitting both new callbacks preserves existing
+write, fallback, restoration, result, and cleanup behavior.
+
 ### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
@@ -184,6 +246,22 @@ that same descriptor, and synchronizes the result. Any write, mode, or sync
 failure triggers a byte-and-mode restore and another sync through the same
 descriptor.
 
+With mutation callbacks enabled, an `EIO` from destination `stat`/`lstat` after
+successful truncation also attempts restoration through that retained descriptor.
+Each restore write still requires live application authority and fresh exact
+descriptor identity, regular-file, and configured hardlink checks. The failed
+pathname observation is not retried to authorize restoration; no pathname is
+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"`.
+
+Callback refusals, detected identity/type/link changes, and other metadata errors
+remain terminal. Failed descriptor revalidation also stops restoration. These
+cases can leave the retained file empty or partial with only a `writing` receipt;
+before the first successful truncation, verification failure leaves it untouched.
+
 With `syncTempFile: false`, an exclusive-create copy fallback does not report
 success until its new destination writer closes successfully. This includes
 `"restore-original"` when the destination did not exist. A close rejection or throw is
@@ -214,6 +292,10 @@ through short reads and EOF, grow only as data arrives, and enforce the same
 `beforeRename` callback, and `ReplaceFileAtomicSyncFileSystem`. Use it inside
 synchronous boot paths or test setup code. It returns the same
 `{ method: "rename" | "copy-fallback" }` receipt as the async variant.
+Promise, thenable, and synchronous or asynchronous generator results from the
+hook reject with `TypeError` before publication; rejected promises are consumed
+and generators are never advanced. Other synchronous return values are ignored.
+The replacement is not published; owned-temp cleanup follows the rules above.
 
 ## `replaceDirectoryAtomic`
 
@@ -295,9 +377,9 @@ semantics. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
 temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
-It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
-you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
-or custom copy-fallback policy.
+It delegates to `replaceFileAtomic()` with a smaller call shape, including its
+pre-publication hook and staging-prefix options. Use `replaceFileAtomic()` when
+you need mode preservation or a custom copy-fallback policy.
 
 ```ts
 import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
@@ -317,9 +399,17 @@ type WriteTextAtomicOptions = {
   dirMode?: number;          // parent mode (default 0o777 masked by process umask)
   trailingNewline?: boolean; // append "\n" if missing; default false
   durable?: boolean;         // default true; false skips temp/parent fsync
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  tempPrefix?: string;       // default ".fs-safe-replace"
 };
 ```
 
+`beforeRename` is awaited after the complete text is staged and before
+publication, with the same [stage identity and refusal cleanup](#beforerename)
+checks as `replaceFileAtomic`. Pass `tempPrefix` to identify staged files; it
+uses the same prefix validation, including rejection of empty prefixes and path
+separators.
+
 `durable: false` keeps the sibling-temp replace/rename behavior but skips the
 temp-file and parent-directory `fsync` calls. Use it only for reconstructible
 metadata where lower latency matters more than crash-durability.

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

@@ -70,6 +70,36 @@ Consumers receive the asset in the npm package and need no compiler.
 
 Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
 
+### Linux GNU release bindings
+
+GNU x64 and arm64 artifacts use Zig 0.16.0 and `cargo-zigbuild` 0.23.4 with an
+explicit glibc 2.28 target, independent of the runner's libc. This matches the
+Node Linux runtime baseline and supports RHEL 8-family users without adding a
+second legacy package. Run the same build and ABI gate used in CI and releases:
+
+```bash
+cargo install cargo-zigbuild --version 0.23.4 --locked
+rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs x86_64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs aarch64-unknown-linux-gnu
+```
+
+These commands require Zig on `PATH` and GNU `objdump`. They build the N-API
+cdylib with `cargo zigbuild --target <triple>.2.28`, copy it to the existing
+`artifacts/fs-safe-native.<platform>.node` name, and reject any GLIBC symbol
+requirement above 2.28 before upload. The gate also rejects missing or unknown
+GLIBC versions. To inspect an existing binding, use
+`node scripts/check-linux-glibc.mjs <binding.node>`.
+
+`pnpm native:build` remains a host-toolchain development build; it does not
+establish the GNU release ABI floor.
+
+On Linux x64 or arm64 with Docker, run `pnpm build`, copy the matching GNU artifact from
+`artifacts/` to `native/`, run `node scripts/stage-host-native.mjs`, then run
+`bash scripts/test-linux-glibc-floor.sh`. CI uses this command to load the actual
+artifact and run native security and no-replace move tests in Rocky Linux 8
+(glibc 2.28). Both GNU architectures execute this load test on matching runners.
+
 ## Test
 
 ```bash
@@ -137,6 +167,52 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+The native watch lane requires events on Linux, macOS, and Windows and reports
+actual edit latency. Run `FS_SAFE_TEST_SERIAL=1 pnpm check` to isolate local timing
+checks from the other filesystem stress suites. Watch fixtures use normal OS
+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
+target, and the pinned portable archive compiler. It leaves library builds and
+validation commands to the caller and does not replace required CI checks.
+
+Use an authenticated Blacksmith CLI with access to the repository and its
+Blacksmith organization. From a full repository checkout, warm one session
+through Crabbox:
+
+```sh
+CRABBOX_BLACKSMITH_IDLE_TIMEOUT=240m crabbox warmup --provider blacksmith-testbox \
+  --blacksmith-org openclaw \
+  --blacksmith-workflow .github/workflows/testbox-validation.yml \
+  --blacksmith-job validate --blacksmith-ref main \
+  --idle-timeout 240m --timing-json
+```
+
+Use a branch or tag containing the workflow for `--blacksmith-ref`; GitHub must
+first have registered the workflow on the default branch. The job has a fixed
+240-minute limit. Keep the idle timeout at that limit (240 minutes in the native
+Blacksmith CLI) because the pinned Testbox action can miss active SSH sessions
+behind a forwarded port. Bound commands by the remaining job time and leave time
+to collect results and stop before the deadline.
+
+Use the returned `tbx_...` ID for subsequent commands. The `fs-safe-testbox`
+wrapper restores the prepared tool paths and WASM compiler settings in the SSH
+shell. For example:
+
+```sh
+crabbox run --provider blacksmith-testbox --id <tbx_id> --timing-json -- \
+  fs-safe-testbox pnpm check
+crabbox stop --provider blacksmith-testbox <tbx_id>
+```
+
+Stop the session when finished and verify its terminal status. Blacksmith owns
+checkout synchronization; record the tested source revision or diff, Testbox ID,
+and Actions run. This backend is Linux-only and does not accept Crabbox's direct
+SSH `--script` or `--download` flags. The workflow provides no application secrets.
+
 ### Method benchmarks
 
 `pnpm benchmark:methods` measures the callable library surface against synthetic
@@ -201,10 +277,32 @@ require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standa
 direct `node` invocation without lifecycle metadata is unsupported. Archive
 codecs and their dependencies are packed from the installed dependency graph.
 
-PR CI builds and executes four host targets: Linux x64 glibc, Linux x64 musl
-(Alpine), macOS arm64, and Windows x64. The root-only smoke runs on each. The
-seven-target source build matrix runs on release tags; packaging all seven is
-not execution proof for every architecture. The smoke writes manager versions,
+PR CI builds and executes all seven shipped bindings. The existing check names
+stay stable; extra runner/runtime combinations add checks without changing the
+repository ruleset. Native lanes run Node 24; the GNU host lanes also exercise
+Bun 1.4.2 (as do macOS and Windows).
+
+| Lane | Runner | Architecture / libc | Runtime |
+| --- | --- | --- | --- |
+| JavaScript check | `ubuntu-latest` | x64 / glibc | Node 22, 24, 26 |
+| JavaScript check | `macos-15` | arm64 | Node 22, 24, 26 |
+| JavaScript check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 22, 24, 26 |
+| Native check | `ubuntu-latest` | x64 / glibc | Node 24, Bun 1.4.2 |
+| Native check (forced no-openat2) | `ubuntu-latest` | x64 / glibc | Node 24 |
+| Native check | `ubuntu-24.04-arm` | arm64 / glibc | Node 24, Bun 1.4.2 |
+| Native check | `macos-15` | arm64 | Node 24, Bun 1.4.2 |
+| Native check | `macos-15-intel` | x64 | Node 24, Bun 1.4.2 |
+| Native check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 24, Bun 1.4.2 |
+| Native check | `windows-2022` (standard hosted) | x64 | Node 24, Bun 1.4.2 |
+| Native check (Alpine 3.24) | `ubuntu-latest` | x64 / musl | Node 24 |
+| Native check (Alpine 3.24) | `ubuntu-24.04-arm` | arm64 / musl | Node 24 |
+| GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-latest` | x64 / glibc | Node 24 |
+| GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-24.04-arm` | arm64 / glibc | Node 24 |
+| Bundled package smoke | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22, 24 |
+| Coverage | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22 |
+
+Both musl lanes also run root-only package smoke with the real host binding.
+The seven-target source build matrix still runs on release tags. The smoke writes manager versions,
 cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
 
 ## Docs

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

@@ -74,6 +74,8 @@ Native Windows byte copies can store large zero-filled chunks as sparse ranges w
 
 The ReFS backend rejects files with alternate data streams and unsupported reparse-point types instead of silently losing their contents. Symbolic links and junctions are preserved.
 
+Failed ReFS clones attempt to remove their partial output through the retained directory handles. On Windows versions that reject the ignore-readonly deletion flag, clone rollback retries without that flag so ordinary output can be removed. It never clears readonly attributes: readonly output can remain, and the original clone error includes the cleanup failure. Other processes retaining output handles can delay deletion beyond settlement; a failed call does not guarantee an absent destination.
+
 XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
 
 `readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.

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

@@ -436,3 +436,10 @@ owning product boundary.
 - [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
 - [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
 - [Errors](errors.md) — typed operational failure handling.
+
+## Existing Windows file retirement
+
+[`retainFileInDirectory`](retained-file.md) describes identity-bound native
+disposition and resource settlement separately from persistence. Its result is
+always `persistence: "not-proven"`; neither accepted disposition nor observed
+namespace absence is a directory/volume barrier or an application commit.

package/node_modules/@openclaw/fs-safe/docs/file-store.md

@@ -101,6 +101,11 @@ such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
 as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
 Windows rejects that spelling as stream syntax.
 
+Keys such as `~` and `~/state.json` name literal entries inside the store; they
+do not expand the user's home directory. Reads, writes, removal, and pruning
+all use that literal identity. The `Root` returned by `root()` retains its own
+home-expansion behavior.
+
 Validation retains each method's operation order. Async reads, `exists`, and
 `remove` open the root first: if the root is missing, strict methods report
 `not-found` and `readTextIfExists` / `readJsonIfExists` return `null`, even for an

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

@@ -119,7 +119,13 @@ publication failure preserves the existing destination and source link; ordinary
 failure cleanup removes the staging directory.
 
 Cross-device directory moves build a copy manifest and check it during source
-cleanup. Source changes can leave the published destination and some or all
+cleanup. Directory creation keeps the source mode subject to the guest's umask;
+mode `000` is not replaced with a default. A top-level mode-000 directory uses
+owner-only staging until publication, then restores zero through its retained
+descriptor. Reading a mode-000 source still requires sufficient OS privileges;
+the guest does not change source permissions to gain access. A permission error
+after publication preserves the source and published copy for reconciliation.
+Source changes can leave the published destination and some or all
 of the source. Regular-file and symlink move fallbacks unlink the source
 pathname after publication; they do not perform the directory manifest's
 identity checks. Directory cleanup also has check-to-unlink race windows.

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

@@ -65,6 +65,7 @@ await fs.remove("notes/archive/today.txt");
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
+| [`watch`](watch.md) | Guarded filesystem observation with advisory native hints and polling. |
 | [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
 | [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
 | [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |