@openclaw/openshell-sandbox 2026.10.5-beta.4 → 2026.10.10-beta.1

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

@@ -5,6 +5,17 @@ description: "The platform-specific native bindings, fd-relative beneath model,
 
 # Native architecture
 
+Windows native realpath calls and handle-bound canonical-name checks share one
+native resolver. It keeps DOS-name resolution first and uses normalized NT names
+on the same handle only after `ERROR_ACCESS_DENIED` in an AppContainer. Ordinary
+process errors retain their original code and identity. AppContainer support
+requires the addon; native-off or unavailable membership leaves Node EPERM
+unchanged without a subprocess probe. Drive-root translation is
+uncached and fail-closed; see the [AppContainer limits](permissions.md#advanced-windows-acl-helpers).
+
+See [platform filesystem capabilities](platform-capabilities.md) for Linux
+write leases, public Darwin ACL facts, and Windows test fixtures.
+
 `@openclaw/fs-safe` uses native bindings that supply mechanisms Node does
 not expose directly. The Rust layer is deliberately not a second policy engine.
 TypeScript owns trusted-root selection, path validation, archive filtering,
@@ -14,12 +25,46 @@ platform syscall sequence that can preserve the boundary.
 
 Every operation that has an equivalent safe Node implementation keeps that
 guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
-run postinstall code, or fetch binaries at runtime. Seven exact-version optional
+run postinstall code, or fetch binaries at runtime. Exact-version optional
 packages are filtered by OS, CPU, and Linux libc, so an installation receives
-only its matching prebuilt binding.
+only its matching prebuilt binding. Windows ships both x64 and ARM64 MSVC
+bindings; selection follows the Node process architecture. An x64 Node process
+on Windows ARM64 uses the x64 binding under emulation.
 Native-only operations fail explicitly
 instead of substituting a weaker implementation.
 
+## FreeBSD 14.4 and newer
+
+The FreeBSD x64 and arm64 packages provide native anonymous pipes, descriptor
+close and POSIX canonicalization. The larger Linux/macOS/Windows filesystem backend is excluded
+from these binaries: its Unix gates contain platform-specific resolver, clone,
+copy, observation and cleanup implementations. FreeBSD does not export stubs for
+those operations. In `auto`, each operation selects its existing guarded JavaScript
+or WASM backend; in `require`, a missing required capability fails with
+`helper-unavailable`. Pure JavaScript APIs retain their ordinary behavior.
+
+| Native capability | FreeBSD binding |
+|---|---|
+| `createPipe`, `closeOwnedFd`, `canonicalizePath` | Implemented; real pipe, descriptor and pathname syscalls |
+| Beneath open/create/mkdir/link, replace/no-replace rename and identity-fenced rename | Absent; guarded fallback where supported |
+| Directory observations, retained files/symlinks, entry publication, owned-tree and root removal | Absent; guarded fallback or explicit native-only rejection |
+| File/tree clone, native copy/hash, archive inspection/extraction and buffer readers | Absent; JavaScript/WASM fallback where supported |
+| Native watch | Absent; polling fallback in `auto` |
+| Darwin ACL and Windows security/identity methods | Not applicable |
+
+The release workflow builds inside FreeBSD 14.4 VMs and checks installed-package
+behavior on the main thread and a real Worker. ARM64 uses QEMU CPU emulation
+with a real FreeBSD kernel. This is not a Linux cross-build runtime test. Build
+locally on FreeBSD with `pnpm native:build:freebsd`; the JavaScript/WASM distribution
+can be prepared separately with `pnpm build`. There is no qualified FreeBSD Bun
+artifact in the runtime matrix. FreeBSD x64 installed-package proof covers npm
+and pnpm. FreeBSD arm64 covers npm only because pnpm does not publish a native
+binary for that target. CI prepares the ARM64 proof harness dependencies on Linux
+and syncs them into the VM; consumer installations and runtime proof run inside
+FreeBSD, without running pnpm there.
+Reopening pipe descriptors through `/dev/fd` requires the standard `fdescfs`
+mount there; the VM proof mounts it before testing reopen, inheritance and EOF.
+
 ## The beneath model
 
 A trusted directory descriptor is the capability. Native operations accept
@@ -41,9 +86,23 @@ validated Root handle
 The TypeScript layer validates and decides. The native layer never decides
 whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
+Ordinary recursive `Root.mkdir()` calls retain the exact existing parent and
+every opened missing component for the duration of one synchronous native walk.
+Each creation is descriptor-relative, followed by fresh Root, retained-parent,
+child identity and canonical-name checks before the next component. Explicit
+mutation policies, callbacks, private permissions, aliases and bindings without
+the required child-open capability retain their existing admission paths.
+
 - Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
   `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
   Without `openat2`, beneath opens use the [guarded fallback](#linux-without-openat2).
+  Regular-file copies with `clone: "auto"` also recover when `FICLONE` returns
+  `EAGAIN` or `EIO`, as can happen for dirty extents on ZFS. Recovery requires
+  successful identity-checked removal of the unpublished exclusive clone target
+  before the native ordinary-copy path creates a new stage. `clone: "always"`
+  still fails when cloning fails. Ordinary-copy I/O errors, clone normalization
+  errors, and cleanup failures remain terminal; generic `EIO` is never a retry
+  signal.
 - macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
   components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
   pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
@@ -71,10 +130,21 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   use `GetSecurityInfo`; private directories receive their protected DACL in
   an exclusive, handle-relative `NtCreateFile` call. Their created handles remain
   open through ACL and pathname-association checks and own any failure cleanup.
+  Admitted, resolved absolute paths use extended-length Win32 spelling for
+  pathname calls, including internal staging and public-name verification;
+  relative child names remain relative to retained handles. Long paths retain
+  the same alias validation, ACL checks, identity fences and cleanup ownership.
+  Already-admitted namespace spellings pass through unchanged, including
+  filesystem-drive paths using `\\.\`; the encoder does not admit or reject paths.
   N-API descriptors cross into and out of
   this layer only through the host executable's paired libuv descriptor bridge;
   missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
   or add-on CRT descriptor namespace.
+  `Root.copyIn` uses the same ReFS integrity, sparse-file, and cluster-aligned
+  block-clone operations as tree cloning, through retained source and destination
+  parent handles. The exclusive stage enters the existing guarded publication
+  path; transfer failures retain its cleanup receipt. It does not inherit the
+  tree API's source metadata policy.
 
 The internal macOS `inspectDarwinAcl(fd)` capability reports `absent`, `empty`,
 or `present` for the opened object's extended ACL. It synchronously borrows the
@@ -269,7 +339,8 @@ not bypass the byte limit.
 ## Mode semantics
 
 See [Native helper policy](native-helper.md#modes) for the `auto`, `require`, and
-`off` contracts and cached loader behavior.
+`off` contracts and cached loader behavior. See [What needs the native binding](#what-needs-the-native-binding)
+for the exceptions to fallback availability.
 
 `sha256FileSync()` is a synchronous Node implementation in all three modes and
 does not load the binding. Use asynchronous `sha256File()` for native hashing
@@ -281,8 +352,76 @@ Features without a safe fallback, including no-clobber
 when native support is absent or off. Staging is currently Linux/macOS only and
 rejects Windows with `unsupported-platform`.
 
+For an ordinary direct child, native `Root.mkdir()` retains the already-admitted
+Root directly instead of running a parent-creation walk. A missing portable
+single-component name also skips general alias resolution after a fresh Root
+identity check and no-follow missing-entry observation; retained Root and child
+identity checks still surround creation. Its short descriptor
+open, creation, identity checks, and close are synchronous; the public method
+remains asynchronous. Root and child pathname/canonical identities are checked
+before success. Ordinary portable paths with existing canonical parents retain the admitted
+parent directly. A fresh exact parent snapshot must match its beneath-opened
+descriptor; parent, child and Root name/identity checks still surround creation.
+Ordinary missing parents use the retained descriptor walk described above when
+the binding can create and open a child together. Aliases, private creation,
+mutation policies, callbacks and older bindings retain their existing admission
+paths. Policy-free `ensureRoot()` verifies the
+retained native Root directly. In `off` and `auto`, ordinary `Root.mkdir()` keeps
+its metadata-only creation syscall in the synchronous guard sequence; supplied
+mutation callbacks, mutation policies, and private creation retain their existing
+asynchronous path. Both public methods continue to return promises.
+
+Native removal and moves also retain Root synchronously and reuse that descriptor
+when Root is an immediate parent. Nonrecursive removal keeps its own leaf path,
+including fresh policy, identity and post-removal checks; recursive traversal
+retains its directory, mount, budget and cancellation checks. Neither optimization
+changes the descriptor-relative mutation or atomic no-replace mechanism.
+
+Ordinary `Root.ensureRoot()` in `require` can combine retained-root opening,
+exact identity/metadata/canonical observations, the final named Root fence and
+checked close in one native call. The initial JavaScript Root identity fence
+remains before native lookup. Verification and close failures retain both errors;
+an unavailable native observer hands its still-open descriptor to the existing
+guarded observation route. Private or policy-bound calls keep their admission.
+
+Writable opens without an explicit mutation policy attempt the existing-file
+handle path before creating parents. Policy-bound opens first prepare the parent
+receipt needed to select the file.
+In `require`, missing files and parents still use native confined creation;
+existing files keep their guarded Node handle path, identity fences and hardlink
+checks. Required creation capabilities are checked even when the file exists.
+
+For ordinary portable missing-file paths with an existing canonical parent,
+native writable creation retains that parent's exact identity through beneath
+admission. An absence observation selects exclusive native creation; an entry
+that appears concurrently returns to the checked existing-file open. The public
+FileHandle handoff and all post-open identity, link-count and canonical checks
+remain in place. Explicit policies, authority callbacks, aliases and missing
+parents retain their full admission path.
+
+Recursive removal in both implementations retains exact directory identities
+at admission. Repeated fences use ordinary numeric stats only when both captured
+identity components are safely representable; larger identities keep bigint
+observations, and unknown Windows components receive the existing bounded exact
+retry. Every directory identity and canonical-path observation remains in place.
+
+Native publication retains Root through synchronous descriptor open/close and
+checks canonical staging directories against their retained descriptors. Older
+bindings keep the existing guarded directory verification. Owned-descriptor
+staged buffers up to 64 KiB can write synchronously when no mutation assertion is
+configured; direct-publication buffers, larger buffers, streams, and assertion-bearing writes keep their
+asynchronous path. Publication, permission, and post-operation identity checks
+remain unchanged.
+
+Asynchronous temp workspaces create their exclusive child relative to the
+retained cleanup parent when the binding provides that operation. The returned
+descriptor remains owned through the existing mode, parent, ancestry and final
+pathname/descriptor checks. Collisions retry with a fresh random name and never
+adopt or remove the existing directory. Capability probing still completes before
+creation. Synchronous creation and older bindings retain their existing routes.
+
 Windows owner/DACL inspection, private-directory creation, and secure-file
-inspection support [PowerShell fallbacks](install.md#windows-security-fallback)
+inspection support [Windows helper fallbacks](install.md#windows-security-fallback)
 in `auto` and `off`. `require` rejects missing capabilities, and native operation
 failures are terminal.
 
@@ -312,6 +451,78 @@ read metadata behavior are unchanged. Missing Windows pathname identity still
 requires a guarded path reopen and comparison with the original retained file;
 that fallback does not apply to POSIX no-read modes.
 
+### Windows buffered-write cost
+
+`Root.write(..., { durable: false })` skips durability synchronization, but still
+stages and atomically replaces the file, admits the existing destination, and
+checks the root, parent, published pathname and retained descriptor identities.
+Raw Node writes truncate the destination in place and are not equivalent work.
+
+A [Windows x64 measurement](https://github.com/openclaw/fs-safe/actions/runs/38335844371)
+of source revision `fe216e22` used Node 24.21.0, a 16-logical-processor hosted
+runner, and 23-byte replacements. Across 21 samples of 100 writes, uninstrumented
+median sample means were 1.912 ms in `off` and 1.233 ms in `require`; their raw
+Node controls were 0.246 ms and 0.255 ms. Paired raw/raw A/A ratios were 1.011
+and 1.009. These are observations on that runner, not latency guarantees or a
+same-process comparison between native modes.
+
+Separate instrumentation recorded every Node filesystem and native binding call
+over 101 warmed 22-byte replacements. The following times are median cumulative
+microseconds per write for each call family; instrumentation adds overhead and
+these rows must not be substituted for the uninstrumented timings above.
+
+| Call family | `off` calls / µs | `require` calls / µs |
+|---|---:|---:|
+| Canonicalize pathname (`realpathSync.native`) | 14 / 797 | 4 / 265 |
+| Exact file and directory metadata (`lstat`, `stat`, `fstat`) | 41 / 365 | 22 / 166 |
+| Node asynchronous open | 2 / 272 | 1 / 74 |
+| Native beneath open: parent, stage, published file | 0 / 0 | 3 / 174 |
+| Native parent observation | 0 / 0 | 1 / 45 |
+| Write payload | 1 / 95 | 1 / 50 |
+| Replace by rename | 1 / 199 | 1 / 173 |
+
+The native stage creation accounted for about 141 µs of its beneath-open total;
+the published-file reopen accounted for about 22 µs. Native rename uses
+handle-relative `NtSetInformationFile`, not `MoveFileEx`. Neither mode invoked
+the security helper, queried ACLs, changed mode, or flushed a file in these
+non-private, non-durable writes. Path and identity observations explain much of
+the remaining cost; a hidden helper process or durability flush does not.
+
+These measurements did not isolate antivirus/indexer time inside filesystem
+calls and do not establish a universal NTFS lower bound. Storage, pathname depth,
+Windows version and security software can change the result. Repeated identity
+observations fence different admission and publication boundaries; their count
+alone does not establish that an observation can safely be removed.
+
+## What needs the native binding
+
+In `off` and missing-binding `auto`, these capabilities are unavailable. Other
+APIs keep their guarded fallback; the [delta table](#javascript-fallback-guarantees-and-delta)
+describes its strength. Installing a binding does not add support on an excluded
+platform or filesystem.
+
+| API or option | Binding requirement without a fallback |
+|---|---|
+| `Root.move()` with `overwrite: false` (the default); `replaceDirectoryAtomic()` | `helper-unavailable`; atomic no-replace publication cannot use check-then-rename. |
+| `stageFileInDirectory()`, `retainSymlinkInDirectory()` | Linux/macOS: `helper-unavailable`; other platforms: `unsupported-platform`. |
+| `retainEntryForPublication()` | Linux/macOS/Windows: `helper-unavailable`; other platforms: `unsupported-platform`. |
+| `retainFileInDirectory()` | Windows retention only; returns an unsupported admission with `helper-unavailable` rather than throwing. |
+| `createPipe()` | Linux/macOS/FreeBSD: `helper-unavailable`; other platforms: `unsupported-platform`. |
+| `tryAcquireWriteLease()` | Linux: `helper-unavailable`; other platforms: `unsupported-platform`. |
+| `createCloneSource()`; `copyTree()` or `Root.copyIn()` with `clone: "always"` | `helper-unavailable`; synchronous `copyRootFileSync()` / batch copying with `clone: "always"` reports `unsupported-platform`. Ordinary automatic byte copying remains available. |
+| `readCloneFileMetadata()`; `inspectDarwinAcl()` | macOS: metadata reading throws `helper-unavailable`; ACL inspection returns `{ kind: "unknown", reason: "helper-unavailable" }`. Elsewhere, they return unsupported/unknown facts. |
+| `Root.copyIn()` with `sourceSymlinks: "copy-link"` | macOS/Windows: `helper-unavailable`; Linux/FreeBSD retain the guarded literal-link path. |
+| `watch()` with `mode: "events"` | `helper-unavailable`; `mode: "auto"` uses polling. |
+| Temp workspace/file helpers with `cleanupSafety: "require-bounded"` | `helper-unavailable`; the default `"compatible"` cleanup remains available. |
+| Private creation on macOS | `helper-unavailable` for descriptor ACL admission: `createDirectory[Sync]()` / `createFileSync()` and Root creation with `private: true`, `Root.createJson()` and `Root.ensureRoot()` with `private: true`. |
+| Windows test hooks `holdWindowsSharingLock()`, `setWindowsFileAttributes()`, `readWindowsFileExtents()` | Windows: `helper-unavailable`; other platforms: `unsupported-platform`. |
+
+`preserveMetadata: true` does **not** require native support in `auto` or `off`:
+see [copy metadata and source links](writing.md#copy-metadata-and-source-links)
+for timestamp precision and Windows attribute differences. Archive fallbacks
+include bundled WASM, and Windows security fallbacks use the packaged
+prebuilt .NET Framework helper; neither requires the optional native binding.
+
 ## JavaScript fallback guarantees and delta
 
 Policy-bound parent creation can refresh exact directory facts through the
@@ -345,20 +556,70 @@ See [Root containment guarantees](security-model.md#containment-guarantees-by-pl
 | Zstd/bzip2 TAR | Rust streaming decode and fd-relative output creation. | Bundled WASM codecs feed the shared Rust TAR parser, then guarded private staging and the same merge policy; no optional codec dependency. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |
 | `rename-noreplace` | Atomic platform no-replace rename; Linux `auto` file publication can use identity-checked, non-crash-atomic link/unlink when unsupported. | Unsupported; no emulation by check-then-rename. |
-| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. Secure-file reads query the borrowed open descriptor and compare its 32-bit volume serial and 64-bit file-index projection with Node's bigint receipt. | The packaged PowerShell/C# bridge preserves raw facts and inspects the borrowed descriptor for secure reads, with the same Node identity comparison; its command failures reject. Structured .NET pathname reporting retains its separate compatibility query. |
-| Windows private directory | Creation-time protected DACL. | The packaged PowerShell/C# bridge applies the protected DACL at creation and retains exact handles through identity validation and failure cleanup. Command failures reject. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. Secure-file reads query the borrowed open descriptor and compare its 32-bit volume serial and 64-bit file-index projection with Node's bigint receipt. | The packaged prebuilt .NET Framework helper preserves raw facts and inspects the borrowed descriptor for secure reads, with the same Node identity comparison; its command failures reject. Structured .NET pathname reporting retains its separate compatibility query. |
+| Windows private directory | Creation-time protected DACL. | The packaged prebuilt .NET Framework helper applies the protected DACL at creation and retains exact handles through identity validation and failure cleanup. Command failures reject. |
 
 Use `off` in CI to keep the fallback contract exercised. Use `require` when a
 deployment depends on the stronger mechanism or a native-only feature; do not
 infer native loading from timing.
 
+## Windows helper build
+
+`pnpm build:windows-helper` builds the portable security executable with the
+.NET SDK pinned by `global.json`, Roslyn deterministic compilation, a fixed
+source path map, no debug symbols, AnyCPU and `Prefer32Bit=false`. The project
+under `native/windows-security-helper/` targets .NET Framework 4.6.2 using
+Microsoft's `Microsoft.NETFramework.ReferenceAssemblies` 1.0.3 and its committed
+NuGet lock file; builds restore in locked mode. CI compares Ubuntu and Windows
+SHA-256 hashes to enforce byte-identical **unsigned** output. Release builds
+repeat this comparison before Authenticode signing on an x64 Windows runner.
+The signing manifest records that the helper's pre-signing SHA-256 equals both
+reproducible build hashes; its signed SHA-256 is checked against the exe inside
+the final npm tarball. Timestamped signatures change the distributed bytes, so
+rebuilding source is expected to reproduce the unsigned hash, not the signed
+file. Both Windows addons and the helper must have a valid, timestamped embedded
+signature from OpenClaw Foundation before signed x64/ARM64 runtime tests and
+release collection. See [release prerequisites](https://github.com/openclaw/fs-safe/blob/main/RELEASE-PREREQS.md#windows-authenticode-signing-one-time-maintainer-setup)
+for setup and the publication-free dry run. The main package includes only
+the exe; the three C# source files remain available in the repository. The separate
+`windows-owner-query.cs` compatibility query preserves the former PowerShell
+query's .NET API sequence, normalization, link behavior, and locality rules;
+the raw security bridge remains independent.
+
+The 4.6.2 target selects modern `System.IO` path handling on 4.6.2+ runtimes,
+matching Windows PowerShell 5.1. An executable targeting an earlier framework
+gets legacy handling that rejects extended-length `\\?\` paths with
+"Illegal characters in path." The helper still uses only APIs available in
+.NET Framework 4.0 and the same CLR v4.0.30319; it needs no `.exe.config` sidecar.
+Locked restore pins the `Microsoft.NETFramework.ReferenceAssemblies.net462`
+package to 1.0.3 with its content hash. The raw bridge keeps extended paths out
+of .NET normalization and uses `CreateFileW`; its security checks are unchanged.
+
+Build output is copied beside the source modules for Vitest and beside the
+compiled modules in `dist/`; both use the same module-relative filename.
+`pnpm build` can skip compilation on non-Windows developer machines without the
+SDK, retaining a previously built source-side copy when present. Packing still
+requires the executable. CI and release assembly install the pinned SDK and
+build it, including package smoke tests on other operating systems.
+
+Each invocation still inspects the inherited borrowed handle with
+`GetStdHandle(-10)` and exits. A persistent helper cannot receive replacement
+fds opened later: portable Node exposes neither the underlying OS HANDLE nor
+`DuplicateHandle`. Per-call processes preserve descriptor ownership and all
+existing checks across callbacks, publication, link-count changes, and chmod.
+There is no security-fact cache or pathname substitution for descriptor checks.
+
 ## Loader security
 
 Native initialization runs in the async context captured when fs-safe's loader
 module is evaluated. Import fs-safe during application startup, outside request
 or lease scopes, so the addon's process-lifetime housekeeping cannot retain the
 first operation's `AsyncLocalStorage` stores. Importing still does not load the
-addon: only the first native operation pays the registration cost. Subsequent
+addon: only the first native operation or explicit
+[`await getFsSafeNativeStatus({ probe: true })`](config.md#getfssafenativestatus-options)
+call pays the registration cost. The `config` subpath defers the internal loader
+until status is requested and shares that loader's cache with native operations.
+Subsequent
 operations and their callbacks retain their own caller context. Dynamically
 importing fs-safe for the first time inside a request scope captures that import
 scope instead; this boundary does not clear an already active import context.
@@ -371,9 +632,19 @@ loader conservatively attempts the glibc package and lets normal module loading
 fail into `auto` fallback. The loader requires only the package selected from
 the detected target; it never probes unrelated packages, downloads code, or
 runs a postinstall step. A missing or incompatible binary
-silently selects the JavaScript fallback in `auto`, throws typed
+selects the guarded fallback in `auto`, throws typed
 `helper-unavailable` in `require`, and is never inspected in `off`. Tests reject
 `child_process`, `exec`, or `spawn` usage in the loader.
+Windows security/private-creation fallbacks emit an actionable, path-free
+warning; other fallbacks remain silent. See
+[fallback troubleshooting](native-helper.md#troubleshooting-fallback-warnings).
+
+## Anonymous pipes
+
+The lean [`pipe` subpath](pipe.md) creates native-owned anonymous pipes. Linux and
+FreeBSD use atomic close-on-exec creation; Darwin reports its non-atomic flag
+setup explicitly. Each end must close through its native owner, including when
+a Node stream uses it in a Worker.
 
 ## Related pages
 

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

@@ -42,10 +42,51 @@ POSIX remediation strings shell-quote paths with whitespace or metacharacters
 and protect option-like paths with `--`, so they can be presented as commands
 without letting the inspected pathname add shell syntax.
 
-`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` 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.
+`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 prebuilt .NET Framework helper in `auto` and `off` modes.
 
 ## Advanced Windows ACL helpers
 
+Private Windows DACLs grant full access to the process user, SYSTEM, and
+Administrators. Inside an AppContainer they additionally grant that process
+token's own container SID, with inheritance on directories. Other containers
+and ALL APPLICATION PACKAGES receive no grant. Creation and security inspection
+use the same token identity; a token-query failure rejects the operation.
+Outside an AppContainer the existing descriptors are unchanged. The native
+addon and packaged .NET security helper both enforce this boundary.
+
+When an AppContainer cannot obtain DOS volume names, guarded path operations
+require the native addon. fs-safe resolves the same open handle's normalized NT
+name, then verifies its drive-root prefix before returning the DOS spelling.
+UNC names are translated from the NT network namespace. This preserves long-name
+canonicalization and the existing identity and containment checks without
+granting access to other containers. Drive mappings are queried on each operation.
+Canonicalization resolves relative inputs against the process working directory
+before opening, and UNC inputs accept either Windows path separator spelling.
+APIs that require absolute paths, including `readSecureFile()`, retain that requirement. The current
+container SID is trusted during ACL inspection independently of the object's owner.
+Folder-mounted volumes, volume-GUID inputs, and unmatched drive prefixes fail
+closed with `FsSafeError("path-mismatch")` when DOS resolution is denied.
+AppContainer support requires the native addon. In native mode `off`, or without
+native membership support, a denied DOS-name query retains Node's original
+`EPERM` error unchanged. The JavaScript realpath resolver is not a fallback.
+Outside a sandbox, successful DOS resolution and ordinary errors retain their
+existing behavior, including in native mode `off`.
+
+Only a denied DOS-name query triggers the canonicalizer's in-process token probe.
+The addon caches immutable AppContainer membership across Workers. Canonicalization
+never starts a helper process. In a container, failure to open the path or query
+its normalized NT name also preserves the original error, so existing contention
+handling remains effective. Token-probe failures are typed.
+
+Inside an AppContainer, advanced ACL inspection uses native facts for inherited
+entries and unique full-control allow entries with uniform inheritance flags,
+including fs-safe's private DACL. Operations that require an external helper
+instead fail with `helper-unavailable` when native membership identifies the
+container. Current Node/libuv child-process pipe creation can fail or hang inside
+AppContainers ([nodejs/node#66374](https://github.com/nodejs/node/issues/66374),
+[libuv/libuv#5178](https://github.com/libuv/libuv/issues/5178)); fs-safe must not
+start the .NET helper or a Node helper child there.
+
 The low-level Windows ACL parser and `icacls` command builders live in `@openclaw/fs-safe/advanced`:
 
 ```ts
@@ -69,15 +110,18 @@ resolveWindowsUserPrincipal(env);
 ```
 
 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.
+built-in prebuilt .NET Framework helper query. It runs the packaged
+`windows-security-helper.exe` with arguments `["owner", targetPath]`, without
+starting PowerShell. The query preserves .NET's named-path security lookup and
+ACL normalization, including leaf-link behavior.
 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,
+SIDs in its `principal` fields with normalized rights tokens. An explicit
+`exec` option retains the query path; `env` no longer selects a query executable
+or bypasses native inspection. 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.
@@ -89,6 +133,9 @@ result. The query returns SIDs directly; no translation cache is needed.
 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`).
+Pass-through executors can run the supplied helper command and arguments
+directly; canned-JSON executors use the same parser. `env` remains available for
+principal classification and remediation command construction.
 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.
@@ -178,7 +225,7 @@ Object-specific and other ACE layouts are not guessed: they are omitted,
 `unsupportedAceTypes`, allowing a security-sensitive caller to fail closed.
 Non-Windows systems return `{ status: "unsupported-platform", platform }`.
 Windows prefers the native binding. In native `auto` or `off` mode, a missing
-binding or capability uses the packaged PowerShell/C# bridge with
+binding or capability uses the packaged prebuilt .NET Framework helper 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
@@ -220,13 +267,13 @@ An available native capability runs all queries in one isolated process using
 the current runtime executable. Its resolved native mode is forwarded explicitly;
 Node preload and module-search environment overrides are not inherited. An
 available native query's failure is terminal. In `auto` when the binding or
-capability is absent, or in `off`, one packaged PowerShell process reads the
-path array from stdin and compiles the existing C# bridge once. Native `require`
+capability is absent, or in `off`, one packaged .NET Framework helper process reads the
+path array from stdin. Native `require`
 rejects missing support before launching a process. No route launches one
 process per path or wraps synchronous parent-process queries in promises.
 
 `timeoutMs` defaults to 60,000 and applies to the whole process, including
-startup and fallback compilation. It must be an integer from 1 through
+helper startup. It must be an integer from 1 through
 2,147,483,647. Combined stdout and stderr are limited to 16 MiB. Success waits
 for process exit and both output pipes to close. Timeout and transport failure
 request termination, then retain the existing one-second settlement grace.
@@ -236,7 +283,7 @@ unconfirmed child can still be reading after rejection; the operation returns
 no facts and owns no output files or artifact cleanup. Neither timing out nor
 receiving a successful kill request is reported as confirmed exit.
 
-The PowerShell fallback encodes and budgets each result while collecting it,
+The helper fallback encodes and budgets each result while collecting it,
 instead of retaining every descriptor graph until the entire batch finishes.
 An encoded response that would exceed 16 MiB rejects with `too-large` before
 inspecting later paths. A query failure observed earlier retains its original
@@ -266,7 +313,7 @@ On Windows, this creates the directory and applies a
 protected owner + LocalSystem + Administrators full-control DACL directly with
 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
+packaged prebuilt .NET Framework helper. 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
@@ -300,10 +347,9 @@ pathname-only compatibility shim. Existing Windows permission inspection still
 retains its structured .NET compatibility fallback.
 
 The raw owner/DACL and private-directory fallbacks each emit one path-free
-`FS_SAFE_NATIVE_FALLBACK` warning per process. PowerShell startup and C#
-compilation add overhead to each call; install the native package for frequent
-operations. These routes run the package's readable, fixed scripts under normal
-system PowerShell policy; see the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+`FS_SAFE_NATIVE_FALLBACK` warning per process. A fresh prebuilt helper process
+adds startup overhead to each call; install the native package for frequent
+operations. These routes run the packaged executable under normal system 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
@@ -318,6 +364,9 @@ 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.
+These builders and `formatPermissionRemediation()` throw `helper-unavailable` in
+a known AppContainer: removing inherited grants could revoke the container's
+own access. Ordinary-process commands remain unchanged.
 
 ## Types
 

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

@@ -0,0 +1,81 @@
+# Anonymous pipes
+
+`@openclaw/fs-safe/pipe` exposes a synchronous, native anonymous pipe for
+one-shot input to a child process. Both ends are reopenable through
+`/proc/self/fd/N` on Linux and `/dev/fd/N` on Darwin and FreeBSD. This supports
+programs that open an inherited descriptor as a pathname.
+
+On FreeBSD, reopening through `/dev/fd/N` requires `fdescfs` mounted at `/dev/fd`.
+An administrator can mount it with `mount -t fdescfs fdesc /dev/fd`; pipe creation
+itself does not require that mount.
+
+```ts
+import { createPipe, type OwnedPipeSync } from "@openclaw/fs-safe/pipe";
+
+const pipe: OwnedPipeSync = createPipe();
+try {
+  // Pass pipe.reader.fd as a numeric child_process spawn stdio entry.
+  // Keep both owners alive until their respective users finish.
+} finally {
+  pipe.reader.close();
+  pipe.writer.close();
+}
+```
+
+The frozen result has `reader` and `writer` members of the existing
+`OwnedFileDescriptorSync` type (`readonly fd: number`, `close(): void`, and
+`[Symbol.dispose](): void`) and `readonly atomicCloseOnExec: boolean`.
+Each end closes idempotently through its native owner. A close attempt consumes
+ownership even if it throws; do not retry with a raw close or use the fd again.
+The pair itself does not have a `close` or disposal method.
+
+Linux and FreeBSD create both ends atomically with close-on-exec set.
+Darwin sets the flag on both ends immediately after creation and reports
+`atomicCloseOnExec: false`: a concurrent native fork/exec can inherit an end
+in that short window. No JavaScript async work intervenes, but this is not an
+atomic inheritance guarantee. Partial setup failure closes both ends.
+
+Importing the subpath is lazy and does not load the addon or the secret-file
+modules. Calling `createPipe()` requires a compatible native helper; disabled
+or missing helpers throw `FsSafeError` with `helper-unavailable`. Windows and
+other unsupported platforms throw `unsupported-platform`. Native creation
+failures throw `helper-failed` with the original error as `cause`.
+The cause's `code` preserves the native errno, including `EMFILE` (the process
+descriptor limit) and `ENFILE` (the system-wide limit).
+
+## Handing the writer to a Node stream
+
+A native-created fd must close through its owner, including in Workers.
+Provide the stream's custom close hook; do not let Node close it directly.
+This is the writer handoff contract: retain the owner in the hook rather than
+detaching its descriptor.
+
+```ts
+import { createWriteStream, write, writev } from "node:fs";
+import { createPipe } from "@openclaw/fs-safe/pipe";
+
+const pipe = createPipe();
+const stream = createWriteStream("", {
+  fd: pipe.writer.fd,
+  fs: {
+    write,
+    writev,
+    close(_fd, callback) {
+      try {
+        pipe.writer.close();
+        callback(null);
+      } catch (error) {
+        callback(error instanceof Error ? error : new Error(String(error)));
+      }
+    },
+  },
+});
+// After spawning with pipe.reader.fd in the child's stdio:
+pipe.reader.close();
+stream.end("one-shot input");
+```
+
+Once the stream is created, its lifetime owns use of the writer: keep an error
+listener, destroy it on cancellation, and wait for `close` before considering
+the fd released. If stream construction fails, close both owners. Closing the
+last writer delivers EOF; unread bytes remain available to the reader.