@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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`.
-7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
+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`), including links introduced before either fresh final pathname observation. Root-file helpers apply the same final check when `rejectHardlinks` is enabled; directory admission is unaffected.
 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?)`
@@ -87,7 +100,7 @@ type RootReadOptions = {
   hardlinks?: "reject" | "allow";   // override defaults.hardlinks
   maxBytes?: number;                // refuse reads larger than this many bytes
   nonBlockingRead?: boolean;        // compatibility hint; safe opens are already nonblocking where supported
-  symlinks?: "reject" | "follow-within-root"; // override defaults.symlinks
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // override defaults.symlinks
 };
 ```
 

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

@@ -110,6 +110,9 @@ descriptor, and current pathname identities remain exact bigints through the
 append boundary; rounded-equal replacements and persistent unknown Windows
 identities reject before chmod or writing bytes. With
 `rejectSymlinkParents: true`, it also rejects symlinked ancestor directories.
+Supported option values are captured once before filesystem work, so replacing
+the content, encoding, mode or cap cannot change an in-flight append. Byte-array
+contents remain caller-owned; leave them unchanged until the append completes.
 
 On POSIX, `O_NONBLOCK` prevents a no-reader FIFO substituted before open from
 stalling admission. A confirmed non-regular target is refused before chmod or

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.
 
@@ -45,6 +49,10 @@ Every `maxBytes` value must be a non-negative safe integer or positive `Infinity
 
 Every method on the returned handle accepts paths relative to the root and rejects anything that would escape it.
 
+Explicit path, data, and copy-source arguments select the operation. Properties
+with those names in an options object do not replace them; a supplied source
+Root retains ownership of source admission and read policy.
+
 ### Reads
 
 ```ts
@@ -60,15 +68,30 @@ 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
-directory; `"skip-subtree"` omits a directory and all of its descendants.
+`"skip-subtree"`, directly or through a Promise. `"skip"` omits the current
+entry but still descends into a directory; `"skip-subtree"` omits a directory
+and all of its descendants.
+Filters run serially outside metadata batches, with the options object as their
+`this` receiver. After an awaited filter resolves, the walk checks cancellation
+and revalidates the current listing directory and Root identities before using
+the decision. Captured entry metadata retains its snapshot semantics.
+
+Cancellation and iterator disposal wait for a pending filter to settle; they do
+not race the callback or close its directory while it is running. Callback
+throws and promise rejections reject the walk through normal cleanup.
 Directory reads remain fail-fast by default. With
 `onDirectoryError: "skip-and-report"`, the iterator instead yields
 `{ relativePath, kind: "directory-error", size: 0, error }` and continues with
-the remaining tree.
+the remaining tree. That policy also covers identity-check failures after an
+awaited filter, while callback failures always reject.
 See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
 with the standalone best-effort walkers.
 
@@ -91,7 +114,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 +128,53 @@ 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
 ```
 
+`mkdir`, `ensureRoot`, `create`, and `createJson` accept `private: true`.
+Missing directories are created with private permissions, and an existing
+requested directory must already be private. Existing ancestors are not
+chmodded or assigned new ACLs. Private files use owner-only POSIX permissions
+or a protected Windows DACL granting access to the current user, System, and
+Administrators. On macOS, private directories and files must also have no ACL;
+creation rejects relevant inheritable parent ACLs, while noninheriting parent
+ACLs remain allowed. A native helper with `inspectDarwinAcl` is required. Native
+`off`, a missing helper, or an older helper without that capability rejects with
+`helper-unavailable` before creating parents or stages. See [creation](creation.md)
+for platform support, synchronous leaf creation, and failure handling.
+
+```ts
+await fs.mkdir("private-data", { private: true });
+await fs.create("private-data/credential", "synthetic credential", { private: true });
+```
+
 `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
+Buffered `create` and `createJson` also accept `atomic?: boolean`. With `true`,
+complete content is staged before exclusive publication even in native-off mode;
+the fallback requires hardlinks. Omitted or `false` keeps the existing buffered
+publication behavior. Streamed creates always stage complete content. The flag
+does not change `durable` or promise stronger containment or crash durability.
+See [atomic creation and settlement](writing.md#atomic-buffered-creation).
+
+`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.
+Empty strings and Buffers add no separator; an empty append still creates a
+missing file.
+
+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 +182,81 @@ 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`.
+`create` and `createJson` additionally accept `durable: "file"` to require file
+synchronization, including propagating `EPERM`. Parent-directory synchronization
+retains its existing best-effort behavior. This option applies to buffered and
+streamed creation and does not select a publication strategy.
+
+`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 +266,104 @@ 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.
+Directory creation rechecks the retained parent after the callback and before
+submitting mkdir, so a replacement is rejected before creating that component.
+Overwrite moves recheck the retained root, parents, source identity and both
+routes after the callback, including destination parents that were missing
+during preparation. Removals recheck cancellation, retained ancestry and exact
+leaf identity before dispatch; `force` tolerates a missing leaf, not replaced
+ancestry. Removing an admitted hardlink still leaves its other names intact.
+
+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.
 
+`move()` snapshots its merged default and per-call mutation policy before
+asynchronous preparation. Later changes to the original policy objects or arrays
+apply to subsequent calls. Use `assertBeforeMutation` for live revocation of an
+in-flight move.
+
+For writes, creates, streams, and copies, parent creation admits the prospective
+file and each missing directory before creating that directory, including on the
+Windows native route. An exact deny on an existing parent does not prevent using
+that parent to write an allowed child. If a deeper missing parent is denied,
+earlier admitted directories may remain; the denied directory and file are not
+created. With `mkdir: false`, missing parents are never created. Native Windows
+policy-aware creation requires the direct-child helper and fails with
+`helper-unavailable` if it is absent.
+
+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 +371,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.
 
@@ -177,6 +421,12 @@ fs.rootWithSep   // rootReal with a trailing separator, for prefix comparisons
 fs.defaults      // the RootDefaults you passed
 ```
 
+The path properties are readonly metadata. Each Root retains the canonical
+directory and exact identity admitted when it was created; changing object
+properties is not a supported way to retarget it. Create another Root to use a
+different directory. The `defaults` reference is readonly, while the supplied
+object's option values remain live for later calls.
+
 ## Failure semantics
 
 Boundary and policy failures throw `FsSafeError` with a `code`. Parsing callbacks
@@ -218,6 +468,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
@@ -110,6 +113,10 @@ If an already validated descriptor fails while reading, both readers throw an
 operational `FsSafeError` with `code: "read-failed"`; inspect `cause` for the
 underlying Node filesystem code such as `EIO`.
 
+A synchronous reader closes its descriptor once. A close failure preserves an
+earlier read or identity-validation error; after a successful read, the close
+failure is reported before trimming or rejecting empty content.
+
 Use the async strict reader when a service cannot start safely without the
 credential:
 
@@ -130,6 +137,15 @@ startWebhookVerifier(signingKey);
 
 Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file, finalizes `mode` (default `0o600`) through an owned descriptor after content writes, and atomically renames over the destination. Publication verification checks the final file identity and mode.
 
+On POSIX, both native and JavaScript writers verify actual `0o600` permission
+bits through the retained descriptor before writing content. A filesystem that
+reports successful chmod without enforcing those bits fails with
+`insecure-permissions` before any payload is written, including when an explicit
+`dirMode` permits other users to traverse the parent. The requested final `mode`
+is still applied after content writes, including restrictive and special-bit
+overrides. This mode-bit check does not require native ACL inspection; JavaScript
+secret writes remain available on macOS.
+
 Concurrent writes to distinct leaves may share creation of a missing parent.
 After a parent-creation race, the helper re-inspects the entry and requires a
 non-symlink directory, then revalidates root/parent guards, containment, and
@@ -172,9 +188,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.
@@ -183,6 +205,10 @@ Both mode options must resolve to integers between `0o0000` and `0o7777`; invali
 
 After this operation wins directory creation, initialization uses a pinned descriptor bound to the admitted identity and effective user, with ancestor checks before chmod. It does not chmod the caller's pathname. Creation and descriptor admission are separate operations, not an atomic create-and-pin guarantee. A raced directory that has not reached its requested mode yet is rejected rather than repaired; callers may retry after its creator finishes initialization.
 
+If initial directory-descriptor admission fails, its original identity, ownership,
+or inspection error is preserved even when closing the rejected descriptor fails.
+Close failures after successful admission remain reportable.
+
 Initialization fails closed if the platform cannot safely pin a created directory. In particular, a non-root macOS process cannot pin a new `000` directory produced by `umask(0o777)`; the write fails without repairing that directory or writing a secret. Restrictive masks retaining owner search permission remain usable. Linux x64/arm64 can use the guarded `O_PATH`/procfs descriptor route where available. There is no unguarded pathname-chmod fallback, and a failure may leave a created directory for caller-managed cleanup.
 
 ### `createSecretFileAtomic(params)`
@@ -261,9 +287,9 @@ await withTimeout(
 
 ## Threat model notes
 
-- These helpers protect the secret file from **other processes with the same UID** that respect filesystem permissions. They do not defend against root or against attackers who can read process memory.
+- On POSIX, the default `0600` file and `0700` directory modes restrict group and other access. They do not protect against processes with the same UID, root, attackers who can read process memory, or access granted by additional ACL entries.
 - Validation failures are tripwires, not authorization. Investigate before clearing a rejected credential file.
-- If the destination directory is on a tmpfs that does not honor mode bits, the helpers will set the mode bits but the OS may ignore them. Audit your platform.
+- On POSIX, a file that still reports a mode other than `0600` after initialization is rejected with `insecure-permissions` before payload is written. Matching mode reports alone cannot prove that an arbitrary filesystem actually enforces those permissions.
 
 ## See also