@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -0,0 +1,204 @@
+---
+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;
+  maxDepth?: number;
+  shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
+};
+
+function probePathSuffixAliasesSync(
+  options: ProbePathSuffixAliasesOptions,
+): boolean | undefined;
+```
+
+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.
+
+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.
+`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.
+
+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.
+
+## 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 | `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
+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,11 +36,15 @@ 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?)`
 
-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
@@ -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");
@@ -110,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 {
@@ -196,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. 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()` 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
 
@@ -68,11 +68,34 @@ 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. 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
+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.
+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
 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 +109,31 @@ 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.
+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
+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
 
@@ -139,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
 
@@ -156,15 +197,60 @@ 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.
-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
+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
+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; 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 .NET/`icacls` compatibility fallback.
+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.
 

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.

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

@@ -20,12 +20,20 @@ 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.
 
 ## `path` and `advanced`
 
+`safePathSegmentHashedV2` encodes every trimmed install ID with domain-separated
+SHA-256 into a fixed lowercase segment. The legacy `safePathSegmentHashed` keeps
+its existing output but can alias distinct IDs. See [install paths](install-path.md)
+for the exact encoding and migration contract.
+
 The lexical path surface additionally exports `isNodeError`,
 `isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
 `resolveSafeRelativePath`, `splitSafeRelativePath`, and
@@ -38,6 +46,43 @@ 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 `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`
+provide exact directory observations without owning a descriptor or a mutation.
+The assertion accepts an observed path and optional expected canonical path;
+see [directory identity](directory-identity.md).
+
+`overwriteFileHandle` and `OverwriteFileHandleOptions` provide in-place byte
+replacement through a borrowed regular-file handle. Its once-only `beforeWrite`
+callback admits the complete write and any required best-effort rollback after
+prefix preparation. See [in-place writes](in-place-write.md).
+
+`probePathCaseInsensitiveSync` and `ProbePathCaseOptions` are advanced exports
+for local ASCII-case observations. An unavailable answer remains `undefined`;
+the caller selects any fallback. See [path case probing](path-case.md).
+
+`resolvePathPrefixSync` and `ResolvedPathPrefix` separate a canonical existing
+path prefix from its raw unresolved suffix after physical symlink traversal.
+See [resolving path prefixes](path-prefix.md).
+
+`probePathSuffixAliasesSync` and `ProbePathSuffixAliasesOptions` compare selected
+missing relative suffixes beneath an existing directory using bounded temporary
+directory probes. The caller owns Unicode-pair policy, caching, and the fallback
+for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
+
+## Guest source
+
+`@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
+`GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE`,
+`GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE`, and
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON`. These are source and protocol
+constants; the caller launches the Python guest and owns authorization and
+transport lifetime. See the [guest protocol](guest.md).
+
 ## `json` and `store`
 
 Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
@@ -89,8 +134,12 @@ The durability surface also exports the synchronous strict
 `EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
 `PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
 `PublishFileExclusiveFailurePhase`,
-`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`, and
-`Sha256FileResult`.
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`,
+`Sha256FileSyncInput`, `Sha256FileOptions`, and `Sha256FileResult`.
+`sha256FileSync()` provides synchronous pathname or borrowed-descriptor hashing
+with the same byte-budget and digest-result contracts as `sha256File()`.
+`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. 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