@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/README.md

@@ -45,7 +45,7 @@ The same idea has landed in other languages. Go [added `os.Root` and `OpenInRoot
 | `path.resolve().startsWith()` | string check only | – | – | – | – |
 | [`write-file-atomic`](https://www.npmjs.com/package/write-file-atomic) | – | ✓ | – | – | – |
 | Go [`os.Root`](https://go.dev/blog/osroot) / Rust [`cap-std`](https://github.com/bytecodealliance/cap-std) | ✓ | platform | ✓ | ✓ | – |
-| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux atomic; others best-effort** | **✓ (ZIP/TAR; native zstd/bzip2)** |
+| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux atomic; others best-effort** | **✓ (ZIP/TAR/gzip/zstd/bzip2)** |
 
 ## Not a sandbox
 
@@ -57,7 +57,9 @@ This is a **library-level guardrail**, not OS-level isolation. It does not repla
 pnpm add @openclaw/fs-safe
 ```
 
-Node 22 or newer. Core root/path/json/temp helpers avoid framework dependencies. With all optional dependencies omitted, public subpaths remain safe to import and non-archive fallback-capable operations work in `auto` or `off`. Native-only features remain unavailable, and operations needing the binding in `require` mode fail with `helper-unavailable`. TAR/gzip fallback uses the bundled WASM build of the same Rust parser as native and works with optional dependencies omitted. ZIP fallback still needs optional `jszip`. See the [0.6 migration guide](docs/migrating-to-0.6.md).
+Node 22 or newer. Core root/path/json/temp helpers avoid framework dependencies. With all optional dependencies omitted, public subpaths remain safe to import and fallback-capable operations work in `auto` or `off`. Native-only features, including no-clobber `Root.move()` and [`private: true` creation on macOS](docs/creation.md#permission-options), remain unavailable and fail with `helper-unavailable`. TAR, gzip, zstd, and bzip2 extraction and bounded entry reads use the same Rust TAR parser through bundled WASM when native support is disabled or absent. Zstd/bzip2 codecs are bundled too; gzip uses Node's built-in decoder. ZIP fallback still needs optional `jszip`. See the [0.6 migration guide](docs/migrating-to-0.6.md).
+
+Bun 1.4.2 is also supported with the [Bun runtime requirements](docs/install.md#bun-runtime), including the matching Rust addon on macOS and Linux. JIT-disabled Bun works too.
 
 The package installs one prebuilt native binding for the current supported target. It
 supplies fd-relative and atomic no-replace primitives that Node does not expose
@@ -68,7 +70,7 @@ environment policy:
 import { configureFsSafeNative } from "@openclaw/fs-safe";
 
 configureFsSafeNative({ mode: "auto" });    // default: native when available
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "off" });     // disable the addon; use supported fallbacks
 configureFsSafeNative({ mode: "require" }); // fail closed if the binding is unavailable
 ```
 
@@ -131,8 +133,18 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
+Use `remove(path, { recursive: true, maxEntries: 20_000, maxDepth: 32 })` for
+bounded tree cleanup. It streams directory entries, checks mutation authority
+before every removal, and supports cancellation. See [removal options and partial
+failure semantics](docs/writing.md).
+
 `root()` takes the trusted directory; relative paths in subsequent calls are resolved against it. Defaults you pass to `root()` apply to every call below; per-call options override them.
 
+`copyIn()` also accepts `{ root: sourceRoot, relativePath }`, `overwrite: false`,
+and `clone: "auto"` for guarded, exclusive file copies with optional native
+copy-on-write acceleration. Byte limits, cancellation, and publication receipts
+are described in the [Root copy contract](docs/root.md#writes).
+
 When you need metadata or a `FileHandle`:
 
 ```ts
@@ -146,7 +158,41 @@ const opened = await fs.open("notes/today.txt");
 await fs.create("notes/README.md", "seed\n"); // throws if it already exists
 ```
 
-`write()` replaces file contents by default; pass `{ overwrite: false }` or use `create()` when an existing file should be an error. `move()` defaults to no clobber because it can otherwise delete an unrelated target while also consuming the source. Pass `{ overwrite: true }` when replacing the target is intended.
+Use `private: true` on `mkdir()`, `ensureRoot()`, `create()`, or `createJson()`
+for private creation. On macOS, this requires native ACL inspection before
+creating parents or stages and verifies owner-only permissions with no ACL
+before writing payload bytes. Native `off` or a missing ACL capability rejects
+with `helper-unavailable`; nonprivate creation is unchanged. See the
+[creation contract](docs/creation.md#permission-options) for parent ACL handling
+and platform support.
+
+Pass `{ atomic: true }` to buffered `create()` or `createJson()` to keep the
+destination absent until complete content is ready, including with native support
+disabled. The JavaScript fallback requires hardlinks and never downgrades to a
+partial visible file. Omitted or `false` retains the existing buffered behavior.
+Atomic visibility is separate from the existing `durable` synchronization policy.
+Use `durable: "file"` on `create()` or `createJson()` when file-flush errors,
+including `EPERM`, must propagate. It combines with `atomic: true` without
+requiring strict parent-directory synchronization.
+
+`create()` also accepts an `AsyncIterable<Uint8Array>` for large or incrementally
+produced files. Streamed creates keep the destination absent until all chunks
+are written, support `maxBytes` and `signal`, and recheck mutation authority
+before writes and publication. See [streamed creation](docs/writing.md#streamed-creation)
+for producer ownership and cancellation semantics.
+
+`write()` replaces file contents by default; pass `{ overwrite: false }` or use `create()` when an existing file should be an error. `move()` defaults to no clobber because it can otherwise delete an unrelated target while also consuming the source. No-clobber moves require the native helper so the collision decision and rename are one descriptor-relative operation; they fail with `helper-unavailable` rather than falling back to a replacing rename. Pass `{ overwrite: true }` when replacing the target is intended.
+
+Mutating methods accept `assertBeforeMutation: () => void` for live lease or
+cancellation checks immediately before filesystem dispatch. Root defaults and
+per-call checks compose; cleanup and already-dispatched work still settle.
+See [live mutation authority](docs/root.md#live-mutation-authority) for the exact
+scope, including raw writable handles and lock bookkeeping.
+For workspaces with directory aliases, use `symlinks: "follow-parents-within-root"`
+on reads and `mutationSymlinks: "follow-parents-within-root"` on mutations or root
+defaults. Contained parent symlinks are resolved by the library, while a final
+symlink is rejected. Read policy and mutation policy are separate; omitting
+`mutationSymlinks` preserves the existing mutation behavior. See [root policies](docs/root.md#defaults-vs-per-call-options).
 
 Use `ensureRoot()` when a computed relative directory target resolves to the root itself (`""` or `"."`) and you want the operation to be accepted. `root()` still requires the trusted root directory to already exist.
 
@@ -204,7 +250,7 @@ const locked = await root("/srv/workspace", {
 await locked.write(".env", "token"); // FsSafeError code "denied-path"
 ```
 
-`stat()`, `exists()`, and `list()` are boundary-checked, but they cannot pin a later operation to the same filesystem object. Use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` for operation-local identity checks, and inspect `containment` when the platform distinction matters.
+`stat()`, `exists()`, `list()`, and `entries()` check the exact selected objects while collecting their advisory results, but they cannot pin a later operation to the same filesystem object. Use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()` for operation-local identity checks, and inspect `containment` when the platform distinction matters.
 
 ## Subpaths
 
@@ -223,17 +269,19 @@ contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are
 | `@openclaw/fs-safe/store` | `fileStore`, `fileStoreSync`, and `jsonStore` |
 | `@openclaw/fs-safe/secret` | sync/async strict and try-style secret reads, atomic replace, and create-only secret writes |
 | `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `replaceFileAtomicSync`, `replaceDirectoryAtomic`, `movePathWithCopyFallback` |
-| `@openclaw/fs-safe/durability` | pinned directory identities, strict directory sync, durable nested-directory creation, exclusive publication, streaming SHA-256, provenance receipts, and sync-failure policy |
+| `@openclaw/fs-safe/durability` | pinned directory identities, strict directory sync, durable nested-directory creation, exclusive publication, streaming and synchronous SHA-256, provenance receipts, and sync-failure policy |
 | `@openclaw/fs-safe/temp` | `tempWorkspace`, `tempWorkspaceSync`, `withTempWorkspace`, `resolveSecureTempRoot` |
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
 | `@openclaw/fs-safe/file-lock` | async/sync sidecar locks, root-bounded sidecars, ownership verification, and stale policy |
 | `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection, raw owner/ACE facts, private-directory creation, and remediation helpers |
 | `@openclaw/fs-safe/walk` | budget-bounded directory walking with symlink policy, filters, and truncation accounting; not root-bounded |
-| `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, native gzip/zstd/bzip2, and bounded entry reads |
-| `@openclaw/fs-safe/advanced` | lower-level composition helpers such as path scopes, root-file open, bounded descriptor reads, install paths, filename sanitizing, temp-file targets, sibling-temp writes, local-root readers, regular-file helpers, `pathExists`, and `withTimeout`; less stable than focused public subpaths |
+| `@openclaw/fs-safe/copy` | directory copying with `clone: "auto"`, `"always"`, or `"never"`; native APFS, Btrfs, ReFS, XFS, and ZFS cloning, portable byte copying, and clone metadata; see [directory copying](docs/copy.md) |
+| `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, gzip/zstd/bzip2 support, and bounded entry reads |
+| `@openclaw/fs-safe/advanced` | lower-level composition helpers such as path scopes, root-file open, bounded descriptor reads, [borrowed-handle and descriptor copying](docs/copy.md#borrowed-filehandle-transfers), [complete byte-window writes](docs/advanced.md#borrowed-handle-writes), [exact directory identity](docs/directory-identity.md), [case probing](docs/path-case.md), [suffix-alias probing](docs/path-suffix-aliases.md), [in-place writes](docs/in-place-write.md), [versioned install-ID encoding](docs/install-path.md#safepathsegmenthashedv2), filename sanitizing, temp-file targets, sibling-temp writes, local-root readers, regular-file helpers, `pathExists`, and `withTimeout`; less stable than focused public subpaths |
 | `@openclaw/fs-safe/errors` | `FsSafeError`, closed codes/categories, causes, and operation-specific details receipts |
 | `@openclaw/fs-safe/types` | shared types: `DirEntry`, `PathStat`, … |
 | `@openclaw/fs-safe/test-hooks` | hooks the test suite uses to inject races; registration requires `NODE_ENV=test` or `VITEST=true` |
+| `@openclaw/fs-safe/guest` | Python source and exit constants for caller-launched filesystem operations in Linux/macOS guests without Node; see the [guest protocol and trust boundary](docs/guest.md) |
 
 ## Failure semantics in the name
 
@@ -294,7 +342,7 @@ original directory on Linux/macOS and requires native support for this operation
 It offers atomic replace/no-replace publication, not expected-inode replacement
 or a crash-durability promise; application checks and coordination remain yours.
 
-`replaceFileAtomic()` writes a sibling temp file, applies its exact mode through the still-open descriptor, optionally fsyncs it, and renames it over the destination. It never follows the published destination path to set file permissions. Mode preservation, pinned-destination hardlink rejection, rename retry / copy fallback on `EPERM`, bounded original-content restoration after a torn fallback, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved. Its optional synchronous `assertBeforeMutation` hook rechecks caller authority before renames and each source removal; `onDestinationPublished` reports an exact bigint destination identity before later checks or cleanup can fail. See [mutation authority and publication receipts](docs/atomic.md#mutation-authority-and-publication-receipts).
+`replaceFileAtomic()` writes a sibling temp file, applies its exact mode through the still-open descriptor, optionally fsyncs it, and renames it over the destination. It never follows the published destination path to set file permissions. Mode preservation inherits only rwx bits from an existing non-symlink regular file; special bits, ownership, ACLs, and extended attributes are not copied. Pinned-destination hardlink rejection, rename retry / copy fallback on `EPERM`, bounded original-content restoration after a torn fallback, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved. Its optional synchronous `assertBeforeMutation` hook rechecks caller authority before renames and each source removal; `onDestinationPublished` reports an exact bigint destination identity before later checks or cleanup can fail. See [mutation authority and publication receipts](docs/atomic.md#mutation-authority-and-publication-receipts).
 
 ```ts
 import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
@@ -335,6 +383,12 @@ fsyncs the completed file, and atomically renames it over the target. Choose it
 when the destination directory is itself the writable boundary and atomic
 replacement matters.
 
+For sibling producers that can leave partial output before throwing, opt in to
+`producerIsolation: "private-directory"`. The callback writes inside an owned
+private workspace on the target filesystem, allowing cleanup after producer
+failure while preserving sibling publication behavior. See [external outputs](docs/output.md)
+for the identity checks and cleanup limits.
+
 Use it when the final filename is known before the external writer runs. If the
 filename depends on sniffing the produced bytes, write to a private temp
 workspace first, then finalize through the normal root APIs after validation.
@@ -354,8 +408,8 @@ const store = files.json("settings.json", { lock: true });
 await store.updateOr({ enabled: false }, (current) => ({ ...current, enabled: true }));
 ```
 
-`jsonStore({ filePath })` is the absolute-path convenience wrapper for the same
-primitive.
+`jsonStore({ filePath })` is the single-path convenience wrapper for the same
+primitive and exposes its resolved absolute path.
 
 Use `update()` when missing state is part of your model; use `updateOr()` for
 the common merge-into-defaults case. Standalone helpers use options bags
@@ -392,7 +446,9 @@ await media.pruneExpired({ ttlMs: 10 * 60 * 1000, recursive: true });
 The `store` subpath also includes durable JSON queue helpers for the common
 "one JSON file per work item" pattern: atomic entry writes, pending-entry loads,
 acknowledgement via `.delivered` markers, failed-entry moves, and stale temp
-cleanup. Retry, dedupe, and transport semantics stay with the caller.
+cleanup. On Windows, every independently supplied queue path rejects NTFS
+alternate-stream and directory-index namespace spellings before reads, locks,
+or mutations. Retry, dedupe, and transport semantics stay with the caller.
 
 `tempWorkspace()` exposes `write()`, `writeText()`, `writeJson()`, `copyIn()`, and `read()` for
 single-file scratch workflows without hand-rolled path joins, plus a `store: FileStore` view of
@@ -401,6 +457,9 @@ Compatible creation and cleanup remain available without native support.
 Set `cleanupSafety: "require-bounded"` to require collision-safe quarantine and
 descriptor-bounded recursive cleanup before creating a child. See the
 [temp workspace contract](docs/temp.md).
+On POSIX, bounded cleanup requires owner read and search in the final `dirMode`
+(`0o500`); restrictive modes select compatible fallback or reject `require-bounded`
+before child creation.
 Linux bounded cleanup requires the exact `openat2`/`RESOLVE_NO_XDEV` capability
 at runtime; compatible mode falls back when unavailable, while `require-bounded`
 rejects before child creation.
@@ -417,13 +476,27 @@ await fs.promises.writeFile(target.path, bytes);
 const checksumPath = target.file("payload.sha256");
 ```
 
+## Exact file comparison
+
+For exact comparison of already-open files, use
+[`sameFileContentsSync()`](docs/file-contents.md) from `advanced`. It compares
+bytes through both EOFs with bounded memory and preserves the borrowed
+descriptors' positions and ownership.
+
 ## Secure absolute file reads
 
 Use `readSecureFile()` when the caller gives you an absolute credential path
 instead of a root-relative workspace path. It opens the file first, validates the
 same handle it will read from, checks trusted directories, owner, POSIX mode or
 Windows ACLs, hardlink count, size, and optional timeout, then reads through the
-pinned handle.
+pinned handle. On Windows, both the bytes and the owner/DACL facts come from that
+handle. In native `auto` or `off` mode, a packaged, readable PowerShell script can
+inspect that borrowed handle when the native capability is unavailable, subject
+to the [Windows security fallback prerequisites](docs/install.md#windows-security-fallback).
+It emits one fallback warning per process for secure reads and adds PowerShell
+startup and compilation overhead per call. Native `require` remains strict, and
+native operation failures are terminal. Neither route reopens the pathname to
+inspect its ACL.
 
 ```ts
 import { readSecureFile } from "@openclaw/fs-safe/secure-file";
@@ -441,6 +514,17 @@ flows where a warning is preferable to refusing the file.
 
 ## Directory walking
 
+[`Root.entries()`](docs/entries.md) observes one directory without descending or
+following child symlinks. It streams in filesystem order by default and supports
+cancellation, entry limits that throw on overflow, and bounded sorted-name
+collection. Use it when the caller owns traversal or symlink validation:
+
+```ts
+for await (const entry of fs.entries("plugins", { maxEntries: 1_000 })) {
+  console.log(entry.name, entry.isSymbolicLink);
+}
+```
+
 `walkDirectory()` and `walkDirectorySync()` replace ad-hoc recursive
 `readdir()` loops with entry and depth budgets, a symlink policy, and stable
 relative paths.
@@ -462,12 +546,18 @@ for (const file of scan.entries) {
 
 Check `scan.truncated` before treating the result as complete, and `scan.failedDirs` to tell an incomplete scan (a directory that could not be read) from an empty one before pruning state from the listing.
 
+`walkDirectory()` accepts asynchronous `include` and `descend` callbacks through `AsyncWalkDirectoryOptions`, so a marker lookup can prune a directory before its children are read. Decisions remain serial and retain the options object as their `this` receiver; `walkDirectorySync()` and its options remain synchronous. See [Directory walking](docs/walk.md) for callback timing, JavaScript result compatibility, and error handling.
+
 For caller-controlled paths, `Root.walk()` is the root-bounded async iterator.
 It supports entry/depth budgets, in-root symlink following, cancellation, and a
 truncation marker (or typed error) when a budget is reached. Its `entryFilter`
-can return `"skip-subtree"` to prune a directory, and
-`onDirectoryError: "skip-and-report"` yields typed `"directory-error"` markers
-while preserving entries from readable subtrees.
+accepts `"include"`, `"skip"`, or `"skip-subtree"`, directly or through a Promise.
+After an awaited decision resolves, the walk rechecks cancellation and the
+current listing directory and Root identities before using it. Pending callbacks
+settle before cancellation or iterator disposal completes. Callback failures
+reject the walk. `onDirectoryError: "skip-and-report"` yields typed `"directory-error"` markers
+for directory read or identity-check failures while preserving entries from
+readable subtrees.
 
 ## Archive extraction
 

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

@@ -30,4 +30,3 @@ export declare function resolveAbsolutePathForRead(filePath: string, options?: {
 export declare function resolveAbsolutePathForWrite(filePath: string, options?: {
     symlinks?: AbsolutePathSymlinkPolicy;
 }): Promise<ResolvedWritableAbsolutePath>;
-//# sourceMappingURL=absolute-path.d.ts.map

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

@@ -4,7 +4,9 @@ import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { pathExists } from "./fs.js";
+import { realpathSync } from "./realpath.js";
 import { resolveRootPath } from "./root-path.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 function resolveSymlinkPolicy(policy) {
     if (policy === undefined)
         return "reject";
@@ -67,7 +69,7 @@ async function directoryGuardFailure(err, dir, scopeLabel) {
         return { ok: false, code: err.code, error: err };
     }
     try {
-        const stat = fsSync.lstatSync(dir);
+        const stat = fsSync.lstatSync(pathForWindowsFilesystem(dir));
         const failure = classifyExistingDirectorySegment(stat, scopeLabel);
         if (failure) {
             return failure;
@@ -87,7 +89,7 @@ async function resolveTrustedDirectoryPrefix(targetPath, scopeLabel) {
     let current = root;
     let currentStat;
     try {
-        currentStat = fsSync.lstatSync(current);
+        currentStat = fsSync.lstatSync(pathForWindowsFilesystem(current));
     }
     catch (err) {
         const failure = classifyDirectoryLookupError(err, scopeLabel);
@@ -111,7 +113,7 @@ async function resolveTrustedDirectoryPrefix(targetPath, scopeLabel) {
         }
         const next = path.join(current, segment);
         try {
-            const nextStat = fsSync.lstatSync(next);
+            const nextStat = fsSync.lstatSync(pathForWindowsFilesystem(next));
             const segmentFailure = classifyExistingDirectorySegment(nextStat, scopeLabel);
             if (segmentFailure) {
                 return segmentFailure;
@@ -144,19 +146,22 @@ export function assertAbsolutePathInput(filePath) {
     if (filePath.includes("\0")) {
         throw new FsSafeError("invalid-path", "path must not contain NUL bytes");
     }
+    assertNoWindowsPathAlias(filePath);
     if (!path.isAbsolute(filePath)) {
         throw new FsSafeError("invalid-path", "path must be absolute");
     }
-    return path.normalize(filePath);
+    const normalized = path.normalize(filePath);
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
 }
 export async function findExistingAncestor(filePath) {
-    return (await findExistingAncestorWithStat(filePath))?.path ?? null;
-}
-async function findExistingAncestorWithStat(filePath) {
-    let current = path.resolve(filePath);
+    assertNoWindowsPathAlias(filePath);
+    let current = resolvePathPreservingWindowsRoot(filePath);
+    assertNoWindowsPathAlias(current);
     while (true) {
         try {
-            return { path: current, stat: fsSync.lstatSync(current) };
+            fsSync.lstatSync(pathForWindowsFilesystem(current));
+            return current;
         }
         catch (err) {
             if (err.code !== "ENOENT") {
@@ -245,26 +250,37 @@ export async function ensureAbsoluteDirectory(dirPath, options = {}) {
     return { ok: true, path: targetPath };
 }
 export async function canonicalPathFromExistingAncestor(filePath) {
+    assertNoWindowsPathAlias(filePath);
     const ancestor = await findExistingAncestor(filePath);
     if (!ancestor) {
-        return path.resolve(filePath);
+        const resolved = resolvePathPreservingWindowsRoot(filePath);
+        assertNoWindowsPathAlias(resolved);
+        return resolved;
     }
     let canonicalAncestor = ancestor;
+    let resolvedAncestor;
     try {
-        canonicalAncestor = fsSync.realpathSync.native(ancestor);
+        resolvedAncestor = realpathSync.native(pathForWindowsFilesystem(ancestor));
     }
     catch {
         // Keep lexical path when the existing ancestor cannot be canonicalized.
     }
+    if (resolvedAncestor !== undefined) {
+        assertNoWindowsPathAlias(resolvedAncestor);
+        canonicalAncestor = resolvedAncestor;
+    }
     const relative = path.relative(ancestor, filePath);
-    return relative ? path.join(canonicalAncestor, relative) : canonicalAncestor;
+    const canonicalPath = relative ? path.join(canonicalAncestor, relative) : canonicalAncestor;
+    assertNoWindowsPathAlias(canonicalPath);
+    return canonicalPath;
 }
 export async function resolveAbsolutePathForRead(filePath, options = {}) {
     const symlinks = resolveSymlinkPolicy(options.symlinks);
     const normalized = assertAbsolutePathInput(filePath);
     let canonicalPath;
     try {
-        canonicalPath = fsSync.realpathSync.native(normalized);
+        canonicalPath = realpathSync.native(pathForWindowsFilesystem(normalized));
+        assertNoWindowsPathAlias(canonicalPath);
     }
     catch (err) {
         if (err.code === "ENOENT") {
@@ -281,7 +297,7 @@ export async function resolveAbsolutePathForWrite(filePath, options = {}) {
     const symlinks = resolveSymlinkPolicy(options.symlinks);
     const normalized = assertAbsolutePathInput(filePath);
     const parentDir = path.dirname(normalized);
-    const parentExists = await pathExists(parentDir);
+    const parentExists = await pathExists(pathForWindowsFilesystem(parentDir));
     if (symlinks === "reject") {
         const filesystemRoot = path.parse(normalized).root;
         await resolveRootPath({

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

@@ -1,6 +1,17 @@
 export { createAsyncLock } from "./async-lock.js";
-export { stageFileInDirectory, type StagedFile, type StagedFileReceipt, type PublishedFileReceipt, type StagedFilePublication, type StagedFileCleanupReceipt, type StagedFileFailureDetails, } from "./native-staged-file.js";
+export { createDirectory, createDirectorySync, createFileSync, type CreateDirectoryOptions, type CreateFileOptions, type OwnedFileDescriptorSync, } from "./create.js";
+export { copyFileHandle, copyFileDescriptorSync, type CopyFileHandleOptions } from "./file-handle-transfer.js";
+export { sameFileContentsSync, type SameFileContentsOptions } from "./file-contents.js";
+export { overwriteFileHandle, type OverwriteFileHandleOptions } from "./overwrite-file-handle.js";
+export { probePathCaseInsensitiveSync, type ProbePathCaseOptions } from "./path-case.js";
+export { resolvePathPrefixSync, type ResolvedPathPrefix } from "./path-prefix.js";
+export { probePathSuffixAliasesSync, type ProbePathSuffixAliasesOptions } from "./path-suffix-aliases.js";
+export { readDirectoryIdentity, assertDirectoryIdentitySync, type DirectoryIdentity, } from "./directory-guard.js";
+export { stageFileInDirectory, } from "./native-staged-file.js";
+export type { StagedFile, StagedFileReceipt, PublishedFileReceipt, StagedFilePublication, StagedFileCleanupReceipt, StagedFileFailureDetails, } from "./staged-file-types.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
+export { readFileWindowFully, readFileWindowFullySync, type ReadFileWindowOptions, } from "./positional-read.js";
+export { writeFileWindowFully, type WriteFileWindowOptions } from "./write-file-handle.js";
 export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, type UnsafeDeviceReadPathMatch, type UnsafeDeviceReadPathOptions, type UnsafeDeviceReadPathReason, } from "./device-path.js";
 export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, type AbsolutePathSymlinkPolicy, type EnsureAbsoluteDirectoryOptions, type EnsureAbsoluteDirectoryResult, type ResolvedAbsolutePath, type ResolvedWritableAbsolutePath, } from "./absolute-path.js";
 export { sameFileIdentity, type FileIdentityStat } from "./file-identity.js";
@@ -14,7 +25,7 @@ export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICI
 export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, type OpenRootFileParams, type OpenRootFileSyncParams, type RootFileOpenFailure, type RootFileOpenFailureReason, type RootFileOpenResult, } from "./root-file.js";
 export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, type ResolvedRootPath, type RootPathAliasPolicy, } from "./root-path.js";
 export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, type PathScope, type PathScopeOptions, type PathScopeResolveOptions, } from "./root-paths.js";
-export { safeDirName, safePathSegmentHashed, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
+export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
 export { assertNoSymlinkParents, assertNoSymlinkParentsSync, type AssertNoSymlinkParentsOptions, } from "./symlink-parents.js";
 export { movePathToTrash, type MovePathToTrashOptions } from "./trash.js";
 export { withTimeout } from "./timing.js";
@@ -23,4 +34,3 @@ export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularF
 export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
 export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
-//# sourceMappingURL=advanced.d.ts.map

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

@@ -2,8 +2,18 @@
 // public subpaths; prefer root/json/store/temp/archive unless you are building a
 // higher-level primitive.
 export { createAsyncLock } from "./async-lock.js";
+export { createDirectory, createDirectorySync, createFileSync, } from "./create.js";
+export { copyFileHandle, copyFileDescriptorSync } from "./file-handle-transfer.js";
+export { sameFileContentsSync } from "./file-contents.js";
+export { overwriteFileHandle } from "./overwrite-file-handle.js";
+export { probePathCaseInsensitiveSync } from "./path-case.js";
+export { resolvePathPrefixSync } from "./path-prefix.js";
+export { probePathSuffixAliasesSync } from "./path-suffix-aliases.js";
+export { readDirectoryIdentity, assertDirectoryIdentitySync, } from "./directory-guard.js";
 export { stageFileInDirectory, } from "./native-staged-file.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
+export { readFileWindowFully, readFileWindowFullySync, } from "./positional-read.js";
+export { writeFileWindowFully } from "./write-file-handle.js";
 export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, } from "./device-path.js";
 export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, } from "./absolute-path.js";
 export { sameFileIdentity } from "./file-identity.js";
@@ -17,7 +27,7 @@ export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICI
 export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, } from "./root-file.js";
 export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, } from "./root-path.js";
 export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, } from "./root-paths.js";
-export { safeDirName, safePathSegmentHashed, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
+export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";
 export { assertNoSymlinkParents, assertNoSymlinkParentsSync, } from "./symlink-parents.js";
 export { movePathToTrash } from "./trash.js";
 export { withTimeout } from "./timing.js";

package/node_modules/@openclaw/fs-safe/dist/archive-crc32.d.ts

@@ -1,2 +1 @@
 export declare function updateCrc32(previous: number, buffer: Buffer): number;
-//# sourceMappingURL=archive-crc32.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/archive-crc32.js

@@ -1,4 +1,7 @@
-const CRC32_TABLE = Array.from({ length: 256 }, (_, index) => {
+import zlib from "node:zlib";
+const nativeCrc32 = zlib.crc32;
+// Node 22.0–22.1 are supported but predate zlib.crc32.
+const CRC32_TABLE = nativeCrc32 ? undefined : Array.from({ length: 256 }, (_, index) => {
     let value = index;
     for (let bit = 0; bit < 8; bit += 1) {
         value = (value & 1) !== 0 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
@@ -6,6 +9,8 @@ const CRC32_TABLE = Array.from({ length: 256 }, (_, index) => {
     return value >>> 0;
 });
 export function updateCrc32(previous, buffer) {
+    if (nativeCrc32)
+        return nativeCrc32(buffer, previous >>> 0);
     let crc = previous ^ -1;
     for (const byte of buffer) {
         crc = (crc >>> 8) ^ (CRC32_TABLE[(crc ^ byte) & 0xff] ?? 0);

package/node_modules/@openclaw/fs-safe/dist/archive-deadline.d.ts

@@ -9,4 +9,3 @@ export declare function ownExtractionDestinationMutation<T>(deadline: Extraction
 export declare function createPipelineTimeoutError(err: unknown, deadline: ExtractionDeadline): unknown;
 export declare function waitForDeadline<T>(promise: Promise<T>, deadline: ExtractionDeadline): Promise<T>;
 export declare function withExtractionDeadline<T>(timeoutMs: number, label: string, run: (deadline: ExtractionDeadline) => Promise<T>): Promise<T>;
-//# sourceMappingURL=archive-deadline.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/archive-deadline.js

@@ -1,3 +1,4 @@
+import { scheduleTimeout } from "./timing.js";
 export async function ownExtractionDestinationMutation(deadline, run) {
     return deadline ? await deadline.ownDestinationMutation(run) : await run();
 }
@@ -17,11 +18,13 @@ export function createPipelineTimeoutError(err, deadline) {
     return err;
 }
 export async function waitForDeadline(promise, deadline) {
+    // An elapsed synchronous check must not orphan a later operation rejection.
+    void promise.catch(() => undefined);
     deadline.check();
     if (deadline.signal.aborted) {
         throw deadlineReason(deadline);
     }
-    return await Promise.race([
+    const result = await Promise.race([
         promise,
         new Promise((_, reject) => {
             const abort = () => reject(deadlineReason(deadline));
@@ -32,21 +35,26 @@ export async function waitForDeadline(promise, deadline) {
             promise.then(cleanup, cleanup);
         }),
     ]);
+    deadline.check();
+    return result;
 }
 function createDestinationMutationOwner(check) {
     const active = new Set();
     return {
         ownDestinationMutation: async (run) => {
             check();
-            const operation = Promise.resolve().then(run);
-            const tracked = operation.then(() => undefined, () => undefined);
-            active.add(tracked);
-            void tracked.finally(() => active.delete(tracked));
-            return await operation;
+            const operation = Promise.resolve().then(() => { check(); return run(); });
+            active.add(operation);
+            try {
+                return await operation;
+            }
+            finally {
+                active.delete(operation);
+            }
         },
         waitForDestinationMutations: async () => {
             while (active.size > 0) {
-                await Promise.all(active);
+                await Promise.allSettled(active);
             }
         },
     };
@@ -54,37 +62,27 @@ function createDestinationMutationOwner(check) {
 function createExtractionDeadline(timeoutMs, label) {
     const controller = new AbortController();
     const timeoutError = new Error(`${label} timed out after ${timeoutMs}ms`);
+    const enabled = Number.isFinite(timeoutMs) && timeoutMs > 0;
+    const startedAt = enabled ? performance.now() : 0;
     const check = () => {
+        if (enabled && !controller.signal.aborted && performance.now() - startedAt >= timeoutMs) {
+            controller.abort(timeoutError);
+        }
         if (controller.signal.aborted) {
             throw signalReason(controller.signal, timeoutError);
         }
     };
-    const mutationOwner = createDestinationMutationOwner(check);
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-        return {
-            signal: controller.signal,
-            check,
-            ...mutationOwner,
-            dispose: () => undefined,
-        };
-    }
-    const timeoutId = setTimeout(() => {
-        controller.abort(timeoutError);
-    }, timeoutMs);
     return {
         signal: controller.signal,
         check,
-        ...mutationOwner,
-        dispose: () => {
-            clearTimeout(timeoutId);
-        },
+        ...createDestinationMutationOwner(check),
+        dispose: enabled ? scheduleTimeout(() => controller.abort(timeoutError), timeoutMs) : () => undefined,
     };
 }
 export async function withExtractionDeadline(timeoutMs, label, run) {
     const deadline = createExtractionDeadline(timeoutMs, label);
-    const operation = Promise.resolve().then(async () => await run(deadline));
+    const operation = Promise.resolve().then(() => { deadline.check(); return run(deadline); });
     try {
-        deadline.check();
         try {
             return await waitForDeadline(operation, deadline);
         }

package/node_modules/@openclaw/fs-safe/dist/archive-durability.d.ts

@@ -0,0 +1,23 @@
+import { type ExtractionDeadline } from "./archive-deadline.js";
+import { type ArchiveDirectoryGuard } from "./archive-staging.js";
+import type { PublishedWriteIdentity } from "./pinned-write-types.js";
+import type { Root } from "./root.js";
+export type ArchivePublishedFile = {
+    relativePath: string;
+    identity: PublishedWriteIdentity;
+    guards: readonly ArchiveDirectoryGuard[];
+};
+export type ArchivePublishedDirectory = {
+    guard: ArchiveDirectoryGuard;
+    parents: readonly ArchiveDirectoryGuard[];
+    mode: number;
+};
+export declare function finalizeArchivePublication(params: {
+    targetRoot: Root;
+    destinationGuard: ArchiveDirectoryGuard;
+    sourceGuard: ArchiveDirectoryGuard;
+    files: readonly ArchivePublishedFile[];
+    directories: readonly ArchivePublishedDirectory[];
+    durable: boolean;
+    deadline?: ExtractionDeadline;
+}): Promise<void>;