@openclaw/openshell-sandbox 2026.9.4 → 2026.9.5

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

@@ -14,7 +14,89 @@ import {
 
 ## Private temp workspaces
 
-A private workspace is a directory created at mode `0o700` under a caller-provided temp root. It is unique per call (random suffix). Calling `cleanup()` or leaving an `await using` scope moves an unchanged workspace through a private quarantine before removal. Descriptor-bounded cleanup prevents recursive traversal of substitutions; the compatible JavaScript fallback has the narrower race contract documented below.
+A private workspace is a uniquely named directory under a caller-provided temp
+root. The default requested mode is `0o700`. Calling `cleanup()` or leaving an
+`await using` scope moves an unchanged workspace through a private quarantine
+before removal. Descriptor-bounded cleanup prevents recursive traversal of
+substitutions; the compatible JavaScript fallback has the narrower race
+contract documented below.
+
+On POSIX, workspace creation verifies the supplied root and its canonical
+ancestors before creating a child. Each existing directory must be owned by the
+effective user or root. Group/world-writable directories must also have the
+sticky bit, so ordinary system temp directories remain usable without changing
+their modes. Foreign-owned directories and non-sticky writable ancestors reject
+with `not-owned` or `insecure-permissions`; unavailable effective-user identity
+rejects with `permission-unverified`. Existing supplied directories keep their
+permissions. Missing root components are created at `0o700` and initialized
+from their first exact security snapshot; if a restrictive umask changes that
+mode, correction uses a verified directory descriptor.
+
+For an already existing canonical root, discovery retains only its immutable
+exact identity. Cleanup-parent retention is provisional: after any native
+capability probe, creation captures and validates the complete ancestry,
+re-observes the root against discovery, and associates the retained parent
+descriptor. Async creation and sync creation outside the Linux/macOS
+direct-mode case dispatch `mkdtemp` immediately after that synchronous boundary
+without another yield or native probe. Existing aliases and missing-component
+roots keep the guarded admission route.
+
+On Linux and macOS, synchronous creation can instead use an exclusive six-character
+random child name when an explicit requested mode other than `0o700` has owner
+`rwx`, no special bits, and no group/world write bits. The requested mode is
+passed directly to `mkdir` and the observed complete permission bits, rather
+than the requested bits, are authoritative. Umask, inherited ACL state, or
+inherited special bits can make that observation differ, in which case creation
+corrects the mode through the retained descriptor. This mode-based optimization
+does not claim that Linux and macOS have identical syscall or ACL behavior, and
+POSIX mode bits do not establish ACL privacy. Creation makes at most 64 attempts;
+after a name collision, each retry generates its candidate first, replays the
+already admitted immutable ancestry and descriptor receipts, and then
+immediately attempts exclusive creation. A colliding entry is never inspected,
+adopted, corrected, registered, or deleted. The default `0o700`, async creation, and
+other sync modes retain the `mkdtemp` path. That path requests initial mode
+`0o700`; a result different from `dirMode` is initialized through the same
+descriptor-bound correction.
+
+The direct sync path opens the new child without following its final component
+and captures one exact descriptor observation after the parent replay. The new
+child's exact identity, type, owner, private bits, and complete `0o7777` mode are
+checked before mode initialization. When its creation mode already
+matches `dirMode` (including the default `0o700`), creation avoids an extra mode
+descriptor and chmod. If the observed creation mode differs from `dirMode`, the
+immediate synchronous correction consumes that one-shot observation, checks the
+fresh child name, replays the parent, and applies correction through the retained
+descriptor. Later admission always performs fresh descriptor and name checks.
+Permission failures propagate. POSIX `dirMode`
+must not grant group/world write access; it only controls the new workspace,
+not existing supplied directories. After the
+first exact child observation, final adoption retains a no-follow child
+descriptor, rechecks complete ancestry and retained cleanup-parent authority,
+and then validates the original child's descriptor and current name for exact
+identity, owner, private bits, and requested mode before cleanup is registered.
+Linux and macOS may replay exact identities through round-trip-safe nonnegative
+numeric `dev`/`ino` projections. Initial receipts that cannot be represented
+exactly stay on the BigInt path; a malformed or mismatched numeric replay fails
+closed without an exact retry.
+Parent or child replacements observed during creation reject before cleanup
+ownership is registered. Unverified artifacts are left in place for
+caller-directed recovery.
+
+On Windows, POSIX mode/UID metadata does not establish ACL privacy, and these
+factories neither claim nor initialize a POSIX `dirMode`; every requested value
+uses the identity-only path without opening a mode descriptor or applying chmod.
+Callers must supply a root with trusted ACLs that protect its children and
+ancestors; exact pathname identity checks still apply. `cleanupSafety` controls
+removal capability, not Windows ACL admission.
+
+Root aliases already present at entry retain their historical support and are
+canonicalized. Callers remain responsible for choosing trusted root paths and
+excluding hostile peers with the same filesystem authority. Node's pathname
+`mkdir`/`mkdtemp` calls do not atomically return a creation descriptor: identity
+checks detect observed substitutions but cannot prove provenance against every
+same-privilege replacement before the first observation. Descriptor chmod
+cannot be redirected to a subsequently substituted pathname. Native bounded
+cleanup does not upgrade the creation operation to an atomic namespace boundary.
 
 ### `tempWorkspace`
 
@@ -76,18 +158,36 @@ verification can still redirect the final pathname removal.
 
 Set `cleanupSafety: "require-bounded"` when that concurrent attacker is in scope.
 Creation then requires native no-replace directory rename, native owned-tree
-removal, and a retained parent descriptor **before** `mkdtemp` creates
-a child. If any capability is unavailable, creation throws
-`FsSafeError("helper-unavailable")`; no child is created and a scoped callback is
-not called. The compatible default retains its fallback even if process-global
-native mode is `require`; select `require-bounded` to make cleanup capability
-mandatory for this API.
+removal, and a readable retained parent descriptor **before** child creation.
+On POSIX, the final requested `dirMode` must also include owner read
+and search (`(dirMode & 0o500) === 0o500`). Preflight failure throws
+`FsSafeError("helper-unavailable")` without creating a child or calling a scoped
+callback. The child descriptor is opened
+while the new directory still has its private creation mode, before an explicit
+`dirMode` can lower access. Retaining a read descriptor does not bypass the
+POSIX final-mode requirement: enumeration reopens the directory relative to
+that descriptor. Compatible mode accepts these restrictive modes but selects
+the JavaScript fallback and does not retain native traversal authority for the
+child, even if the caller later restores its permissions. Windows cleanup
+does not use this POSIX mode gate. A search-only descriptor remains valid identity
+evidence but is never native traversal authority: compatible cleanup selects
+the JavaScript fallback, while `require-bounded` rejects and leaves the
+unregistered child in place for caller-directed recovery. The compatible
+default retains its fallback even if process-global native mode is `require`;
+select `require-bounded` to make cleanup capability mandatory for this API.
 
 On Linux, bounded cleanup requires a successful runtime probe of the exact
 `openat2` child-directory flags, including `RESOLVE_NO_XDEV`, against the retained
 parent descriptor. If the kernel or seccomp policy denies that capability,
 compatible mode uses the guarded JavaScript fallback; `require-bounded` rejects
-before child creation. The probe runs once at creation, without filesystem mutation.
+before child creation. For eligible modes, the probe runs once at creation,
+without filesystem mutation.
+
+Cleanup does not repair POSIX workspace or descendant permissions. In compatible
+mode, a restrictive workspace mode or caller-created unreadable descendants
+can prevent recursive removal; native bounded cleanup can also encounter later
+permission changes or inaccessible descendants. These remain operational
+cleanup failures, with the propagation and recovery behavior described below.
 
 Bounded cleanup checks the parent and public workspace identity, quarantines
 the direct child without replacement, and verifies the quarantine against the
@@ -183,12 +283,20 @@ try {
 type TempWorkspaceOptions = {
   rootDir: string;          // parent directory for workspaces
   prefix: string;           // dir prefix (sanitized)
-  dirMode?: number;         // dir mode; default 0o700
+  dirMode?: number;         // new workspace mode; default 0o700; no POSIX group/world write
   mode?: number;            // file write mode; default 0o600
   cleanupSafety?: "compatible" | "require-bounded"; // default compatible
 };
 ```
 
+On Windows, caller-provided workspace roots and workspace leaf names reject
+NTFS alternate-stream and directory-index namespace spellings before directory
+creation or file access. The lower-level temp and sibling helpers apply the
+same admission to supplied roots, sibling directories, and callback-selected
+final paths. Prefixes and `tempFile()` filenames keep their documented
+sanitization behavior; ordinary colon-bearing POSIX roots and leaf names remain
+valid.
+
 ## Advanced temp primitives
 
 When you don't need the stable workspace abstraction, the lower-level temp-file
@@ -212,6 +320,18 @@ try {
 }
 ```
 
+Options:
+
+```ts
+type TempFileOptions = {
+  rootDir?: string;
+  prefix: string;
+  fileName?: string;
+  onCleanupError?: (error: unknown) => void;
+  cleanupSafety?: "compatible" | "require-bounded"; // default compatible
+};
+```
+
 Returns:
 
 ```ts
@@ -224,9 +344,30 @@ type TempFile = {
 };
 ```
 
-Cleanup captures the directory identity at creation time. If that path is
-renamed away and replaced, cleanup preserves the replacement rather than
-recursively deleting a directory it did not create.
+The default `cleanupSafety: "compatible"` retains the historical temp-file
+behavior without loading or probing the native helper. Cleanup captures the
+directory identity at creation time and preserves a replacement observed by
+its pre-removal identity check. That check and pathname-recursive removal are
+separate operations, however: a same-privilege peer can substitute a directory
+in the final gap and redirect recursive traversal. Process-exit cleanup has the
+same compatible contract.
+
+The bounded mode requires an existing supplied root and applies the same
+trusted-ancestry admission as private temp workspaces. On POSIX it finalizes
+the new directory to `0o700` through its retained descriptor; Windows keeps
+identity checks without treating POSIX modes as ACL privacy. Unverified
+creation artifacts are preserved for caller-directed recovery.
+
+Set `cleanupSafety: "require-bounded"` to require the retained-parent,
+no-replace quarantine, and descriptor-bounded owned-tree removal described for
+[private temp workspaces](#private-temp-workspaces). Admission, including the
+runtime probe, completes before `mkdtemp`; unavailable support throws
+`FsSafeError("helper-unavailable")` before a child is created. Manual, disposal,
+scoped, and process-exit cleanup then share one owner, and no pathname-recursive
+fallback is used. `cleanup()` still resolves `Promise<void>`: operational
+cleanup errors are passed to `onCleanupError` when supplied and otherwise
+suppressed for compatibility. The bounded POSIX final-entry unlink limit still
+applies.
 
 ### `withTempFile`
 
@@ -262,13 +403,22 @@ const result = await writeSiblingTempFile<string>({
 // result.filePath, result.result (returned by writeTemp)
 ```
 
-`writeSiblingTempFile` chooses a random, initially absent sibling name in `dir`
-and calls `writeTemp()`. After the callback succeeds, it validates the produced
+By default, `writeSiblingTempFile` chooses a random, initially absent sibling
+name in `dir` and calls `writeTemp()`. After the callback succeeds, it validates the produced
 regular file before taking ownership: symlinks, directories, other non-regular
 files, hardlinks, and changes between the pre-open pathname, opened descriptor,
 and current pathname are rejected. The callback must finish and close its
 writer before returning. Its return value is preserved as `result`.
 
+Generated temp filenames suffix Windows reserved-device basenames on every
+platform. Before either an ordinary or isolated producer runs, the completed staging
+name must be a nonempty, non-dot path component with no POSIX or Windows
+separator, C0/C1 control, Windows-invalid punctuation or stream colon. Windows
+reserved devices and trailing-dot/space aliases are rejected on every host.
+The helper joins that validated component to the guarded or owned directory and
+verifies that the result is a direct child. An invalid completion rejects with
+`invalid-path` without calling the producer or its pre-write hook.
+
 The helper retains one descriptor through requested mode application, opt-in
 file synchronization, rename, and publication verification. It opens read-only
 unless file synchronization is requested, so closed read-only producer output
@@ -292,12 +442,52 @@ Omitting either option or passing `false` skips that sync, never the identity
 checks. Parent synchronization can be unsupported or fail without rejecting
 the write, so success is not a strict crash-durability receipt.
 
-Cleanup only unlinks an admitted file while the parent, pathname identity, and
-single-link regular-file checks still agree. Observed substitutes are preserved,
+Without producer isolation, cleanup only unlinks an admitted file while the
+parent, pathname identity, and single-link regular-file checks still agree.
+Observed substitutes are preserved,
 including during process-exit cleanup. Operational cleanup failures retain an
 identity-bound exit retry. If the callback throws or admission fails, no file
 has been adopted: even a regular partial file is left for caller-directed
-recovery. The helper never recursively removes a sibling temp.
+recovery. The helper never recursively removes a sibling temp file path.
+
+Set `producerIsolation: "private-directory"` in `WriteSiblingTempFileOptions`
+when the producer can leave partial output before throwing. The callback then
+receives an initially absent file path inside a private child workspace under
+`dir`, on the same filesystem as the final target. fs-safe captures directory
+cleanup ownership before invoking the callback. A callback exception triggers
+owned workspace cleanup, including partial output, subject to directory
+identity checks and I/O failures. The callback must still finish and close its
+writer before returning.
+
+After the callback succeeds, an available native helper uses guarded
+no-replace `Root.move`. Native-off operation admits the completed regular file
+with a retained descriptor. On Windows, that branch first requests write-only
+access so admission does not request completed-file data reads; access or provider
+rejections fall back to the historical read-only or read/write open before admission.
+It then creates the randomized sibling with an atomic
+no-clobber hard link and verifies the expected two-link transition. On Windows,
+it opens and verifies a sibling descriptor before closing the source descriptor,
+keeping the file pinned while allowing the private name to disappear on runtimes
+with legacy deletion behavior. It removes the private name before continuing.
+If legacy deletion clears the completed file's read-only attribute, the helper
+restores it through the retained sibling descriptor and verifies its mode and
+identity before publication. Restoration failures reject the operation.
+An escaping symlink fails with `path-alias`, and
+a filesystem without either handoff reports `helper-unavailable`. The retained
+descriptor carries file admission, requested modes, sync options, and final
+rename with their existing contracts; `resolveFinalPath(result)` still names a
+direct child of `dir`.
+
+The isolated path retains exact bigint identities for both the parent and the
+workspace and rechecks them before moving output to the sibling path. An
+observed replacement is rejected. This internal use of [`withTempFile`](#withtempfile)
+does not expose `cleanupSafety` and uses compatible cleanup: moving or replacing
+the parent or workspace can leave artifacts, and a workspace substituted in
+the final check-to-recursive-removal gap can redirect traversal. It does not
+promise cleanup through a retained directory after a rename, bounded cleanup,
+stronger permissions, or additional crash durability. Omitting producer
+isolation preserves the direct sibling callback path and unadmitted
+partial-file retention.
 
 On POSIX, admission uses no-follow and nonblocking open flags, so a FIFO swap
 does not block the helper. Windows retains Node's guarded pathname-open behavior
@@ -311,8 +501,11 @@ Identity checks and pathname rename/unlink are separate syscalls, not atomic
 conditional mutations. A hostile process can still replace a leaf or parent in
 the final syscall gap or mutate an open file's contents. Use an approved writable
 directory and cooperative locking or OS isolation; a moved parent can leave an
-unpublished original temp behind. Observed replacements are preserved, but
-arbitrary concurrent namespace changes cannot be prevented by these helpers.
+unpublished original temp behind. Replacements observed before the final
+namespace mutation are preserved, but that observation is not an atomic
+condition on the later unlink or rename. Private producer isolation also has
+the compatible recursive-cleanup gap described above. Arbitrary concurrent
+namespace changes cannot be prevented by these helpers.
 
 By default the helper attempts to set `dir` to `dirMode` (default `0o700`)
 through the shared verified POSIX directory-descriptor helper. Only the actual
@@ -343,12 +536,18 @@ await writeViaSiblingTempPath({
 If `replaceFileAtomic` does what you need, prefer that. Use
 `writeViaSiblingTempPath` when the producer needs a concrete temp pathname but
 the final destination still needs root-boundary checks.
-Its private workspace uses the same identity-aware directory cleanup as
-`tempFile()`: moving and replacing the workspace preserves the replacement.
-The callback staging component is capped at 255 bytes under NFC and NFD by
+Its private workspace uses `tempFile()`'s compatible identity-aware cleanup.
+It preserves replacements observed before removal, but retains the final
+pathname-recursive-removal gap described above; this helper does not expose
+`cleanupSafety: "require-bounded"`.
+The callback staging component is capped at 255 bytes as written and under NFC and NFD by
 shortening only an overlong embedded destination tail, while preserving an
 extension when possible. Short callback paths and the final target stay
-unchanged. This workspace owns its contents, unlike the unadmitted sibling
+unchanged. An unusable target basename causes `fallbackFileName` to pass through
+the same basename, character, reserved-device, and length sanitization before it
+is embedded; if neither candidate is usable, the fixed tail `file` is used. The
+completed component is then checked as a direct child before test hooks or the
+producer run. This workspace owns its contents, unlike the unadmitted sibling
 pathname above.
 
 ## Secure temp root
@@ -368,6 +567,7 @@ Consumers that only need this resolver can use the narrow package subpath:
 import {
   resolveSecureTempRoot,
   type ResolveSecureTempRootOptions,
+  type SecureTempRootDescriptorAdapter,
 } from "@openclaw/fs-safe/secure-temp-root";
 ```
 
@@ -392,12 +592,13 @@ type ResolveSecureTempRootOptions = {
   getuid?: () => number | undefined;
   tmpdir?: () => string;
   accessSync?: typeof import("node:fs").accessSync;
-  chmodSync?: typeof import("node:fs").chmodSync;
+  chmodSync?: typeof import("node:fs").chmodSync; // deprecated, never read or called
+  descriptor?: SecureTempRootDescriptorAdapter; // complete bundle; see below
   lstatSync?: (path: string) => {
     isDirectory(): boolean;
     isSymbolicLink(): boolean;
-    mode?: number;
-    uid?: number;
+    mode?: number | bigint;
+    uid?: number | bigint;
   };
   mkdirSync?: (
     path: string,
@@ -416,6 +617,61 @@ the fallback to mode `0o700` where mode bits apply. If it cannot establish that
 state, it throws an ordinary `Error`; there is no native mode or
 `helper-unavailable` branch on this API.
 
+Existing secure directories retain the one-`lstat`/access fast path, with no
+descriptor open or chmod. On POSIX, a directory created by this call is instead
+finalized through a pinned descriptor and must finish at exactly `0o700`, even
+when a privileged caller can access its initial restrictive mode. A concurrent
+recursive-`mkdir` winner is inspected as an untrusted existing directory.
+Broad-mode repair also uses a pinned descriptor; there is no pathname chmod.
+
+Repair and finalization require a known nonnegative safe-integer UID and exact
+bigint device, inode, owner, mode, and directory-type facts. They open with
+`O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK`, verify the descriptor and
+current directory entry against the initial receipt before `fchmod`, then
+verify identity, permissions, and write/search access again before closing.
+Trailing separators are stripped only for entry inspection, preserving filesystem
+roots and symlink-sensitive `..` components. Unknown, numeric, or malformed
+identity facts cannot authorize a mutation. A failed chmod is tolerated only for
+the existing `EPERM`/`EACCES`/`ENOENT` cases when the same exact pinned directory
+has concurrently become safe and accessible; it emits no repair warning.
+
+There is no search-only descriptor or `/proc` fallback. A newly created `000`
+directory that cannot be opened read-only is left in place; the resolver tries
+the secure fallback or throws. Actual Windows uses directory-type and access
+checks and performs no POSIX chmod, regardless of an injected `platform` value.
+Failures keep the ordinary `Error` contract; available underlying repair and
+close failures are retained in `cause`, including paired errors.
+
+The optional descriptor adapter is a complete authority bundle:
+
+```ts
+type SecureTempRootDescriptorAdapter = {
+  lstatSync(path: string, options: { bigint: true }): Pick<import("node:fs").BigIntStats,
+    "dev" | "ino" | "uid" | "mode" | "isDirectory" | "isSymbolicLink">;
+  fstatSync(fd: number, options: { bigint: true }): ReturnType<SecureTempRootDescriptorAdapter["lstatSync"]>;
+  openSync(path: string, flags: number): number;
+  fchmodSync(fd: number, mode: number): void;
+  closeSync(fd: number): void;
+  constants: { O_RDONLY: number; O_DIRECTORY: number; O_NOFOLLOW: number; O_NONBLOCK: number };
+};
+```
+
+Options, adapter functions, and flags are captured synchronously before callbacks.
+On POSIX a complete bundle supplies exact admission and repair observations,
+taking precedence over the legacy `lstatSync` hook. Partial bundles or unavailable
+flags make repair/finalization unavailable. Injecting `lstatSync`, `accessSync`,
+or `mkdirSync` disables the default host descriptor bundle. Injected observations
+also require an explicit `mkdirSync` for creation; supplying a descriptor bundle
+likewise never implicitly authorizes host mkdir. A custom mkdir requires the
+complete descriptor bundle for POSIX finalization. The deprecated `chmodSync`
+option is inert and alone does not disable normal host behavior.
+
+These checks bind chmod to the admitted object and reject observed replacements;
+the returned path is not a retained capability. Pathname access and identity
+checks remain separate syscalls, and another process can replace the path after
+the final check. Applications still need a trusted namespace or OS isolation
+when other processes can mutate it.
+
 ## Common patterns
 
 ### Build something, atomically place it
@@ -440,6 +696,7 @@ import fs from "node:fs/promises";
 
 const r = await writeSiblingTempFile({
   dir: "/srv/cache",
+  producerIsolation: "private-directory",
   writeTemp: async (tempPath) => {
     const handle = await fs.open(tempPath, "w");
     try {

package/node_modules/@openclaw/fs-safe/docs/test-hooks.md

@@ -31,10 +31,17 @@ type FsSafeTestHooks = {
   afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
   beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
   afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterOpenedPathIdentityCheck?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadPathResolution?: (filePath: string) => Promise<void> | void;
+  beforeRootReadFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadFinalPathIdentityCheck?: (filePath: string, handle: FileHandle) => void;
   beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
   beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
   beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
   beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
+  beforeRootStatObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootStatInitialObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootListObservation?: (directoryPath: string, withFileTypes: boolean) => Promise<void> | void;
   afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
   beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
   beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
@@ -49,10 +56,17 @@ type FsSafeTestHooks = {
 | `afterPreOpenLstat` | A pre-open `lstat` has just resolved. Use this to swap a path between validation and open. |
 | `beforeOpen` | The library is about to call `open(path, flags)`. Use this to inject a TOCTOU window. |
 | `afterOpen` | An open just succeeded. Use this to mutate state before the post-open identity check runs. |
+| `afterOpenedPathIdentityCheck` | A standalone local-file or absolute copy-source descriptor matches its pathname and the generic opened-path resolver is about to run. Root reads use their final admission hooks instead. |
+| `afterRootReadPathResolution` | A Root read path was resolved and has not yet entered local-file open admission. |
+| `beforeRootReadFinalFence` | A Root read descriptor passed pre-open/descriptor identity and hardlink checks and is about to enter its single final root/path/canonical-path/root admission fence. |
+| `afterRootReadFinalPathIdentityCheck` | The final pathname-to-descriptor comparison passed and the second root check has not run. This hook is synchronous-only. |
 | `beforeArchiveOutputMutation` | Archive staging is about to create a directory or apply a mode. |
 | `beforeFileStorePruneDescend` | File-store pruning is about to descend into a directory. |
 | `beforeFileStoreSyncPrivateWrite` | A synchronous private-store write is about to mutate its target. |
 | `beforeRootFallbackMutation` | A guarded JS root fallback is about to mkdir, move, or remove. |
+| `beforeRootStatObservation` | `Root.stat()` admitted its exact target and parent and is about to collect returned metadata. |
+| `beforeRootStatInitialObservation` | `Root.stat()` admitted its exact parent and is about to inspect the target for the first time. |
+| `beforeRootListObservation` | `Root.list()` admitted its exact selected directory and is about to collect names and optional metadata. |
 | `afterPinnedWriteFallbackRename` | A fallback rename committed and post-commit identity checks have not run yet. |
 | `beforeSiblingTempWrite` | A sibling temp file exists and its writer is about to run. |
 | `beforeSidecarLockSnapshotOpen` | A sidecar lock was inspected and is about to be opened for a bounded snapshot read. |

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

@@ -22,6 +22,8 @@ function withTimeout<T>(
 
 If `timeoutMs` is `0`, negative, `Infinity`, or `NaN`, the helper is a no-op and simply awaits the original promise.
 
+Finite delays above Node's single-timer limit (2,147,483,647 ms, about 24.9 days) are scheduled in bounded intervals without expiring early. The timer is still cleared if the wrapped promise settles first.
+
 ## Examples
 
 ### Simple ceiling

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

@@ -45,7 +45,7 @@ type DirEntry = PathStat & {
 };
 ```
 
-Returned by `Root.list(rel, { withFileTypes: true })`. Includes every
+Returned by `Root.list(rel, { withFileTypes: true })` and [`Root.entries()`](entries.md). Includes every
 `PathStat` field plus the entry's `name`.
 
 ## `BasePathOptions`
@@ -99,6 +99,7 @@ type ReadResult = {
 type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
 
 type RootDefaults = {
+  assertBeforeMutation?: () => void;
   denyMutations?: DenyMutationPolicy;
   durable?: boolean; // default true for write/create/writeJson/createJson/append
   hardlinks?: "reject" | "allow";
@@ -107,7 +108,8 @@ type RootDefaults = {
   mode?: number;
   nonBlockingRead?: boolean;
   renameIdentity?: RenameIdentityPolicy;
-  symlinks?: "reject" | "follow-within-root";
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
+  mutationSymlinks?: MutationSymlinkPolicy;
 };
 
 type DenyMutationPolicy = {
@@ -121,20 +123,20 @@ type RootOptions = {
 };
 ```
 
-`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these. `denyMutations` is the exception: root and per-call deny entries are merged.
+`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these. `denyMutations` and `assertBeforeMutation` are exceptions: deny entries are merged, and the root authority assertion runs before the per-call assertion.
 
 ## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
+type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity" | "mutationSymlinks"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };
-type RootCopyOptions = Pick<RootDefaults, "denyMutations" | "maxBytes" | "mkdir" | "mode"> & {
+type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "maxBytes" | "mkdir" | "mode" | "mutationSymlinks"> & {
   sourceHardlinks?: "reject" | "allow";
 };
-type RootOpenWritableOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
+type RootOpenWritableOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mkdir" | "mode" | "mutationSymlinks"> & {
   writeMode?: "replace" | "append" | "update";
 };
 type RootWriteJsonOptions = RootWriteOptions & {
@@ -145,23 +147,28 @@ type RootWriteJsonOptions = RootWriteOptions & {
 type RootAppendOptions = RootWriteOptions & {
   prependNewlineIfNeeded?: boolean;
 };
-type RootMoveOptions = Pick<RootDefaults, "denyMutations"> & {
+type RootMoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
   overwrite?: boolean;
 };
-type RootRemoveOptions = Pick<RootDefaults, "denyMutations">;
-type RootMkdirOptions = Pick<RootDefaults, "denyMutations">;
+type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
+type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
 ```
 
 Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.
 
-## `SymlinkPolicy` / `HardlinkPolicy`
+## `SymlinkPolicy` / `MutationSymlinkPolicy` / `HardlinkPolicy`
 
 ```ts
-type SymlinkPolicy = "reject" | "follow-within-root";
+type SymlinkPolicy = "reject" | "follow-within-root" | "follow-parents-within-root";
+type MutationSymlinkPolicy = "reject" | "follow-parents-within-root";
 type HardlinkPolicy = "reject" | "allow";
 ```
 
-The two policy unions you'll see throughout. `"reject"` is conservative; `"follow-within-root"` allows symlinks whose final target is still inside the root; `"allow"` (hardlinks only) is permissive. Defaults for both symlinks and hardlinks are `"reject"`; switch hardlinks to `"allow"` only when you intentionally accept hardlink aliases.
+`"reject"` is conservative; `"follow-within-root"` allows symlinks whose final target is still inside the root; `"allow"` (hardlinks only) is permissive. Defaults for read symlinks and hardlinks are `"reject"`; switch hardlinks to `"allow"` only when you intentionally accept hardlink aliases.
+
+`"follow-parents-within-root"` allows contained parent directory aliases while
+rejecting final symlinks. Mutation policy is opt-in and independent of read
+policy; omission preserves each mutation method's existing behavior.
 
 ## `FsSafeErrorCode` / `FsSafeErrorCategory`
 

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

@@ -72,10 +72,57 @@ Unreadable directories are skipped rather than throwing, but every skipped direc
 `Root.walk(rel, options)` is the root-bounded counterpart to these standalone
 inventory helpers. It yields `{ relativePath, kind, size }` incrementally and
 accepts `maxDepth`, `maxEntries`, `symlinkPolicy: "skip" |
-"follow-within-root"`, and an `AbortSignal`. The default budget behavior yields
+"follow-within-root"`, `order: "sorted" | "filesystem"`, and an `AbortSignal`. The default budget behavior yields
 one `kind: "truncated"` marker and ends; pass `limitBehavior: "throw"` for a
 typed `FsSafeError("too-large")` instead.
 
+For followed symlinks, both `kind` and `size` describe the resolved target.
+
+The default `order: "sorted"` visits each directory's names in lexicographic
+order before descending depth first. It reads and sorts all names in each
+visited directory. With `maxEntries`, it prepares small metadata batches capped
+by the remaining global entry budget. Every batch stops at the first directory
+or symlink, so recursive descent cannot spend a budget already used by later
+siblings. An early `break` may leave metadata from the current batch unused;
+the total still stays within `maxEntries`. Filtering requires metadata and
+consumes the entry budget, including entries skipped by the filter.
+
+Without `maxEntries`, sorted walks reuse a full directory metadata snapshot
+from the `Root.list()` owner. This preserves the existing fast complete-scan
+behavior and its snapshot semantics: changes made after a directory is listed
+do not alter its already-captured entries. Supply an entry budget or use
+filesystem order when metadata work must remain incremental. Sorted entries
+describe the observations captured in their directory snapshot or batch.
+
+Use `order: "filesystem"` when a wide directory must not be fully enumerated:
+
+```ts
+for await (const entry of capability.walk("", {
+  order: "filesystem",
+  maxEntries: 128,
+  symlinkPolicy: "skip",
+})) {
+  consume(entry);
+}
+```
+
+This order follows the filesystem's directory stream and is not deterministic.
+It reads one entry at a time, including one name of lookahead to distinguish an
+exactly exhausted budget from truncation. The lookahead does not request full
+entry metadata from fs-safe, and an early `break` does not prefetch later child
+metadata. If a filesystem does not supply directory-entry
+types, Node may classify that one extra entry with a synchronous `lstat`.
+Handles close on completion, truncation, cancellation, errors, or an
+early `break`. Both orders keep the same depth-first traversal, entry filtering,
+and truncation rules. Cancellation is checked between entries, with event-loop
+handoffs between budgeted sorted batches. Root and directory checks and admitted
+child metadata reads are synchronous; no mode can interrupt a filesystem
+syscall already in progress or the sorted mode's name sorting.
+
+If a thrown walk failure and directory close both fail, disposal throws a
+`SuppressedError` with the close failure in `error` and the original failure in
+`suppressed`, preserving both causes.
+
 `entryFilter` is evaluated for each resolved file, directory, or other entry:
 
 ```ts
@@ -109,10 +156,12 @@ Every examined directory entry consumes `maxEntries` before filtering, so
 `"truncated"` markers describe already-reached state and do not authorize
 further descent.
 
-The pure-Node path validates every directory canonically inside the root,
-revalidates each listing through the normal `Root.list()` boundary, and tracks
-canonical directories to stop symlink cycles. It does not hold a descriptor
-for the entire tree, so it is not a process sandbox against a hostile peer that
+The pure-Node path validates every directory through the Root boundary, pins
+its exact identity, and rechecks it and the Root identity around each metadata
+batch or individual filesystem-order observation. Sorted batches contain no
+await or caller code between their before/after checks. It tracks canonical
+directories to stop symlink cycles.
+Neither mode holds a descriptor for every path component, so it is not a process sandbox against a hostile peer that
 can continuously swap and restore directories. Each individual lookup retains
 the documented Node `Root` boundary checks.