@openclaw/openshell-sandbox 2026.9.4 → 2026.9.5

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

@@ -35,6 +35,7 @@ type ExternalFileWriteOptions<T = void> = {
   maxBytes?: number;
   mode?: number;
   staging?: "workspace" | "sibling"; // default: "workspace"
+  producerIsolation?: "private-directory"; // opt-in for sibling staging
   fallbackFileName?: string;          // safe staged-name fallback
 };
 
@@ -60,7 +61,7 @@ hazards but does not trim Windows-normalized trailing dots or spaces; reject or
 rewrite those when cross-platform filename uniqueness matters.
 `staging: "workspace"` passes the sanitized basename to the producer.
 `staging: "sibling"` embeds that basename in its randomized temporary name.
-When the complete temporary component would exceed 255 bytes under NFC or NFD,
+When the complete temporary component would exceed 255 bytes as written or under NFC or NFD,
 only the embedded tail is shortened, preserving its extension when possible;
 short callback paths remain unchanged. The final target and returned `path` use
 the destination basename, sanitized
@@ -68,16 +69,26 @@ when needed as described above. Guarded temporary files used only inside
 fs-safe have independent names so their length does not grow with the
 destination basename.
 
+On Windows, `rootDir` and every target parent reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`. A colon in only the requested basename still follows
+the documented portable filename sanitization above instead of being treated
+as a raw stream path. Ordinary colon-bearing POSIX roots and parents remain
+valid.
+
 ## Choosing a staging mode
 
 `staging: "workspace"` is the default. The producer writes in private temp
 storage, then fs-safe copies through the guarded root boundary. Choose it when
 the temp and destination filesystems may differ, or when an externally produced
 partial file must never appear in the destination directory. The final target
-still appears only after guarded finalization.
+still appears only after guarded finalization. Its internal `tempFile()` does
+not expose `cleanupSafety` through this API and uses compatible cleanup, with
+the final check-to-pathname-recursive-removal gap documented in
+[`tempFile`](temp.md#tempfile).
 
-`staging: "sibling"` gives the producer a randomized temp path in the target
-directory. Choose it only when that directory itself is the approved writable
+By default, `staging: "sibling"` gives the producer a randomized temp path in
+the target directory. Choose it only when that directory itself is the approved writable
 boundary and same-filesystem atomic replacement is required. After the callback
 returns, fs-safe pins and validates the staged regular file, rejects hardlinks
 and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
@@ -91,11 +102,48 @@ cleanup retry.
 Sibling staging shares the [callback sibling owner](temp.md#sibling-temp-writes):
 it checks exact pre-open, descriptor, and current-path identities, retains the
 descriptor through publication, and never chmods or reads a replacement by path.
-Cleanup preserves unverified paths, including partial output when the callback
-throws before admission. Native-off and Windows operation remain supported with
-the platform limits and non-atomic rename/unlink identity checks described there.
+Without producer isolation, cleanup preserves unverified paths, including partial
+output when the callback throws before admission. Native-off and Windows
+operation remain supported with the platform limits and non-atomic
+rename/unlink identity checks described there.
 When `mode` is omitted, output-sibling staging preserves the producer's mode.
 
+Add `producerIsolation: "private-directory"` to sibling staging when the
+producer can leave partial output before throwing. It receives an initially
+absent file path inside a private child workspace under the target parent, on
+the target filesystem. Directory cleanup ownership is captured before the
+callback. A callback exception triggers owned workspace cleanup, including
+partial output, subject to directory identity checks and I/O failures.
+After success, an available native helper uses guarded no-replace `Root.move`.
+With native mode off, the helper opens and identity-fences the completed regular
+file, creates the randomized sibling through an atomic no-clobber hard link,
+verifies its temporary two-link state, then removes the private name. Windows
+first transfers the pin to an independently verified sibling descriptor so the
+source name can disappear before workspace cleanup, including on runtimes with
+legacy deletion behavior. If that unlink clears the producer's read-only
+attribute, the retained descriptor restores it and the helper verifies mode and
+identity before continuing. This keeps the handoff zero-copy while preserving the
+ordinary retained-descriptor, mode,
+file-sync, and final-rename lifecycle. Escaping symlinks still fail with
+`path-alias`; filesystems without hard-link support fail with
+`helper-unavailable`.
+
+Exact bigint parent and workspace identities are rechecked before moving
+output to the sibling path to reject observed replacements. Cleanup uses the
+compatible [`withTempFile` ownership contract](temp.md#withtempfile); this
+output option does not expose `cleanupSafety: "require-bounded"`. A moved or
+replaced parent or workspace can leave artifacts, and a workspace substituted
+in the final check-to-pathname-recursive-removal gap can redirect traversal.
+The option does not promise cleanup through a retained directory after a
+rename. The existing Windows and JavaScript pathname-guard limitations remain,
+with no additional permissions or durability guarantee. Native-off publication
+is supported only where hard links are available. See the
+[producer-isolation contract](temp.md#sibling-temp-writes)
+for cleanup and pathname-race details. The option affects only `staging: "sibling"`;
+with `staging: "workspace"`, it is redundant and harmless because the producer
+already uses a private workspace. Omitting it leaves both staging defaults
+unchanged.
+
 ## Why not pass the final path to the library?
 
 If a target parent can be swapped after validation, handing an external library

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

@@ -0,0 +1,64 @@
+# Path case probing
+
+`probePathCaseInsensitiveSync()` observes whether a path's lookup location
+folds ASCII case. It returns `true`, `false`, or `undefined` when the observation
+cannot establish an answer. It does not infer a filesystem property from the
+operating system or cache its result.
+
+```ts
+import { probePathCaseInsensitiveSync } from "@openclaw/fs-safe/advanced";
+
+const insensitive = probePathCaseInsensitiveSync("/srv/data/future.json", {
+  allowTemporaryProbe: false,
+});
+if (insensitive === undefined) {
+  // The application decides how to handle an unavailable observation.
+}
+```
+
+## Lookup location
+
+The input is resolved with Node's `path.resolve()`. Existing targets, including
+directories and final symlinks, are first compared by basename in their parent.
+The probe does not follow a final symlink to decide the target's case behavior.
+Parent aliases are followed. For a missing path, it walks to the nearest existing
+directory whose metadata can be read, without creating the missing directories.
+An unreadable directory listing returns `undefined`.
+
+The probe checks existing directory entries before considering a temporary
+file. Separately listed case variants count as distinct entries even when they
+are hardlinks to the same inode. Identity comparisons retain bigint precision;
+unknown Windows identities do not count as matches. The original entry is
+rechecked after looking up its case variant, so its disappearance or replacement
+invalidates the observation. A detected directory replacement also returns
+`undefined`.
+
+## Temporary probes and cleanup
+
+`allowTemporaryProbe` defaults to `true`. When existing entries give no answer,
+the helper exclusively creates one empty `.fs-safe-case-probe-*` file in the
+selected directory at mode `0o600`. It uses the existing temporary-file owner
+to retain the descriptor and exact cleanup identity. Successful ordinary
+completion removes the probe and closes the descriptor.
+
+Set `allowTemporaryProbe: false` for strictly read-only observation. In that
+mode an empty directory, or one with no useful ASCII-case names, returns
+`undefined` without creating a temporary file. Temporary probing can change
+directory timestamps and trigger filesystem watchers even when cleanup succeeds.
+
+Operational failures, unverified identities, changed entries, and cleanup
+failures return `undefined`. A substituted or hardlinked temporary entry is
+preserved. When cleanup fails operationally, the existing owner retains its
+identity-bound process-exit retry. A creation whose identity cannot be obtained
+may leave an empty file; the helper never guesses cleanup ownership. Therefore
+`undefined` does not promise that no temporary artifact remains.
+
+## Limits
+
+This is a local ASCII-case observation, not a Unicode-normalization test,
+filesystem-wide guarantee, lock, or authorization receipt. Directory enumeration
+and metadata lookups are separate operations. Concurrent changes can invalidate
+or immediately stale a result, and the final identity check and unlink are not
+an atomic conditional deletion. Use temporary probing only where creating a
+temporary file is permitted. The caller retains any admission, serialization,
+fallback, or later mutation policy.

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

@@ -0,0 +1,64 @@
+# Resolving an existing path prefix
+
+`resolvePathPrefixSync()` follows filesystem path components until the first
+missing entry. It returns a canonical existing prefix and the unprocessed
+suffix separately, including dangling symlink targets.
+
+```ts
+import { resolvePathPrefixSync, type ResolvedPathPrefix } from "@openclaw/fs-safe/advanced";
+
+const observed: ResolvedPathPrefix = resolvePathPrefixSync("/srv/data/future/file.json");
+// When /srv/data exists but future does not:
+// observed.existingPath is the canonical spelling of /srv/data.
+// observed.unresolvedSegments is ["future", "file.json"].
+```
+
+The result has three readonly fields:
+
+| Field | Meaning |
+| --- | --- |
+| `absolutePath` | Input anchored to the current directory or Windows drive, with raw path components retained and Windows separators converted to backslashes. |
+| `existingPath` | Existing prefix canonicalized by fs-safe's native-realpath owner. This may be a file when the entire path exists. |
+| `unresolvedSegments` | Components from the first missing entry onward, after expanding any earlier symlinks. Empty when the entire path exists. |
+
+## Physical traversal and missing paths
+
+The helper resolves `link/..` from the link's physical target. It does not use
+`path.resolve()` on the full input or a symlink target, because lexical
+normalization would erase that traversal. Relative inputs use the current
+directory; Windows drive-relative inputs use Node's current directory for that
+drive. A root-relative Windows symlink target retains its containing link's
+drive or share root. Windows junctions and full UNC share roots are supported.
+
+At the first `ENOENT`, traversal stops. A suffix such as
+`missing/../live.sqlite` remains `["missing", "..", "live.sqlite"]`, even if
+`live.sqlite` exists beside the missing component. Dot components, repeated
+separators, and a trailing separator in the unresolved suffix are retained.
+Normalizing that suffix would invent an alias to a file the filesystem cannot
+reach through the missing directory. The caller owns any application-specific
+comparison or prospective-path policy.
+
+## Failures and limits
+
+Only `ENOENT` from component inspection produces a missing suffix. Permission,
+I/O, non-directory traversal, symlink-reading, and final canonicalization
+failures propagate. A vanished symlink that was already observed is an error,
+not an unprocessed missing component. NUL bytes reject with `invalid-path`.
+
+Resolution rejects with `ELOOP` after 64 symlink expansions or a repeated
+resolution state. The state retains exact bigint device/inode identity and
+the remaining suffix, so revisiting a link with a shorter suffix is permitted.
+Traversing through a non-directory, including `file/..`, `file/.`, or `file/`,
+rejects with `ENOTDIR`.
+
+Dot and parent components require the directory's search permission before
+they are collapsed. Native realpath alone does not establish this permission
+on every platform. Empty components from repeated or trailing separators do
+not introduce a `.` lookup.
+
+This is a read-only path observation. It neither pins files nor creates a root
+boundary, authorizes access, or guarantees a consistent snapshot during
+concurrent changes. Results can become stale immediately. Use a guarded Root
+operation for subsequent access to untrusted paths; keep any database ownership,
+cache invalidation, and mutation policy with the caller. Native configuration
+and Bun realpath limitations follow the existing [runtime contract](install.md#bun-runtime).

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

@@ -1,6 +1,6 @@
 # pathScope()
 
-`pathScope()` is an advanced helper with the same boundary semantics as `root()`, but it operates on **absolute paths** the caller already trusts and returns plain `{ ok, path }` results instead of throwing. Use it when you want the boundary check up front before handing an absolute path to another library.
+`pathScope()` prepares absolute paths and returns plain `{ ok, path }` results. `resolve()` and `resolveAll()` check lexical containment without touching the filesystem; `existing()`, `files()`, and `writable()` add the filesystem checks described below. Use it to prepare paths before handing them to another library, whose file-opening and mutation behavior still applies.
 
 ```ts
 import { pathScope } from "@openclaw/fs-safe/advanced";

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

@@ -0,0 +1,159 @@
+---
+title: Path suffix alias probing
+description: "Bounded local observations for selected missing relative path suffixes."
+---
+
+# Path suffix alias probing
+
+`probePathSuffixAliasesSync()` observes whether selected missing relative suffixes
+would alias beneath an existing directory. It returns `boolean | undefined`; it
+does not infer filesystem behavior from the operating system or normalize a path
+into an authorization decision.
+
+```ts
+import { probePathSuffixAliasesSync } from "@openclaw/fs-safe/advanced";
+
+const aliases = probePathSuffixAliasesSync({
+  directory: "/trusted/existing-directory",
+  left: "Reports/Caf\u00e9",
+  right: "reports/Cafe\u0301",
+});
+if (aliases === undefined) {
+  // The caller must choose an explicit ambiguity policy.
+}
+```
+
+Use this for suffixes that do not yet exist. For local ASCII-case observations,
+including an explicit read-only mode, use
+[`probePathCaseInsensitiveSync()`](path-case.md). Suffix probing has no read-only
+mode: a nontrivial observation can create and remove directories and requires an
+approved writable parent.
+
+## API and validation
+
+```ts
+type ProbePathSuffixAliasesOptions = {
+  directory: string;
+  left: string;
+  right: string;
+  shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
+};
+
+function probePathSuffixAliasesSync(
+  options: ProbePathSuffixAliasesOptions,
+): 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
+filesystem observations are needed, the directory is canonicalized and its
+identity is checked; an initial directory alias can be followed.
+
+Suffixes must have the same number of ordinary relative path components. Empty
+components, `.` and `..`, absolute suffixes, NUL characters, and non-string path
+inputs are rejected with `TypeError`. Windows additionally rejects drive-relative
+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.
+
+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
+
+These limits apply to one call and cannot be raised through options:
+
+| 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 |
+| 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 |
+
+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
+exhausted and is not disabled by that exhausted budget.
+
+Candidates are generated lazily, only as needed. The helper does not eagerly
+allocate every possible probe name or consume randomness for unused retries.
+These are count and string-size limits, not a wall-clock guarantee. Synchronous
+filesystem calls, randomness, and caller code can block; the helper cannot
+interrupt them or promise a maximum elapsed time.
+
+## Results and caller policy
+
+- `true`: the suffixes are identical, or the requested observations found aliases.
+- `false`: an observation found distinct entries, or the caller's predicate
+  excluded a pair.
+- `undefined`: no reliable answer was obtained, including filesystem failures,
+  identity changes, exhausted collision candidates or dynamic budgets, generated
+  path limits, or incomplete cleanup.
+
+`undefined` is not evidence of either case sensitivity or aliasing. The helper
+does not cache observations, choose a fallback, reserve the future destination,
+or establish a root-confinement boundary. A result applies only to the local
+observations made during that call, not to every Unicode pair, mount, or later
+filesystem state.
+
+The optional trusted, synchronous `shouldProbeCaseVariants` predicate receives
+NFC-normalized component pairs when they differ and are not equivalent under
+ASCII case folding. Without a predicate, those pairs are eligible for probing.
+It is called in component order. Returning `false` excludes
+that pair and produces `false`; it is caller policy, not a filesystem finding.
+A first-component exclusion needs no probes or randomness. A later exclusion
+can follow earlier mutations, so it does not make the call read-only.
+
+A non-boolean predicate result throws `TypeError`; a predicate exception is
+re-thrown unchanged after cleanup attempts. Cleanup problems do not replace the
+original predicate failure. Do not use an asynchronous predicate or rely on the
+resource limits to bound arbitrary callback work.
+
+## Probe design
+
+The helper works through corresponding components, creating nested directories
+to observe inherited lookup behavior. ASCII-case probes use generated names.
+Normalization probes retain the original non-ASCII spellings while substituting
+suitable ASCII letters. When a generated pair is unavailable, the exact raw pair
+can be tried inside an owned neutral directory. Requested names are never
+materialized directly in the caller's unowned parent.
+
+Generated names are conservatively excluded when their NFC lowercase or uppercase
+forms could collide with either requested component. These folds are only a name
+exclusion rule; they never classify two requested paths as aliases. Short neutral
+and ASCII probe names use at most six characters and are no longer than the
+shorter requested component. Generated normalization pairs are also limited by
+the longer original joined path length. A raw-pair fallback adds a directory
+level; filesystem-specific name or path limits can still make it unavailable.
+
+Probes use normal directory creation and the process umask, preserving inherited
+directory behavior. They do not force mode `0700`, change parent permissions, or
+promise private probe names. Creation and removal can affect directory timestamps
+and filesystem watchers.
+
+## Identity and cleanup limitations
+
+The requested directory, canonical parent, and owned probe chain are rechecked
+with exact bigint filesystem identities. An alternate spelling must identify the
+same ordinary directory, not a symlink or unrelated collision. Existing files,
+directories, and symlinks at a candidate name are not removed to make room.
+
+Cleanup attempts owned directories in reverse order with identity checks and
+non-recursive removal. Nonempty directories and observed replacements are
+preserved. A cleanup failure changes an otherwise boolean result to `undefined`.
+If the first identity observation after a successful creation fails, a directory
+can remain: the helper does not guess ownership to delete it.
+
+This is a pathname-based observation helper, not an atomic filesystem
+transaction. There are unavoidable gaps between creation and the first identity
+observation, and between an identity check and a subsequent syscall. No pinned
+directory handle or atomic conditional deletion closes those gaps. Use a trusted,
+approved writable directory and application-level concurrency control where
+needed; do not use this helper as authorization to access attacker-controlled
+paths.

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

@@ -36,7 +36,11 @@ isPathInside("/srv/uploads", "/srv/uploads-other/x");        // false
 isPathInside("/srv/uploads", "/srv/uploads");                // true (root itself counts)
 ```
 
-The check is platform-aware: on Windows, paths are normalized for case and separator before comparison.
+The check is platform-aware: on Windows, paths are normalized for case and separator before comparison. This is deliberately a string-only, lexical answer; case folding does not prove that two differently cased prefixes name the same directory on a case-sensitive Windows directory. Root operations perform their own filesystem-identity admission when containment depends on case folding.
+It is a lexical comparison, not a filesystem-admission boundary: it does not
+reject Windows alternate data streams or index-allocation aliases. Use a
+filesystem operation such as `root()` when a caller-controlled path will be
+opened or mutated.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 
@@ -54,6 +58,9 @@ type Options = {
 ```
 
 Does not throw on missing inputs — `realpath` failures are absorbed by the underlying `safeRealpathSync`. By default (`requireRealpath: true`) the function returns `false` when either input cannot be resolved. Pass `{ requireRealpath: false }` to fall back to the lexical answer from `isPathInside` instead.
+On Windows it returns `false` for namespace aliases in either raw input or in
+a canonical value returned by `realpath` or the supplied cache. The
+`requireRealpath: false` fallback does not admit those aliases.
 
 ### `isWithinDir(rootDir, targetPath)`
 
@@ -79,12 +86,16 @@ if (real === null) return notFound();
 ```
 
 All `realpath` failures collapse to `null` — there is no distinction between `ENOENT`, `EACCES`, and other I/O errors. Use `fs.realpathSync` directly if you need to branch on the error code.
+This convenience wrapper preserves ordinary Node `realpath` semantics; it is
+not a caller-path admission boundary on its own.
 
 ### `safeStatSync(targetPath)`
 
 Synchronous `stat` that returns `Stats` on success and `null` on any failure,
 including missing paths and permission errors. Use `fs.statSync` directly when
 the distinction matters.
+Like `safeRealpathSync`, it does not apply the pathname-admission policy used
+by the higher-level filesystem boundaries.
 
 ```ts
 const stat = safeStatSync("/srv/uploads/photo.jpg");

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. Secure reads and callers that protect credential-bearing execution require `ownerTrusted === true`.
+`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.
 
 ## Advanced Windows ACL helpers
 
@@ -68,11 +68,27 @@ createIcaclsResetCommand(targetPath, { isDir, env });
 resolveWindowsUserPrincipal(env);
 ```
 
-The fallback Windows inspector calls `icacls.exe <path>` using its supported
-path-only inspection syntax and classifies principals as trusted, world, or
-group. Trusted defaults include the current user, SYSTEM, and Administrators.
-Built-in PowerShell, `icacls.exe`, and `whoami.exe` invocations have a fixed
-30-second per-process deadline. A command failure or timeout returns an
+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
+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
+SIDs in its `principal` fields with normalized rights tokens. Explicit `env` or
+`exec` options retain the query path. Disabled or unavailable native helpers,
+remote or incomplete descriptors, leaf symbolic links, and native query errors
+use the fallback. Explicit ACEs and zero-mask entries also retain the query so
+.NET continues to own its ACE ordering and normalization.
+Structured ACLs containing only canonical SIDs are classified directly from
+the current-user SID without requiring a separate account-name lookup.
+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.
+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
 unverified result (`source: "unknown"`) so callers fail closed. Advanced callers
 that inject a custom `exec` implementation own that executor's deadline.
 Failed owner and ACL inspections retain `error` text and an optional
@@ -86,15 +102,18 @@ 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.
-The parser is on the advanced surface so tests and CLIs can process captured
-`icacls` output without spawning a process.
+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
+unrestricted access; an empty DACL grants nothing. Inherit-only ACEs do not
+apply to the inspected object, and deny ACEs never subtract coarse grants or
+claim effective-access evaluation. Unsupported ACE layouts remain unverified.
 
 When the native binding is available, `inspectPathPermissions()`
 reads the owner and DACL directly with Windows security APIs. It classifies the
 current user, LocalSystem, and built-in Administrators as trusted and reports
 the world/group read/write facts consumed by secure reads. Descriptor forms it
-cannot classify equivalently fall back to the established owner/.NET and
-`icacls` path; `mode: "off"` exercises that fallback deterministically.
+cannot classify equivalently fall back to the structured .NET query; `mode: "off"` exercises that fallback deterministically.
 
 ## Policy-free owner and DACL facts
 
@@ -159,12 +178,37 @@ await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
 On Windows with native support, 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
+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
+includes the cleanup failure.
+
+Directory association checks compare the complete 64-bit volume serial and
+128-bit `FILE_ID_INFO` identity, including on ReFS. If that identity class is
+unavailable, the operation fails closed without a narrower file-index fallback.
+Validation confirms that the created directory is local, its DACL is protected
+from inheritance, and its final public pathname opens the same local directory.
+
+This is a point-in-time pathname association check. The function closes its
+handles before returning; callers must keep the pathname's ancestry trusted
+during subsequent use, including opening SQLite databases in the example above.
+The immediate parent and final directory must not be reparse points. Earlier
+ancestor reparse points can be followed; this API does not reject every reparse
+point in the full ancestry.
+
+Path components ending in a space or period are rejected before filesystem
+operations to avoid differing Win32 and native pathname interpretations. This
+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
 directories through their existing trusted-root creation policy rather than a
 pathname-only compatibility shim. Existing Windows permission inspection still
-retains its .NET/`icacls` compatibility fallback.
+retains its structured .NET compatibility fallback.
 
 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.
 

package/node_modules/@openclaw/fs-safe/docs/positional-read.md

@@ -0,0 +1,63 @@
+# Positional reads
+
+Use `readFileWindowFully()` and `readFileWindowFullySync()` to read a bounded
+window from an already-open file. They fill a caller-owned `Buffer`, completing
+short reads until the buffer is full or the file reaches EOF, and return the
+number of bytes read. They never allocate a payload buffer, close the descriptor,
+or change its current offset.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+import { readFileWindowFully } from "@openclaw/fs-safe/advanced";
+
+const workspace = await root("/srv/workspace");
+await using opened = await workspace.open("large.log");
+const buffer = Buffer.allocUnsafe(4096);
+const bytesRead = await readFileWindowFully(opened.handle, buffer, 8192);
+const window = buffer.subarray(0, bytesRead);
+```
+
+## Signatures
+
+```ts
+type ReadFileWindowOptions = { signal?: AbortSignal };
+
+function readFileWindowFully(
+  handle: import("node:fs/promises").FileHandle,
+  buffer: Buffer,
+  position: number,
+  options?: ReadFileWindowOptions,
+): Promise<number>;
+
+function readFileWindowFullySync(
+  fd: number,
+  buffer: Buffer,
+  position: number,
+): number;
+```
+
+`position` and the exclusive window end (`position + buffer.length`) must be
+non-negative safe integers. Invalid ranges throw `RangeError` before reading.
+A zero-length buffer returns zero without I/O. Reading at or beyond EOF also
+returns zero. If EOF occurs within the window, only the returned prefix is
+written; the remaining buffer bytes stay unchanged. Always slice by the returned
+count before using an unsafe-allocated buffer.
+
+These helpers use the caller's open descriptor directly. They do not establish
+path containment, file identity, file-type admission, or a snapshot of concurrently
+modified contents. Use [`Root.open()`](root.md#reads) to admit untrusted paths,
+and keep the handle open and the buffer available until the operation settles.
+Underlying I/O errors propagate unchanged.
+
+## Cancellation
+
+The async variant accepts `signal`. A pre-aborted signal rejects before I/O.
+In-flight cancellation is checked after the pending read settles and before
+another read starts, preserving the signal's reason. Bytes already read remain
+in the buffer; cancellation does not roll them back. Once the promise settles,
+the caller can reuse the buffer or close its handle without a hidden read still
+running.
+
+For a whole-file read that rejects files exceeding a byte limit, use the
+[bounded descriptor readers](advanced.md#files-and-identity) instead. Positional
+reads stop successfully at the requested window and do not probe for extra data.

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

@@ -47,6 +47,20 @@ fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json
 The sync store intentionally exposes a smaller surface: path resolution,
 lenient reads, and atomic text/JSON writes.
 
+Sync directory modes remain repair-compatible on POSIX, but repairs are applied
+only through an exact-identity, no-follow directory descriptor after the store
+root and admitted parent name are revalidated. Root or component swaps fail
+without chmodding the substituted directory. Matching modes take the no-open
+fast path. Windows uses its existing `mkdir` mode request plus exact directory
+identity checks and never falls back to pathname chmod.
+
+On Linux, Node offers no portable search-only descriptor that can also be
+`fchmod`ed. A mismatched directory without effective read access—including one
+created under an owner-read-removing umask—fails closed with
+`permission-unverified`. Supported macOS x64/arm64 hosts additionally try
+`O_SEARCH` when the directory remains searchable; an inaccessible directory
+still fails rather than restoring the pathname race.
+
 ## See also
 
 - [`fileStore`](file-store.md) — full store API.