@openclaw/openshell-sandbox 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/path-suffix-aliases.md

@@ -36,6 +36,7 @@ type ProbePathSuffixAliasesOptions = {
   directory: string;
   left: string;
   right: string;
+  maxDepth?: number;
   shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
 };
 
@@ -44,9 +45,11 @@ function probePathSuffixAliasesSync(
 ): boolean | undefined;
 ```
 
-The helper reads and validates `directory`, then resolves it to an absolute path
-before reading the suffixes or predicate. Later option getters or the predicate
-cannot retarget a relative directory by changing the working directory. When
+The helper reads `directory`, rejects non-string values and supplied paths longer
+than 32,768 code units, then rejects NUL-containing inputs. It resolves the path
+to an absolute path and applies the same limit to that result before reading
+`maxDepth`. Each option is read once. Later option getters or the predicate cannot retarget a
+relative directory by changing the working directory. When
 filesystem observations are needed, the directory is canonicalized and its
 identity is checked; an initial directory alias can be followed.
 
@@ -56,26 +59,68 @@ inputs are rejected with `TypeError`. Windows additionally rejects drive-relativ
 components, colons, and reserved device names, including device aliases with
 extensions or trailing ignored characters. On POSIX, backslashes and colons are
 ordinary filename characters. The optional predicate must be a function.
+`maxDepth` defaults to `32` and must be a non-negative safe integer; invalid
+values, including `Infinity`, throw `RangeError` before mutation or an
+identical-suffix return. A value of `0` admits no ordinary nonempty suffix.
 
 Both suffixes and the predicate are validated before the identical-suffix fast
 path. Identical, valid, within-budget suffixes return `true` without filesystem
 access or a predicate call. This does not prove that the directory exists or that
 the suffix can be created.
 
-## Fixed resource limits
+The forward-observation allowance never exceeds 32,768, even with a large
+`maxDepth`. A deeper or repeatedly colliding probe can return `undefined` when
+that ceiling is reached. Reverse cleanup still runs outside this allowance.
 
-These limits apply to one call and cannot be raised through options:
+## Resource budgets
+
+The default limits for one call are:
 
 | Resource | Limit | On exceeding the limit |
 |---|---|---|
 | Each supplied suffix | 8,192 UTF-16 code units | `RangeError` before mutation |
 | Supplied and resolved directory paths | 32,768 UTF-16 code units each | `RangeError` before mutation |
-| Each suffix's component count | 32 | `RangeError` before mutation |
+| Each suffix's component count | `maxDepth`, default 32 | `RangeError` before mutation |
 | Directory-creation attempts | 128 | `undefined` after cleanup |
 | Successfully created probe directories | 64 | `undefined` after cleanup |
 | Forward filesystem observations | 4,096 | `undefined` after cleanup |
 | Each generated actual path | 32,768 UTF-16 code units | `undefined` after cleanup |
 
+### Deeper observations
+
+Applications comparing deeper prospective paths can explicitly raise `maxDepth`:
+
+```ts
+const prefix = "future/".repeat(32);
+const aliases = probePathSuffixAliasesSync({
+  directory: "/trusted/existing-directory",
+  left: `${prefix}Report.sqlite`,
+  right: `${prefix}report.sqlite`,
+  maxDepth: 33,
+});
+```
+
+The 8,192-code-unit suffix limit and 32,768-code-unit path limits remain fixed.
+Ordinary-component validation, Windows path controls, identity checks, and
+cleanup rules also remain unchanged.
+
+Operation budgets grow proportionally from the actual admitted suffix depth,
+not the requested `maxDepth`. For actual depth `D`, let `B = max(32, D)`.
+Directory-creation attempts are limited to `4 × B`, successfully created
+directories to `2 × B`, and forward filesystem observations to `min(32,768, 4 × B²)`.
+The quadratic observation allowance accommodates rechecks of owned ancestors.
+
+For example, 33 components allow 132 creation attempts, 66 created directories,
+and 4,356 forward observations; 65 components allow 260, 130, and 16,900.
+Specifying a large `maxDepth` for a short suffix keeps the original budgets.
+The suffix-length limit bounds actual depth to at most 4,096, so every budget
+remains a finite safe integer.
+
+Admission does not guarantee a boolean result. Repeated collisions, many
+normalization probes, filesystem limits, or identity failures can exhaust the
+budget or prevent an observation. The helper then returns `undefined` after
+cleanup attempts; callers must preserve their explicit ambiguity policy.
+
 Input limits are checked even for identical suffixes. Dynamic budgets count work
 across the whole call, including collision retries; removing a probe does not
 restore its creation budget. Cleanup is still attempted when a forward budget is

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

@@ -44,7 +44,7 @@ opened or mutated.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 
-Synchronous. Same as `isPathInside`, but resolves both inputs through `realpath` first. Use this when you want the canonical answer and either input might be a symlink.
+Synchronous. First requires lexical containment with `isPathInside`, then resolves both inputs through `realpath` and checks containment again. A lexically outside path is rejected even if its resolved target is inside the root.
 
 ```ts
 isPathInsideWithRealpath("/srv/uploads", "/srv/symlink-to-elsewhere"); // false
@@ -121,7 +121,7 @@ The check is intentionally not a normal consumer policy knob. Safe read APIs rej
 
 ### `isNotFoundPathError(err)`
 
-`true` if the error is a `NodeJS.ErrnoException` with code `ENOENT` (file or directory missing).
+`true` if the error has code `ENOENT` (file or directory missing) or `ENOTDIR` (a path component is not a directory).
 
 ```ts
 try {
@@ -207,8 +207,8 @@ import {
 } from "@openclaw/fs-safe/advanced";
 ```
 
-- `assertNoPathAliasEscape({ rootRealPath, candidatePath, policy })` — async. Asserts the candidate's resolved real path is inside the root. Configurable via `PATH_ALIAS_POLICIES` (which currently ships only the default `"strict"` policy).
-- `assertNoHardlinkedFinalPath({ filePath })` — async. Throws if the file at `filePath` has `nlink > 1`.
+- `assertNoPathAliasEscape({ absolutePath, rootPath, boundaryLabel, policy? })` — async. Applies root path resolution and final hardlink checks. `policy` defaults to `PATH_ALIAS_POLICIES.strict`; `PATH_ALIAS_POLICIES.unlinkTarget` permits final symlink and hardlink aliases for unlink operations.
+- `assertNoHardlinkedFinalPath({ filePath, root, boundaryLabel, allowFinalHardlinkForUnlink? })` — async. Rejects a regular file with `nlink > 1`; missing paths and nonregular resolved entries are ignored. Setting `allowFinalHardlinkForUnlink: true` skips this check for unlink operations.
 
 Use these when writing a custom helper that wants the same guards `root()` uses but with different surrounding logic.
 

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

@@ -42,7 +42,7 @@ POSIX remediation strings shell-quote paths with whitespace or metacharacters
 and protect option-like paths with `--`, so they can be presented as commands
 without letting the inspected pathname add shell syntax.
 
-`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` does not use those pathname fallbacks on Windows: it requires descriptor-bound native owner/DACL facts for the exact handle it reads.
+`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` obtains descriptor-bound owner/DACL facts for the exact handle it reads, using native support or the packaged PowerShell/C# bridge in `auto` and `off` modes.
 
 ## Advanced Windows ACL helpers
 
@@ -69,9 +69,10 @@ resolveWindowsUserPrincipal(env);
 ```
 
 The fallback Windows inspector reads the owner and DACL together through one
-built-in Windows PowerShell/.NET query. It returns canonical SIDs and numeric
-access masks, so Unicode paths and account names do not pass through lossy
-console display text. `inspectWindowsAcl()` uses native descriptor facts for
+built-in Windows PowerShell/.NET query. The query addresses its JSON command by
+module name and limits module discovery to PowerShell's bundled system modules.
+It returns canonical SIDs and numeric access masks, so Unicode paths and account
+names do not pass through lossy console display text. `inspectWindowsAcl()` uses native descriptor facts for
 complete local ACLs with nonzero inherited ACEs (or empty/null DACLs) when the
 optional Windows binding is available. It applies
 the same classifier to native facts and the fallback query, returning canonical
@@ -86,6 +87,12 @@ The advanced options retain `currentUserSid` as an explicit classification
 override and `principalTranslationFailed: true` as an immediate unverified
 result. The optional `principalSids` translation cache is still accepted but
 is no longer needed because the query returns SIDs directly.
+Injected executors must return the same structured success JSON as the built-in
+query: valid `ownerSid` and `currentUserSid` strings, an explicit boolean
+`remote`, and complete DACL facts (`complete`, `daclPresent`, and `aces`).
+Missing or nonboolean locality leaves both inspectors unverified; only
+`remote: false` establishes locality for owner trust. An explicit `remote: true`
+retains the ACL report but never grants trusted ownership.
 The existing classifier assigns principals to trusted, world, or group;
 trusted defaults include the current user, SYSTEM, and Administrators.
 The built-in query has a fixed 30-second process deadline. A command failure or timeout returns an
@@ -102,6 +109,19 @@ characters, including a trailing `…` when truncated. Diagnostics do not copy
 stdout or read target file contents. The separate `errorCause` retains the
 original exception for restricted local diagnosis; do not serialize or expose
 it as display text.
+Custom executors may reject with any JavaScript value. The fallback display
+formatter handles primitives directly and reads only string-valued `name` and
+`message` data descriptors through a small, fixed prototype budget. It does not
+coerce objects, invoke accessors, or inspect proxy targets; unavailable display
+facts use a bounded generic reason. Command fields follow the same best-effort
+data-descriptor rule. Raw string, `Buffer`, or genuine `Uint8Array` stderr
+retains the sanitization above. Byte stderr is copied through captured
+typed-array intrinsics into a private bounded snapshot before replacement-based
+UTF-8 decoding; receiver properties, iterators, constructors, and altered
+prototypes are not consulted. Detached or out-of-bounds byte views contribute
+no stderr detail. These diagnostic limits do not relax permission policy:
+incomplete owner or ACL inspection remains unverified, and `errorCause` remains
+the exact rejected value even when no display metadata is safe to obtain.
 The parser and remediation command builders remain on the advanced surface for
 CLIs processing captured `icacls` output or presenting an explicit repair.
 Runtime inspection does not parse that display text. A null DACL reports
@@ -158,10 +178,12 @@ Object-specific and other ACE layouts are not guessed: they are omitted,
 `complete` becomes false, and their numeric types appear in
 `unsupportedAceTypes`, allowing a security-sensitive caller to fail closed.
 Non-Windows systems return `{ status: "unsupported-platform", platform }`.
-Windows requires the native binding; if it is unavailable or forced
-off, the call throws `FsSafeError("helper-unavailable")`. The existing coarse
-`inspectPathPermissions()` API still owns its compatibility fallback and trust
-classification.
+Windows prefers the native binding. In native `auto` or `off` mode, a missing
+binding or capability uses the packaged PowerShell/C# bridge with
+the same raw ACE projection. Native `require` rejects either absence with
+`FsSafeError("helper-unavailable")` and starts no command. An available native
+query's failure is terminal. The existing coarse `inspectPathPermissions()` API
+still owns its compatibility fallback and trust classification.
 
 ## Private directories
 
@@ -175,10 +197,11 @@ await createPrivateDirectory(sqliteDirectory);
 await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
 ```
 
-On Windows with native support, this creates the directory and applies a
+On Windows, this creates the directory and applies a
 protected owner + LocalSystem + Administrators full-control DACL directly with
-an atomic security descriptor; no PowerShell or `icacls` process is launched.
-The native operation retains the parent and exact created-directory handles
+an atomic security descriptor. The native route launches no command. When its
+binding or capability is unavailable, native `auto` and `off` modes use the
+packaged PowerShell/C# bridge. Both routes retain the parent and exact created-directory handles
 through ACL and final pathname validation. If validation fails, it attempts only
 nonrecursive deletion through the created handle, preserving any pathname
 replacement. If cleanup also fails, the error retains the original failure and
@@ -203,13 +226,32 @@ also rejects explicit `.` and `..` components, including spellings such as
 `.\private` and `parent\..\private`, as a compatibility restriction. Simple
 relative names without these components remain supported.
 
-This API is Windows-only and native-only; it fails closed with
-`FsSafeError("helper-unavailable")` on other platforms, when native mode is off,
-or when the binding is unavailable. POSIX callers should create private
+This API is Windows-only; it fails closed with `FsSafeError("helper-unavailable")`
+on other platforms. Native `require` also fails if the binding or capability is
+missing and never starts a command. An available native operation's failure is
+terminal. POSIX callers should create private
 directories through their existing trusted-root creation policy rather than a
 pathname-only compatibility shim. Existing Windows permission inspection still
 retains its structured .NET compatibility fallback.
 
+The raw owner/DACL and private-directory fallbacks each emit one path-free
+`FS_SAFE_NATIVE_FALLBACK` warning per process. PowerShell startup and C#
+compilation add overhead to each call; install the native package for frequent
+operations. These routes run the package's readable, fixed scripts under normal
+system PowerShell policy; see the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+If command support is unavailable, disallowed, or fails, the operation rejects.
+Private-directory creation never falls back to inherited permissions.
+The asynchronous creation command has a 30-second deadline. After a timeout or
+transport failure, fs-safe requests termination and waits at most one further
+second before rejecting and closing its output pipes. The error distinguishes
+observed process exit from an unconfirmed termination attempt. If the OS refuses
+termination, the command can still create the directory after rejection. An
+already-created object retains its protected DACL, but pathname validation and
+owned-handle cleanup may not finish. An error therefore does not prove the
+pathname is absent; a retry can report `EEXIST`. Before retrying or using the
+pathname, establish that the earlier operation stopped and verify any existing
+directory's security. The library does not attempt pathname-based cleanup.
+
 Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
 
 ## Types

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

@@ -20,6 +20,9 @@ The root subpath also exports `openLocalFileSafely`, `readLocalFileSafely`, and
 `resolveOpenedFileRealPathForHandle` for trusted absolute-file composition.
 They do not create a root boundary around arbitrary caller input; prefer
 `root()` for untrusted paths.
+The handle resolver verifies exact descriptor and pathname identities, with one
+bounded retry for unknown Windows observations. It borrows the handle without
+reading, reopening, closing it, or changing its cursor.
 
 The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`. The
 deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
@@ -43,8 +46,9 @@ 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.
+`copyFileHandle` and `copyFileDescriptorSync` share `CopyFileHandleOptions` to
+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`
@@ -134,6 +138,8 @@ The durability surface also exports the synchronous strict
 `Sha256FileSyncInput`, `Sha256FileOptions`, and `Sha256FileResult`.
 `sha256FileSync()` provides synchronous pathname or borrowed-descriptor hashing
 with the same byte-budget and digest-result contracts as `sha256File()`.
+`DirectoryReceipt<T>` accepts `Stats` or `BigIntStats` input metadata; its default
+type argument and returned durability receipts remain numeric `Stats`.
 
 ## 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. 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).
+`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()` removes files and empty directories by default. To remove a non-empty directory, pass `{ recursive: true }`; use `maxEntries`, `maxDepth`, and `signal` to bound the work. See [`root()`](root.md) for removal ordering, limits, and partial-removal semantics.
 
 ## 5. Inspect
 

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

@@ -28,7 +28,7 @@ Regardless of shape, every read goes through the same boundary checks:
 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 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`).
+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
@@ -100,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

@@ -49,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
@@ -72,12 +76,22 @@ The default `order: "sorted"` enumerates and sorts each directory's names;
 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.
 
@@ -120,8 +134,32 @@ 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`).
 
+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
@@ -133,6 +171,8 @@ 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
@@ -142,6 +182,11 @@ 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.
 
+`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`:
@@ -269,6 +314,13 @@ 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
@@ -290,6 +342,20 @@ 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
@@ -355,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

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

@@ -113,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:
 
@@ -133,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
@@ -192,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)`
@@ -270,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
 

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

@@ -27,9 +27,13 @@ The helper:
 - 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 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.
+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. Both native and system-command queries return 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.
 
-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.
+Windows secure reads prefer the matching optional native package. In native `auto` or `off` mode, a missing binding or descriptor-inspection capability uses a packaged, readable PowerShell script and adjacent C# source to inspect the borrowed file handle. This route requires the [Windows security fallback prerequisites](install.md#windows-security-fallback), including permission to run the scripts under normal system policy. The command does not read file contents or reopen the pathname. Successful inspection waits for the child to exit and its output pipes to close. This emits a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per process for secure reads and adds PowerShell startup and compilation overhead to each inspection.
+
+Descriptor commands have a 30-second deadline. After a timeout or transport failure, fs-safe requests termination, waits at most one further second, and then rejects even if process exit or pipe closure remains unconfirmed. It closes its own output pipes and reports the observed exit separately from the termination attempt in the error cause. If the OS refuses termination, the child may retain its independently inherited Windows handle; closing the caller's descriptor cannot retarget that handle. No file bytes are returned from a failed inspection.
+
+Native `require` still rejects a missing binding or capability with `permission-unverified`, without starting a command. An available native helper's failure is terminal. On either route, fd-to-handle conversion failure, denied `READ_CONTROL`, a remote handle, incomplete descriptor, unsupported ACE form, or unavailable command support rejects with `permission-unverified` before content is read. A malformed or different handle identity rejects with `path-mismatch`. The standalone reporting APIs in [`permissions`](permissions.md) retain their documented pathname 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.
 
@@ -92,13 +96,14 @@ On an actual Windows process with effective `platform: "win32"`, `inject.env` an
 | `timeout` | `timeoutMs` elapsed while reading. |
 
 Windows descriptor-inspection failures are operational `permission-unverified`
-errors and refuse the read. The original native exception is retained as
+errors and refuse the read. The original native or descriptor-command 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.
+secure reads never invoke the injected pathname inspector: their optional
+command route inspects the borrowed descriptor instead. No retries are performed.
 
 ## See also