@openclaw/openshell-sandbox 2026.9.3 → 2026.9.5

package/node_modules/@openclaw/fs-safe/docs/public-api.md

@@ -26,6 +26,11 @@ deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
 
 ## `path` and `advanced`
 
+`safePathSegmentHashedV2` encodes every trimmed install ID with domain-separated
+SHA-256 into a fixed lowercase segment. The legacy `safePathSegmentHashed` keeps
+its existing output but can alias distinct IDs. See [install paths](install-path.md)
+for the exact encoding and migration contract.
+
 The lexical path surface additionally exports `isNodeError`,
 `isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
 `resolveSafeRelativePath`, `splitSafeRelativePath`, and
@@ -38,6 +43,42 @@ The advanced root-file primitive exports `OpenRootFileParams`,
 `RootFileOpenFailureReason`. These are composition types for callers building
 their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
 
+`copyFileHandle` and `CopyFileHandleOptions` transfer bytes between already-open
+regular files without taking over their cursors, lifetime, or publication.
+See [borrowed-handle transfers](copy.md#borrowed-filehandle-transfers).
+
+`readDirectoryIdentity`, `assertDirectoryIdentitySync`, and `DirectoryIdentity`
+provide exact directory observations without owning a descriptor or a mutation.
+The assertion accepts an observed path and optional expected canonical path;
+see [directory identity](directory-identity.md).
+
+`overwriteFileHandle` and `OverwriteFileHandleOptions` provide in-place byte
+replacement through a borrowed regular-file handle. Its once-only `beforeWrite`
+callback admits the complete write and any required best-effort rollback after
+prefix preparation. See [in-place writes](in-place-write.md).
+
+`probePathCaseInsensitiveSync` and `ProbePathCaseOptions` are advanced exports
+for local ASCII-case observations. An unavailable answer remains `undefined`;
+the caller selects any fallback. See [path case probing](path-case.md).
+
+`resolvePathPrefixSync` and `ResolvedPathPrefix` separate a canonical existing
+path prefix from its raw unresolved suffix after physical symlink traversal.
+See [resolving path prefixes](path-prefix.md).
+
+`probePathSuffixAliasesSync` and `ProbePathSuffixAliasesOptions` compare selected
+missing relative suffixes beneath an existing directory using bounded temporary
+directory probes. The caller owns Unicode-pair policy, caching, and the fallback
+for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
+
+## Guest source
+
+`@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
+`GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE`,
+`GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE`, and
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON`. These are source and protocol
+constants; the caller launches the Python guest and owns authorization and
+transport lifetime. See the [guest protocol](guest.md).
+
 ## `json` and `store`
 
 Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
@@ -89,8 +130,10 @@ The durability surface also exports the synchronous strict
 `EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
 `PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
 `PublishFileExclusiveFailurePhase`,
-`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`, and
-`Sha256FileResult`.
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`,
+`Sha256FileSyncInput`, `Sha256FileOptions`, and `Sha256FileResult`.
+`sha256FileSync()` provides synchronous pathname or borrowed-descriptor hashing
+with the same byte-budget and digest-result contracts as `sha256File()`.
 
 ## Archives
 

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

@@ -60,7 +60,7 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
-`move()` defaults to no clobber. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
 
 ## 5. Inspect
 

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

@@ -14,6 +14,12 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 Identity and containment checks use brief synchronous metadata calls, like Node's module resolution, while file data is read asynchronously. Canonical paths retain Node's native realpath spelling, including expansion of Windows short paths.
 
+The same observation rule applies to archive extraction, copy, publication, move,
+directory modes, and supporting lock, queue, and secret-file operations. Opens,
+data transfers, durability syncs, filesystem mutations, and closes retain their
+existing asynchronous behavior. Custom filesystem adapters retain their async
+metadata interface.
+
 Regardless of shape, every read goes through the same boundary checks:
 
 1. Resolve the input lexically against the canonical real root.
@@ -21,10 +27,17 @@ Regardless of shape, every read goes through the same boundary checks:
 3. Resolve path components and reject anything that escapes the root (`outside-workspace`).
 4. Reject `..` traversal and absolute spellings when they resolve outside the root. In-root absolute spellings remain accepted; `readAbsolute` makes that intent explicit.
 5. Open with `O_NOFOLLOW` where available. Any remaining symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
-6. Compare the pre-open path identity, the open fd, and the post-open resolved path (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
+6. Compare the pre-open bigint path identity with the open fd, then perform one best-effort final admission: check the captured root identity, compare the policy-aware pathname with the fd, freshly canonicalize and re-admit that target inside the captured root, compare its exact bigint identity without following a final symlink with the fd, and check the root again. Both final pathname observations run even when their spellings match. An observed swap triggers `path-mismatch` or `outside-workspace`; a missing final path triggers `not-found`.
 7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
 8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
+The final fence closes a rejected descriptor before any Root read consumes bytes or
+`open()` hands the descriptor to its caller. It is a sequence of filesystem
+observations, not an atomic kernel pathname/open primitive, so a hostile peer can
+still race the namespace after the last observation. Standalone absolute-file
+helpers have no captured `Root` identity and do not claim this replacement-root
+fence; use a `Root` for untrusted paths.
+
 ## Read shapes
 
 ### `fs.read(rel, options?)`

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

@@ -18,7 +18,8 @@ const fs = await root("/srv/workspace", {
 function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 
 type RootDefaults = {
-  durable?: boolean;               // fsync write/create/writeJson/createJson/append; default true
+  assertBeforeMutation?: () => void; // synchronous caller authority check at mutation dispatch
+  durable?: boolean;               // fsync write/create/writeJson/createJson/append/copyIn; default true
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
@@ -26,7 +27,8 @@ type RootDefaults = {
   mode?: number;                   // file mode applied to new writes; per-call override available
   nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
   renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
-  symlinks?: "reject" | "follow-within-root"; // policy when a path component is a symlink
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // read policy
+  mutationSymlinks?: "reject" | "follow-parents-within-root"; // opt-in mutation policy
 };
 
 type DenyMutationPolicy = {
@@ -37,7 +39,9 @@ type DenyMutationPolicy = {
 
 `root()` resolves the directory through the real filesystem. A symlinked input becomes the canonical path; a non-existent root throws `FsSafeError` with code `not-found`, and malformed or non-directory roots throw `invalid-path`.
 
-`defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only, except `denyMutations`: root and per-call deny entries are merged so a call cannot clear a root-level deny.
+The root directory is pinned with exact bigint device/inode identities. A changed root rejects subsequent operations; an unknown Windows identity that remains unverifiable after bounded reinspection rejects construction with `path-mismatch`.
+
+`defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only, except `denyMutations` and `assertBeforeMutation`: deny entries are merged, and the root assertion runs before the per-call assertion. A call cannot clear either root-level restriction.
 
 Every `maxBytes` value must be a non-negative safe integer or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` explicitly disables the cap. An omitted or explicitly `undefined` per-call value preserves the configured Root default instead of clearing it.
 
@@ -60,7 +64,12 @@ fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kin
 
 `walk()` is the incremental, root-bounded recursive scan. It supports entry and
 depth budgets, cancellation, and `symlinkPolicy: "skip" |
-"follow-within-root"`. Budget exhaustion yields a `"truncated"` marker by
+"follow-within-root"`. With an entry budget, sorted walks prepare small metadata
+batches within the remaining budget; unbounded sorted walks reuse the full
+directory snapshot.
+The default `order: "sorted"` enumerates and sorts each directory's names;
+`order: "filesystem"` streams names in filesystem order for bounded work in
+wide directories. Budget exhaustion yields a `"truncated"` marker by
 default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
 Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
 `"skip-subtree"`. `"skip"` omits the current entry but still descends into a
@@ -91,7 +100,9 @@ The read methods also accept an absolute spelling that already resolves inside
 the root. `readAbsolute()` and `reader()` make that intent explicit and accept
 both the configured root spelling and its canonical real path when the Root was
 created through a directory symlink or Windows junction. An absolute path
-outside the root is still rejected.
+outside the root is still rejected. On Windows, alternate casing is accepted
+only when the differently cased Root prefix has the Root's exact directory
+identity; the operation then continues under the trusted Root spelling.
 
 ### Writes
 
@@ -103,15 +114,27 @@ fs.createJson(rel, value, options?)      // create() variant of writeJson
 fs.append(rel, data, options?)           // append text/buffer; syncs before close by default
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
-fs.move(from, to, options?)              // rename within the root; defaults to no clobber
-fs.remove(rel, options?)                 // unlink file or rmdir empty directory
+fs.move(from, to, options?)              // rename within the root; native-backed no clobber by default
+fs.remove(rel, options?)                 // unlink file, rmdir, or bounded recursive removal
 fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
 fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 ```
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
-These five methods also accept `durable?: boolean`: the per-call value overrides
+`create` also accepts `AsyncIterable<Uint8Array>` with `RootCreateStreamOptions`:
+the same path, authority, mode, and durability options, plus `maxBytes` and
+`signal`, without `encoding` or `renameIdentity`. It consumes one chunk at a
+time and publishes the completed file exclusively. The byte cap inherits an
+explicit `Root.defaults.maxBytes`; without either cap, consumption is unlimited.
+See [streamed creation](writing.md#streamed-creation) for cancellation,
+cleanup, and filesystem requirements.
+
+`append` accepts `prependNewlineIfNeeded: true` to separate text from existing
+content when neither side supplies a newline. String data uses its `encoding`
+for the newline check, including UTF-16LE; Buffer data uses a single LF byte.
+
+These five methods and `copyIn` also accept `durable?: boolean`: the per-call value overrides
 `Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
 `undefined` per-call value preserves the root default. `durable: false` keeps
 the existing publication behavior, modes, and identity checks but skips file
@@ -119,7 +142,76 @@ and parent-directory fsync calls. Use it only for reconstructible data: a crash
 may lose the write or leave the previous file. See [Writing](writing.md#write-options)
 for platform details.
 
-`copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
+`copyIn` accepts a `RootCopySource`: a trusted absolute source path or a file
+within another Root. The guarded form supplies `root` with only its `open` and
+`stat` read capabilities, plus `relativePath`:
+
+```ts
+const source = await root("/srv/templates");
+const destination = await root("/srv/workspace");
+await destination.copyIn("config/settings.json", {
+  root: source,
+  relativePath: "config/settings.json",
+}, {
+  overwrite: false,
+  clone: "auto",
+  mode: 0o600,
+  signal: AbortSignal.timeout(30_000),
+});
+```
+
+The source Root applies its read policies, including confinement and symlink
+handling. `sourceHardlinks` overrides its hardlink policy only when supplied;
+otherwise the source Root default is retained. The admitted source
+descriptor stays open through copying and source-identity verification; copying
+does not consume its current file position. Both forms enforce `maxBytes` while
+reading, including when a file grows after admission, and use bounded buffers.
+Copies have independent file data; changing either file cannot change the other.
+Set `preserveSourceMode: true` to select the mode from the admitted source
+descriptor. An explicit numeric `mode`, including `Root.defaults.mode`, takes
+precedence. By default, copying retains the existing destination-mode rules.
+The operation verifies source identity, not a coherent snapshot of concurrent
+in-place edits. Keep the source unchanged when snapshot consistency is required.
+
+`overwrite` defaults to `true`, preserving the existing replacement behavior.
+With `overwrite: false`, an existing destination produces `already-exists` and
+is never altered. Copying prepares a private sibling file before publishing its
+completed contents. Native mode uses no-replace rename. The guarded JavaScript
+fallback links the completed stage and removes its temporary name in the same
+JavaScript turn; the filesystem must support hardlinks. Other processes can
+briefly observe both names. The source is never hardlinked to the destination.
+
+`clone` chooses the file-data transfer strategy through `CopyCloneMode`, shared
+with [`copyTree`](copy.md#api). File copies default to `"never"`; tree copies
+default to `"auto"`:
+
+| Value | Behavior |
+| --- | --- |
+| `never` | Copy regular file bytes using reads and writes, without explicit cloning or copy offload. |
+| `auto` | Try native file cloning, then copy offload or ordinary byte copying when cloning is unavailable. |
+| `always` | Require native cloning; fail when the binding or filesystem cannot provide it. |
+
+Native file cloning supports APFS and supported Linux filesystems. Windows
+currently uses byte copying for `never` and `auto`; `always` fails. Clone choice
+does not change modes, durability, root confinement, or source and publication
+identity checks. The shared strategy does not replace Root's guarded regular-file
+contract with `copyTree`'s caller-owned immutable-tree and metadata contract.
+
+An already aborted `signal` prevents I/O. Cancellation during copying waits for
+admitted reads and native work to settle, then cleans only the owned unpublished
+stage. The final authority check runs before publication. Once publication has
+occurred, later cancellation or verification failure preserves the destination.
+The synchronous optional `onDestinationPublished` callback receives a frozen
+`RootCopyPublicationReceipt` containing `{ path, dev, ino }`, with exact bigint identity immediately after
+publication, before later checks can fail. Callback errors also preserve the
+published file. This receipt records an outcome; it does not authorize removing
+a file that another actor may have edited. Application recovery and cooperative
+locking remain caller-owned.
+
+Existing `copyIn` callers must account for completed destinations retained after
+a post-publication source-verification failure, even without the new options.
+Recovery must inspect current destination state rather than assume a rejected
+copy left no file.
 
 Root operations that choose a new destination reject a leading Windows
 drive-relative spelling such as `C:name` on every platform. This applies to
@@ -129,10 +221,83 @@ source)` can reject a legal POSIX basename such as `c:photo.png`; callers that
 derive portable destination names from host files must sanitize or map that
 basename first.
 
-`openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
+On Windows, every Root pathname admission also rejects NTFS alternate-data-stream
+and directory-index aliases: relative names containing `:`, or absolute names
+with a colon beyond the single rooted drive designator, fail with
+`invalid-path` before filesystem access. This includes spellings such as
+`file:stream`, `dir::$INDEX_ALLOCATION`, and `dir:$I30:$INDEX_ALLOCATION`.
+Rooted drive, UNC, and extended-drive paths keep their existing handling, and
+the separate device/network policies remain in force. Ordinary colon-bearing
+names remain valid on POSIX where the operation's existing drive-relative rule
+does not otherwise reject them.
+
+`openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Before truncation or handle return, descriptor and pathname identities are compared with lossless bigint metadata; persistently unknown Windows identities fail closed. The returned `stat` remains an ordinary numeric Node `Stats` object. Use it for streaming output. Prefer `await using` for cleanup.
+
+`remove` leaves non-empty directories unchanged unless `recursive: true` is
+provided. Recursive removal defaults to streaming entries in filesystem order;
+`order: "sorted"` processes each directory's children lexicographically. The
+`maxEntries` (100,000 by default) and `maxDepth` (64 by default) budgets accept
+explicit `Infinity` when the caller needs unlimited traversal. It never
+follows discovered symlinks; an explicit `mutationSymlinks` policy rejects them,
+while the omitted policy unlinks them. `force: true` ignores missing targets,
+and `signal` stops further work after admitted I/O and resource cleanup settle.
+Removal is not transactional: a budget, cancellation, policy, or identity
+failure can leave a partially removed tree. See [removal](writing.md)
+for the full counting and failure contract.
+
+### Live mutation authority
+
+All mutation methods accept `assertBeforeMutation?: () => void`. Use it when a
+lease, operation owner, or cancellation state can expire while filesystem
+preparation is awaiting I/O:
+
+```ts
+const controller = new AbortController();
+await fs.write("config.json", "{}\n", {
+  assertBeforeMutation: () => controller.signal.throwIfAborted(),
+});
+```
+
+The callback runs synchronously after awaited preparation, immediately before
+each Root-owned mutation is dispatched: parent creation, file creation and
+content writes (including private staging and streamed chunks), publication,
+truncation, append, move, and removal. Buffered writes use bounded chunks and
+recheck before every partial-write submission; file removal submits a direct
+unlink request. Native calls that perform multiple filesystem steps are one
+dispatch. No asynchronous wait separates the check
+from that dispatch. A thrown value rejects the operation unchanged; an async
+or thenable-returning callback rejects with `TypeError` before that mutation.
+Synchronous return values are ignored. Callbacks can run multiple times and
+must inspect current authority each time.
+
+Already dispatched I/O cannot be revoked. Identity-checked cleanup, final
+permissions, and durability finish under the existing operation owner even
+after authority expires. Sidecar lock acquisition, recovery, and release for
+`renameIdentity: "verify-content-with-lock"` are lock bookkeeping outside this
+callback; content mutations still recheck after the lock is acquired. An
+operation may leave already-created parent directories when a later check
+rejects. A no-op such as `ensureRoot()` on the existing root does not require a
+callback invocation. This is a dispatch fence, not a filesystem transaction or
+a replacement for root confinement.
+
+If cleanup also fails or cannot prove ownership of an entry, the existing
+structured cleanup error takes precedence and retains the authority refusal
+as its cause.
+
+For `openWritable()`, the callback covers the library's parent creation,
+exclusive creation, and truncation. The returned raw `FileHandle` belongs to
+the caller, which must check authority before its own later writes.
 
 All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
 
+All mutation methods also accept `mutationSymlinks`. `"reject"` rejects symlink
+components; `"follow-parents-within-root"` resolves contained parent directory
+aliases but rejects the final component if it is a symlink, including a dangling
+link. Missing parent directories can still be created through a contained alias.
+`move()` applies the policy to both source and destination. An omitted value
+preserves existing behavior, including `remove()` unlinking a final symlink.
+The read-only `symlinks` default does not change mutation behavior.
+
 ### Inspection (advisory)
 
 ```ts
@@ -140,14 +305,27 @@ fs.exists(rel)                   // boolean
 fs.stat(rel)                     // PathStat
 fs.list(rel)                     // string[]
 fs.list(rel, { withFileTypes })  // DirEntry[]
+fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, including symlinks
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
-These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
+These do not pin a later operation. During `stat()`, the exact selected target and
+parent are checked around metadata collection; `list()` checks one exact selected
+directory around the complete name/metadata batch instead of repeating containment
+work for every child. A detectable redirection rejects with `path-mismatch` rather
+than returning names or metadata from the replacement. Results remain advisory
+after the call returns, so use the verb methods for the actual read or write.
+
+`entries()` streams immediate children in filesystem order by default. It
+supports cancellation, a physical-entry limit that throws on overflow, and
+bounded sorted-name collection. It reports child symlinks without following
+them; its `symlinks` option applies only to the selected directory path.
+See [Directory entries](entries.md) for ordering, identity, and partial-result
+semantics.
 
 `resolve()` is the exception to the existing-object rule: because it selects a
 location for later use, it rejects a leading drive-relative spelling. Reads,
-`stat`, `exists`, `list`, `walk`, `remove`, and the source argument of `move`
+`stat`, `exists`, `list`, `entries`, `walk`, `remove`, and the source argument of `move`
 accept an existing POSIX filename such as `c:notes.txt`. For `move`, only the
 new destination name is subject to the portable guard.
 
@@ -218,6 +396,35 @@ await fs.readText("config.toml");
 await fs.readText("links/current.log", { symlinks: "follow-within-root" });
 ```
 
+With `follow-within-root`, parent components after a symlink are applied to the
+symlink's resolved target. Reads use that checked canonical path, including
+after home expansion and through `readAbsolute` and `reader`; the default policy still rejects a symlink
+even when a later `..` would hide it in a purely lexical normalization.
+
+Use `follow-parents-within-root` when directory aliases are allowed but a final
+file symlink should fail. Set each policy at the root to share that contract
+between reads and mutations:
+
+```ts
+const workspace = await root("/srv/workspace", {
+  symlinks: "follow-parents-within-root",
+  mutationSymlinks: "follow-parents-within-root",
+});
+await workspace.readText("directory-alias/notes.txt");
+await workspace.write("directory-alias/notes.txt", "updated\n");
+```
+
+The library uses the resolved parent for the operation and checks the final
+component again before publication or removal. These checks preserve the existing
+[platform containment guarantees](security-model.md#symlinks-write-side);
+they do not make check-and-rename atomic against another process. Callers do not
+need a separate `realpath()` or final `lstat()` preflight.
+
+For methods that accept absolute paths, the same final-component rule applies
+when a path enters the root through an alias outside its lexical spelling. A directory alias may
+lead to a regular file inside the root; an absolute final file or directory
+symlink is rejected before its canonical target replaces the original path.
+
 Text helpers default to UTF-8. Pass `encoding` per call to `readText`, `readJson`, `write`, `create`, or `append` when you need another encoding.
 
 ## Common patterns

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

@@ -81,6 +81,9 @@ itself must not be an alias. Hardlinks are rejected by default so another
 in-tree name cannot alias the credential; pass `rejectHardlinks: false` only
 when you explicitly trust that layout.
 
+Read options are captured when the call starts. Mutating a shared options
+object while an asynchronous read is in flight cannot relax its link policy.
+
 These readers do not enforce ownership or mode bits on an existing file. Their
 read contract covers pinned identity, file type, link policy, and byte bounds;
 the `0o600` guarantee belongs to the write helpers below. Use
@@ -172,9 +175,15 @@ type WriteSecretFileParams = {
   content: string | Uint8Array;
   mode?: number;                // file mode for the new file (default PRIVATE_SECRET_FILE_MODE = 0o600)
   dirMode?: number;             // mode for the root and intermediate dirs (default PRIVATE_SECRET_DIR_MODE = 0o700)
+  durable?: boolean;            // default true; false skips file and parent fsync
 };
 ```
 
+`durable: false` preserves atomic publication, modes, and identity checks while
+skipping file and parent-directory `fsync` calls. Use it only for reconstructible
+data where lower latency matters more than crash-durability; private and JSON
+stores forward their durability policy here.
+
 The full POSIX directory mode is asserted on each component along the path: `rootDir`, then any intermediate dirs, then the parent. Existing directories, including another creator's `EEXIST` winner, must already match `dirMode` exactly or the write fails with `insecure-permissions`; they are never chmod-repaired. An explicitly requested directory mode such as `0o2750` preserves its setgid bit. Audit and adjust existing secret directories yourself. The admitted directory guards are retained through traversal and the final writer/lock handoff; a fresh pathname lookup cannot silently authorize a replacement. The caller must still trust the selected root and its owners; matching permission bits alone do not establish that trust.
 
 Directory admission and its retained guards use lossless bigint identities, including through private locks and native writes. On Windows, an unknown zero device or inode gets one reinspection that retains known components; a definite mismatch or persistent ambiguity fails with `path-mismatch` rather than authorizing a replacement.

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

@@ -21,14 +21,17 @@ The helper:
 - rejects every non-regular preview and, by default, symlink paths
 - opens POSIX paths no-follow and nonblocking before reading, then verifies the opened fd still matches the path and realpath; a FIFO swap cannot block before `timeoutMs` owns the byte read
 - optionally requires the real path to live under one of `trust.trustedDirs`
+- rejects hardlink aliases using descriptor, pathname, and realpath link counts, then rechecks the descriptor after reading before returning bytes
 - rejects hard-to-verify or unsafe permissions unless `permissions.allowInsecure` is set
 - rejects files owned by another POSIX uid
 - enforces `maxBytes` before and after reading
 - closes the handle on success, error, and timeout
 
-On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper uses the ACL inspection helpers from [`permissions`](permissions.md) and refuses the read if ACLs cannot be verified.
+On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper queries owner, DACL, and locality from the same open descriptor that supplies the bytes. The native query returns the 32-bit volume serial and 64-bit file-index projection used by Node, which must equal Node's bigint descriptor receipt before its ACL facts are trusted. This avoids JavaScript number rounding but does not represent the full 128-bit file identity available on ReFS. Only the current user, LocalSystem, and built-in Administrators are trusted owner classes.
 
-Descriptor, pathname, and realpath identity checks use lossless bigint stats internally. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
+Windows secure reads require the matching current optional native package. A missing or stale helper, fd-to-handle conversion failure, denied `READ_CONTROL`, remote handle, incomplete descriptor, or unsupported ACE form rejects with `permission-unverified` before content is read. A malformed or different handle identity rejects with `path-mismatch`. There is no pathname-command fallback for `readSecureFile()`; the standalone reporting APIs in [`permissions`](permissions.md) retain their documented fallbacks. `permissions.allowInsecure` remains the explicit escape hatch and bypasses the ACL query.
+
+Descriptor, pathname, and realpath identity checks use bigint stats internally to avoid JavaScript number rounding. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
 
 ## Options
 
@@ -59,8 +62,14 @@ type SecureFileReadOptions = {
 
 `io.maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap and `Infinity` disables the cap. Invalid limits reject before filesystem admission.
 
+The helper synchronously snapshots the supplied options, including nested permission and I/O settings, the injection callback, and supplied injection environment values, before opening the file or reaching its first `await`. Mutating those objects after this snapshot does not change that read's policy. This is not an atomic snapshot at invocation entry: caller getters run during snapshot construction and can affect values or working directories that have not yet been captured. `trust.trustedDirs` must be an array with a valid length and an own string entry without null bytes at every index; malformed lengths or entries, including sparse entries filled by inherited properties, reject with `invalid-path` before filesystem admission. An omitted or empty array leaves the read unrestricted by directory.
+
+Relative trusted directories (including an empty string) are resolved to absolute lexical paths during this synchronous snapshot using Node's `path.resolve()` semantics. Windows drive-relative entries retain their per-drive current-directory semantics, and extended-length drive roots retain their root separator. Raw alternate-stream and filesystem-namespace aliases reject before normalization. Working-directory changes after the snapshot cannot redirect this allowlist. The existing realpath check still follows trusted-directory symlinks when it runs and falls back to the captured lexical path if realpath lookup fails; the allowlist does not pin directory identities.
+
 `permissions.allowInsecure` is a migration escape hatch. Prefer fixing permissions and using [`formatPermissionRemediation`](permissions.md) to show the user what to run. `trust.allowNetworkPath` is off by default because UNC paths are remote authority, not local filesystem input. `inject` is for tests and platform adapters; production callers usually leave it unset.
 
+On an actual Windows process with effective `platform: "win32"`, `inject.env` and `inject.exec` do not replace descriptor inspection. They remain available to simulated Windows checks on non-Windows hosts.
+
 `permissions.allowInsecure` bypasses only permission checks. Neither it nor `inject.platform` changes filesystem identity verification, which always uses the actual process platform. `trust.allowSymlink` permits an alias but still requires its target and realpath to match the opened descriptor.
 
 ## Errors
@@ -69,29 +78,27 @@ type SecureFileReadOptions = {
 
 | Code | Meaning |
 |---|---|
-| `invalid-path` | `filePath` was not a local absolute path. |
+| `invalid-path` | `filePath` was not a local absolute path, `trust.trustedDirs` contained malformed paths, or a Windows file path/trusted directory used an alternate-stream or filesystem-namespace alias. |
 | `not-found` | The path could not be stat'd before open. |
 | `not-file` | The opened target is not a regular file. |
 | `symlink` | The path is a symlink and `trust.allowSymlink` is false. |
+| `hardlink` | The descriptor, pathname, or realpath has more than one link. |
 | `path-mismatch` | The path or realpath changed between open and verification, or filesystem identity could not be verified after bounded re-inspection. |
 | `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
-| `permission-unverified` | Required mode/ACL checks could not be completed. |
+| `permission-unverified` | Required mode/ACL checks could not be completed, including when descriptor-bound Windows inspection is unavailable. |
 | `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
-| `not-owned` | POSIX owner uid is not the current process uid. |
+| `not-owned` | POSIX owner uid is not the process's effective uid. |
 | `too-large` | File size or bytes read exceeded `maxBytes`. |
 | `timeout` | `timeoutMs` elapsed while reading. |
 
-Windows inspection failures remain operational `permission-unverified` errors
-and still refuse the read. Their message includes the underlying reason when
-available. `details` includes `ownerError` for owner-query failures and, when
-command diagnostics are available, `command`, `durationMs`, `timedOut`,
-`exitCode`, `signal`, and `stderr`. Reasons and stderr are control-character
-escaped and limited to 400 characters each (including a truncation marker).
-No stdout or target file contents are copied into these display diagnostics.
-The original inspection exception is retained as `cause`; built-in command
-errors also retain their original execFile exception in the cause chain.
-Treat causes as restricted local diagnostic data. No retries are performed,
-and verification order and rejection conditions are unchanged.
+Windows descriptor-inspection failures are operational `permission-unverified`
+errors and refuse the read. The original native exception is retained as
+`cause`; treat causes as restricted local diagnostic data. No pathname or ACL
+content is copied into the display message. Test adapters that simulate Windows
+on another operating system retain the standalone pathname inspector's
+structured command diagnostics (`ownerError`, `command`, `durationMs`,
+`timedOut`, `exitCode`, `signal`, and bounded escaped `stderr`). Actual Windows
+secure reads do not start those commands. No retries are performed.
 
 ## See also