@openclaw/fs-safe 0.19.0 → 0.21.0

package/dist/windows-security-command.js

@@ -3,10 +3,11 @@ import { fileURLToPath } from "node:url";
 import { FsSafeError } from "./errors.js";
 import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
-import { parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
+import { parseWindowsOwnerAndDaclFacts, parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TERMINATION_GRACE_MS = 1_000;
 const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
+export const WINDOWS_SECURITY_BATCH_MAX_BYTES = 16 * 1024 * 1024;
 function isFullIdentity(identity) {
     return typeof identity === "string" && identity.length === 49 && FULL_IDENTITY.test(identity);
 }
@@ -76,6 +77,10 @@ function parseReplyValue(stdout, operation) {
         unverified("Windows security command returned an incomplete response");
     }
     if (!response.ok) {
+        if (operation === "paths" &&
+            (response.code === "helper-unavailable" || response.code === "too-large") && typeof response.message === "string") {
+            throw new FsSafeError(response.code, response.message);
+        }
         const codes = new Set(["EACCES", "EPERM", "EEXIST", "ENOENT", "ENOTSUP", "EIO", "EBADF", "ELOOP", "ENOTDIR", "EINVAL", "ENOSPC", "EBUSY"]);
         if (typeof response.code !== "string" || !codes.has(response.code) || typeof response.message !== "string") {
             unverified("Windows security command returned an invalid failure");
@@ -112,13 +117,13 @@ class WindowsSecurityCommandError extends PermissionCommandError {
     timedOut;
     creationOutcome;
     processExitConfirmed;
-    constructor(file, durationMs, receipt, timedOut) {
-        super(file, durationMs, receipt);
+    constructor(file, durationMs, receipt, timedOut, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+        super(file, durationMs, receipt, timeoutMs);
         this.timedOut = timedOut;
         this.creationOutcome = receipt.creationOutcome;
         this.processExitConfirmed = receipt.processExitConfirmed;
         if (timedOut)
-            this.message = `Windows permission inspection timed out after ${DEFAULT_PERMISSION_EXEC_TIMEOUT_MS}ms`;
+            this.message = `Windows permission inspection timed out after ${timeoutMs}ms`;
         if (!receipt.processExitConfirmed)
             this.message += "; process exit was not confirmed";
         else if (!receipt.outputClosed)
@@ -156,11 +161,12 @@ export function hasUnsettledWindowsSecurityCommand(error) {
     return pending.length > 0;
 }
 function ignoreLateError() { }
-async function execute(operation, params) {
-    const { file, args, env } = command(operation, params);
+async function execute(operation, params, request) {
+    const selected = request ?? command(operation, params);
+    const { file, args, env, input, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, maxOutputBytes = MAX_OUTPUT_BYTES } = selected;
     const startedAt = performance.now();
     return await new Promise((resolve, reject) => {
-        const child = spawn(file, args, { windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"] });
+        const child = spawn(file, args, { windowsHide: true, env, stdio: [input === undefined ? params.fd ?? "ignore" : "pipe", "pipe", "pipe"] });
         const output = [];
         const errors = [];
         let bytes = 0;
@@ -180,7 +186,7 @@ async function execute(operation, params) {
         const timeout = setTimeout(() => {
             timedOut = true;
             fail(deadlineError());
-        }, DEFAULT_PERMISSION_EXEC_TIMEOUT_MS);
+        }, timeoutMs);
         const finish = (outputClosed) => {
             if (settled)
                 return;
@@ -193,6 +199,18 @@ async function execute(operation, params) {
             child.removeListener("error", onChildError);
             child.on("error", ignoreLateError);
             const cleanupErrors = [];
+            if (input !== undefined && child.stdin) {
+                child.stdin.removeListener("error", fail);
+                child.stdin.on("error", ignoreLateError);
+                if (!outputClosed) {
+                    try {
+                        child.stdin.destroy();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+            }
             for (const [stream, collect] of [[child.stdout, collectOutput], [child.stderr, collectErrors]]) {
                 if (!stream)
                     continue;
@@ -221,7 +239,7 @@ async function execute(operation, params) {
                     cause: failure, pid: child.pid ?? null, code: exitCode, signal: exitSignal, stderr: Buffer.concat(errors),
                     processExitConfirmed, outputClosed, terminationSignalSent, terminationError, cleanupErrors,
                     ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
-                }, timedOut));
+                }, timedOut, timeoutMs));
             }
             else {
                 try {
@@ -260,7 +278,7 @@ async function execute(operation, params) {
             if (failed || settled)
                 return;
             bytes += chunk.length;
-            if (bytes <= MAX_OUTPUT_BYTES)
+            if (bytes <= maxOutputBytes)
                 chunks.push(chunk);
             else
                 fail(new Error("Windows security command exceeded its output budget"));
@@ -282,7 +300,7 @@ async function execute(operation, params) {
         };
         const onClose = (code, signal) => {
             onExit(code, signal);
-            if (!failed && performance.now() - startedAt >= DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+            if (!failed && performance.now() - startedAt >= timeoutMs) {
                 timedOut = true;
                 failed = true;
                 failure = deadlineError();
@@ -298,11 +316,47 @@ async function execute(operation, params) {
         child.stderr?.on("error", fail);
         child.stdout?.on("data", collectOutput);
         child.stderr?.on("data", collectErrors);
-        if (!child.stdout || !child.stderr) {
+        if (!child.stdout || !child.stderr || (input !== undefined && !child.stdin)) {
             // Node reports spawn errors on nextTick, which can follow the current microtask.
             missingPipes = setImmediate(() => { if (!failed && !settled)
                 fail(new Error("Windows security command output pipes are unavailable")); });
         }
+        if (input !== undefined && child.stdin) {
+            child.stdin.on("error", fail);
+            try {
+                child.stdin.end(input, "utf8");
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+    });
+}
+export async function readWindowsSecurityFactsBatch(paths, options) {
+    const invocation = command("paths", {});
+    const request = {
+        ...invocation,
+        input: JSON.stringify(paths),
+        timeoutMs: options.timeoutMs,
+        maxOutputBytes: WINDOWS_SECURITY_BATCH_MAX_BYTES,
+    };
+    if (options.native) {
+        request.file = process.execPath;
+        request.args = ["--", fileURLToPath(new URL("./owner-dacl-batch-worker.js", import.meta.url))];
+        request.env = {
+            ...Object.fromEntries(Object.entries(invocation.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH", "FS_SAFE_OWNER_DACL_BATCH_MODE"].includes(key.toUpperCase()))),
+            FS_SAFE_OWNER_DACL_BATCH_MODE: options.mode,
+        };
+    }
+    const response = await execute("paths", {}, request);
+    if (!Array.isArray(response) || response.length !== paths.length) {
+        unverified("Windows security command returned an incomplete path batch");
+    }
+    return response.map((row, index) => {
+        if (!record(row) || row.path !== paths[index]) {
+            unverified("Windows security command returned a mismatched path batch");
+        }
+        return parseWindowsOwnerAndDaclFacts(row.security);
     });
 }
 export function readWindowsSecurityFactsCommand(targetPath) {

package/dist/windows-security-facts.d.ts

@@ -1,5 +1,8 @@
 import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+export type DescriptorFacts = Pick<NativeWindowsSecurityFacts, "ownerSid" | "currentUserSid" | "daclPresent" | "isLocal" | "aceListComplete" | "unsupportedAceTypes" | "aces">;
 export declare function unverified(message: string, cause?: unknown): never;
+/** Validate policy-free observations crossing the isolated batch transport. */
+export declare function parseWindowsOwnerAndDaclFacts(value: unknown): DescriptorFacts;
 /** Raw reporting retains unknown flag bits; secure admission validates them below. */
 export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
 /** Native and command observations share the same fail-closed admission policy. */

package/dist/windows-security-facts.js

@@ -46,6 +46,10 @@ function validateDescriptor(value, allowUnknownFlags) {
     }
     return value;
 }
+/** Validate policy-free observations crossing the isolated batch transport. */
+export function parseWindowsOwnerAndDaclFacts(value) {
+    return validateDescriptor(value, true);
+}
 function summarize(facts) {
     const ownerClass = facts.ownerSid === facts.currentUserSid ? "current-user"
         : facts.ownerSid === SYSTEM_SID ? "system"

package/docs/advanced.md

@@ -77,10 +77,11 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
+| `retainFileInDirectory`, `RetainedFile`, related receipt/result types | [Retained Windows files](retained-file.md) | Existing-file native handle custody and explicit removal; local NTFS, producer authority required, no persistence guarantee. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
-| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
+| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks, inspecting raw segments before `..` normalization. A `..` may undo an inspected real directory, but cannot leave the root or undo an allowed root-child symlink. Raw paths outside the root that normalize inside are rejected. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
 `pathExists()` and `pathExistsSync()` intentionally retain ordinary `stat`
@@ -240,6 +241,7 @@ atomic replacement, use [`Root.write()`](writing.md).
 | Export | Page | Notes |
 |---|---|---|
 | `stageFileInDirectory`, `StagedFile`, `StagedFileReceipt`, `PublishedFileReceipt`, `StagedFilePublication`, `StagedFileCleanupReceipt`, `StagedFileFailureDetails` | [staged-file.md](staged-file.md) | Native-required Linux/macOS lifecycle retaining the original directory for abort cleanup. |
+| `retainSymlinkInDirectory`, `StagedSymlink`, `StagedSymlinkExpected`, `StagedSymlinkReceipt`, `PublishedSymlinkReceipt`, `StagedSymlinkPublication`, `StagedSymlinkRemoval`, `StagedSymlinkCleanupReceipt`, `StagedSymlinkFailureDetails` | [staged-symlink.md](staged-symlink.md) | Native-required retained symlink identity, no-replace publication and explicit recovery; never same-target ownership adoption. |
 | `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.md) | One-file temp primitive; prefer `tempWorkspace` from `@openclaw/fs-safe/temp` for the stable surface. |
 | `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Callback-produced file staging: verified sibling publication or private-workspace copy through a root. |
 
@@ -256,7 +258,7 @@ atomic replacement, use [`Root.write()`](writing.md).
 |---|---|---|
 | `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
 | `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `Error` by default, or an error supplied by `createError`. |
-| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. |
+| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. Allowed roots constrain the real parent of the moved entry, including symlinks; the referent is not moved. Parent identity is rechecked before mutation. |
 
 ## Stability
 

package/docs/archive.md

@@ -211,6 +211,14 @@ loading, including failure. Public preflight still returns ordinary JSZip entry
 objects, with directory keys ending in `/` and recognizable symlink type bits.
 Compressed data is retained even for declared-zero entries, so an empty-size
 claim cannot bypass payload-size or CRC verification during extraction or reads.
+Extraction and bounded reads retain the admitted CRC and size independently of
+mutable decoder objects, so later decoder changes cannot redefine the expected
+payload integrity. Public preflight archives retain ordinary JSZip mutation
+and entry-reading behavior.
+Portable bounded reads select the admitted canonical name and reject a selected
+decoder entry that no longer belongs to that archive and name before reading its
+payload. Extraction retains the admitted names and physical order independently
+of later changes to the decoder's public `files` object.
 
 Within one ZIP entry, identical local and central name bytes reuse the same
 decoded validation. Unicode Path admission is shared only when both the raw names

package/docs/atomic.md

@@ -60,6 +60,8 @@ type ReplaceFileAtomicOptions = {
   syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
   syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
   throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
+  assertBeforeMutation?: () => void;
+  onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
   fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
 };
@@ -108,6 +110,65 @@ descriptor is still closed, and a close failure remains reportable.
 
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
+### Atomic write authority and destination state
+
+Use `assertBeforeMutation` when a write depends on a lease or other revocable
+application authority. Both atomic variants capture the callback at entry and
+run it synchronously before directory creation or mode changes, compatibility
+lock acquisition, staging creation and writes, each rename attempt, and fallback
+removal, destination acquisition, truncation, and each content write. Asynchronous destination identity checks
+finish before the final authority check; no await separates that check from the
+write dispatch. A dispatched operation still owns its completion.
+
+`onDestinationState` captures facts that a caller may need if the operation later
+rejects:
+
+```ts
+type ReplaceFileAtomicDestinationState =
+  | Readonly<{ state: "removed"; path: string }>
+  | Readonly<{
+      state: "writing" | "published";
+      path: string;
+      dev: bigint;
+      ino: bigint;
+    }>;
+```
+
+- `removed` follows successful removal of an existing fallback destination.
+- `writing` records the fallback's retained descriptor after exclusive creation
+  or the first successful truncation of an existing `restore-original` target.
+  Opening an existing target leaves it untouched and emits no receipt. This state
+  does not claim that all requested bytes were written.
+- `published` follows successful rename and destination identity verification,
+  before parent synchronization or descriptor close can fail. Copy fallback
+  reports it after its content, mode, and requested file synchronization complete.
+  The explicit `verify-content-with-lock` policy first applies its existing
+  locked content verification to admit the replacement descriptor.
+
+Receipts are frozen and use the destination spelling captured by the operation.
+File identities come from retained descriptors, never from reopening a pathname
+after a failed copy. Failed or indeterminate admission can leave no identity
+receipt; a rename followed by replacement before verification also has no
+publication receipt. Do not infer ownership from a fresh post-failure stat. A later writer
+can replace the pathname, so compare the recorded identity with the current
+entry and recheck application authority before compensation. Receipts do not
+promise durable storage or authorize rollback.
+
+Both callbacks must complete synchronously; Promise and thenable results are
+rejected, and ordinary return values are ignored. The first callback refusal
+is terminal, including falsy thrown values; an `EPERM`, `EEXIST`, or `EBUSY` code
+from a callback never starts fallback or retry. Refusal during an in-place
+fallback also stops new restoration writes. Final mode, synchronization, close,
+and private-stage cleanup may still settle against owned identities after
+revocation. Callback refusal does not delete a published destination or a
+competing file at a staging name. An observer that throws must retain its receipt
+first if recovery needs it.
+
+`beforeRename` remains the hook for preparing backups. Effects performed inside
+that hook remain the caller's responsibility; the authority option guards the
+atomic writer's own effects. Omitting both new callbacks preserves existing
+write, fallback, restoration, result, and cleanup behavior.
+
 ### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
@@ -295,9 +356,9 @@ semantics. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
 temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
-It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
-you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
-or custom copy-fallback policy.
+It delegates to `replaceFileAtomic()` with a smaller call shape, including its
+pre-publication hook and staging-prefix options. Use `replaceFileAtomic()` when
+you need mode preservation or a custom copy-fallback policy.
 
 ```ts
 import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
@@ -317,9 +378,17 @@ type WriteTextAtomicOptions = {
   dirMode?: number;          // parent mode (default 0o777 masked by process umask)
   trailingNewline?: boolean; // append "\n" if missing; default false
   durable?: boolean;         // default true; false skips temp/parent fsync
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  tempPrefix?: string;       // default ".fs-safe-replace"
 };
 ```
 
+`beforeRename` is awaited after the complete text is staged and before
+publication, with the same [stage identity and refusal cleanup](#beforerename)
+checks as `replaceFileAtomic`. Pass `tempPrefix` to identify staged files; it
+uses the same prefix validation, including rejection of empty prefixes and path
+separators.
+
 `durable: false` keeps the sibling-temp replace/rename behavior but skips the
 temp-file and parent-directory `fsync` calls. Use it only for reconstructible
 metadata where lower latency matters more than crash-durability.

package/docs/contributing.md

@@ -70,6 +70,36 @@ Consumers receive the asset in the npm package and need no compiler.
 
 Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
 
+### Linux GNU release bindings
+
+GNU x64 and arm64 artifacts use Zig 0.16.0 and `cargo-zigbuild` 0.23.4 with an
+explicit glibc 2.28 target, independent of the runner's libc. This matches the
+Node Linux runtime baseline and supports RHEL 8-family users without adding a
+second legacy package. Run the same build and ABI gate used in CI and releases:
+
+```bash
+cargo install cargo-zigbuild --version 0.23.4 --locked
+rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs x86_64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs aarch64-unknown-linux-gnu
+```
+
+These commands require Zig on `PATH` and GNU `objdump`. They build the N-API
+cdylib with `cargo zigbuild --target <triple>.2.28`, copy it to the existing
+`artifacts/fs-safe-native.<platform>.node` name, and reject any GLIBC symbol
+requirement above 2.28 before upload. The gate also rejects missing or unknown
+GLIBC versions. To inspect an existing binding, use
+`node scripts/check-linux-glibc.mjs <binding.node>`.
+
+`pnpm native:build` remains a host-toolchain development build; it does not
+establish the GNU release ABI floor.
+
+On Linux x64 with Docker, run `pnpm build`, copy the GNU x64 artifact from
+`artifacts/` to `native/`, run `node scripts/stage-host-native.mjs`, then run
+`bash scripts/test-linux-glibc-floor.sh`. CI uses this command to load the actual
+artifact and run native security and no-replace move tests in Rocky Linux 8
+(glibc 2.28). GNU arm64 is cross-built and symbol-checked in the same CI matrix.
+
 ## Test
 
 ```bash
@@ -137,6 +167,11 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+The native watch lane requires events on Linux, macOS, and Windows and reports
+actual edit latency. Run `FS_SAFE_TEST_SERIAL=1 pnpm check` to isolate local timing
+checks from the other filesystem stress suites. Watch fixtures use normal OS
+temporary storage; session scratch trees may suppress macOS filesystem events.
+
 ### Method benchmarks
 
 `pnpm benchmark:methods` measures the callable library surface against synthetic

package/docs/durability.md

@@ -436,3 +436,10 @@ owning product boundary.
 - [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
 - [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
 - [Errors](errors.md) — typed operational failure handling.
+
+## Existing Windows file retirement
+
+[`retainFileInDirectory`](retained-file.md) describes identity-bound native
+disposition and resource settlement separately from persistence. Its result is
+always `persistence: "not-proven"`; neither accepted disposition nor observed
+namespace absence is a directory/volume barrier or an application commit.

package/docs/index.md

@@ -65,6 +65,7 @@ await fs.remove("notes/archive/today.txt");
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
+| [`watch`](watch.md) | Guarded filesystem observation with advisory native hints and polling. |
 | [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
 | [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
 | [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |

package/docs/install.md

@@ -134,6 +134,16 @@ when the matching package is absent, incompatible, or disabled.
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.
 
+### Older Linux kernels and seccomp
+
+The native addon supports kernels without `openat2` (before Linux 5.6) and
+containers returning `ENOSYS` or probe-time `EPERM` for that syscall. Beneath
+opens use a guarded no-follow component walk and report `best-effort`.
+Nested no-clobber moves retain atomic `renameat2(RENAME_NOREPLACE)` and exact
+identity checks; keep native mode enabled. Strict bounded cleanup still
+requires `openat2` with `RESOLVE_NO_XDEV` and reports `helper-unavailable`
+without it. See [Linux capability behavior and limits](native.md#linux-without-openat2).
+
 ### Windows security fallback
 
 Windows raw owner/DACL inspection, private-directory creation, and secure-file
@@ -161,6 +171,24 @@ available native operation's error never triggers a command retry. See
 
 ## Native helper policy
 
+### Supported native platforms
+
+Prebuilt bindings cover Linux x64/arm64 (GNU glibc **2.28 or newer**, or musl),
+macOS x64/arm64, and Windows x64. The GNU baseline includes RHEL 8, Rocky Linux 8,
+and AlmaLinux 8. A compatible Node 22+ runtime and the kernel/filesystem features
+required by each operation are still necessary; a loadable addon alone does not
+guarantee every native capability. Systems older than glibc 2.28 are outside the
+GNU binary support floor.
+
+A missing or incompatible optional binding (including `ERR_DLOPEN_FAILED` from
+glibc) does not prevent importing fs-safe. In `auto`, supported JavaScript/WASM
+fallbacks remain available. Native-only operations such as the default
+no-clobber `Root.move()` still fail closed with `helper-unavailable`; `require`
+also rejects fallback-capable operations and retains the binding load error as
+the cause.
+
+### Loading modes
+
 The platform native binaries provide fd-relative open/link/mkdir primitives,
 atomic no-replace rename, and file identity checks. The default is `auto`: use
 the matching binary when it loads, otherwise use the guarded JavaScript path

package/docs/native-helper.md

@@ -103,7 +103,7 @@ clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Without `openat2`, beneath opens use the [no-follow component walk](native.md#linux-without-openat2) with exact identity checks and report `best-effort`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup still requires `openat2` with `RESOLVE_NO_XDEV` and fails closed when unavailable.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
 - Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
 
@@ -139,11 +139,12 @@ for the exact difference.
 The guarded JavaScript mutation path is detection-based, not containment-atomic.
 If a same-privilege peer can replace a writable parent after its identity guard
 but before Node resolves a pathname mutation, the mutation can land outside the
-intended root before the post-operation guard throws. Select `require` rather
-than `auto` or `off` when that concurrent attacker is part of the threat model.
+intended root before the post-operation guard throws. Native `require` ensures the addon is present, but does not require a
+`kernel-atomic` resolver; inspect containment and use OS isolation when that
+concurrent attacker is part of the threat model.
 
 `openBeneath()` returns `{ fd, containment }`. `containment` is
-`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for the Linux fallback, macOS and
 Windows. Public JavaScript root open/read/writable results also expose the
 field and report `"best-effort"`; the label reports mechanism, not policy.
 
@@ -181,3 +182,12 @@ consumer performs its 0.5 upgrade.
 - [Durability](durability.md)
 - [Migrating to 0.5](migrating-to-0.5.md)
 - [Migrating to 0.6](migrating-to-0.6.md)
+
+### Retained existing Windows file
+
+The maintained Windows helper supports the public
+[`retainFileInDirectory`](retained-file.md) lifecycle on fixed local NTFS.
+Private native handles, exact identity/generation checks, writable-section
+admission and explicit close results stay behind that public API. Older helpers
+without this capability are unsupported; there is no pathname deletion fallback.
+No Windows namespace persistence barrier is provided.

package/docs/native.md

@@ -43,6 +43,7 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 - 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).
 - 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,
@@ -85,6 +86,49 @@ privately owned empty ACL. Unsupported, malformed, and failed inspection is not
 reported as absence. These facts do not classify individual ACE permissions or
 prove volume ownership enforcement; each caller applies its own security policy.
 
+## Linux without openat2
+
+Linux kernels before 5.6 and containers whose seccomp policy denies `openat2`
+can keep native mode `auto` or `require`. The addon caches one harmless
+`openat2(".")` capability probe per process. `ENOSYS`, or `EPERM` on that probe,
+selects the native `openat` fallback. An `EPERM`/`EACCES` from an application
+operation is still a permission error and never triggers a retry. Install
+syscall filters before the first native operation; a later `ENOSYS` fails with
+`ENOTSUP`, rather than changing the cached mechanism during a call.
+
+The fallback opens each directory relative to a retained descriptor with
+`O_PATH | O_DIRECTORY | O_NOFOLLOW`, compares exact device/inode/type identities,
+and rechecks the retained parent chain before and after the final no-follow
+open. It rejects all symlink components, including procfs magic links, even
+when the low-level caller requests symlink following. Public Root policy and
+canonical-path admission, hardlink rejection, pinned-file checks, and mutation
+identity fences remain in place. `openBeneath()` reports `best-effort`: these
+identity samples detect replacements but cannot make a multi-component walk
+atomic against a hostile process renaming directories between samples. This
+is the same documented containment class as the macOS and JavaScript paths;
+applications requiring atomic beneath resolution must check the result or use
+OS isolation. Rejection after a mutating open does not promise rollback.
+
+Nested no-clobber `Root.move()` still admits both parents and uses
+`renameat2(RENAME_NOREPLACE)`. Existing destinations are never overwritten.
+That separate syscall/filesystem capability remains required; if unavailable,
+the operation fails with `helper-unavailable`. Turning native mode `off` still
+disables no-clobber moves because Node has no equivalent atomic rename API.
+
+Bounded owned-tree cleanup deliberately has no `openat` fallback:
+`RESOLVE_NO_XDEV` rejects bind mounts even when device numbers match, which
+ordinary identity checks cannot reproduce. `cleanupSafety: "require-bounded"`
+fails before workspace creation with `helper-unavailable`; low-level cleanup
+opens report `ENOTSUP`. Compatible cleanup retains its documented behavior.
+Low-level `O_TMPFILE` anonymous opens also fail before creation with `ENOTSUP`
+in the fallback, because named-entry identity checks cannot verify an unnamed
+file. Public staged-write APIs use exclusive named files and remain available.
+
+For tests, set `FS_SAFE_TEST_NO_OPENAT2=1` before starting Node to force the
+fallback (including bounded-cleanup refusal). It is read only at the first
+capability probe. It has no effect on macOS or Windows.
+See [Linux fallback testing](testing.md#linux-openat2-fallback).
+
 ## Archives
 
 Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
@@ -252,7 +296,7 @@ See [Root containment guarantees](security-model.md#containment-guarantees-by-pl
 
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` on Linux and `best-effort` on macOS and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` with Linux `openat2` and `best-effort` with the guarded Linux fallback, macOS, and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
 | ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
 | 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. |

package/docs/permissions.md

@@ -185,6 +185,72 @@ the same raw ACE projection. Native `require` rejects either absence with
 query's failure is terminal. The existing coarse `inspectPathPermissions()` API
 still owns its compatibility fallback and trust classification.
 
+### Asynchronous batches
+
+Use `readOwnerAndDaclBatch()` when several paths, such as a directory and its
+ancestors, need inspection without blocking the caller's event loop:
+
+```ts
+import { readOwnerAndDaclBatch } from "@openclaw/fs-safe/permissions";
+
+const facts = await readOwnerAndDaclBatch(stagingDirectories, { timeoutMs: 60_000 });
+```
+
+```ts
+function readOwnerAndDaclBatch(
+  paths: readonly string[],
+  options?: { timeoutMs?: number },
+): Promise<OwnerAndDaclResult[]>;
+```
+
+Results use the same raw fact shape and SID spelling as `readOwnerAndDacl()`.
+They correspond one-for-one to input order, including duplicate paths. An empty
+array returns `[]` without dispatch. Other platforms return an
+`unsupported-platform` result for each path. Query failures, malformed facts,
+or missing/reordered response rows reject the entire batch; no partial facts
+are returned. Null DACLs, incomplete ACE lists and nonlocal observations remain
+raw facts for the caller's policy to evaluate.
+
+The call captures paths, options and native mode before awaiting. Windows
+relative paths are anchored to the current directory or selected drive at
+entry, without normalizing their remaining `.` or `..` components. Empty,
+nonstring, sparse or NUL-containing path entries and Windows namespace aliases
+reject before dispatch. The UTF-8 JSON input is limited to 16 MiB.
+
+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`
+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
+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.
+The error's `processExitConfirmed` field, also retained in its cause receipt,
+distinguishes observed exit from an unconfirmed termination attempt. An
+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,
+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
+error, and no partial facts are returned. Duplicate paths remain independent
+observations. This bounds accumulated encoded results, not total process memory:
+the current descriptor and row, decoded input, and runtime overhead still exist.
+
+Batch observations are point-in-time pathname facts, not a snapshot or a
+retained filesystem capability. The caller still owns ancestry trust, principal
+policy and authorization for subsequent operations. Existing singular queries
+and other command operations retain their 30-second deadline, 1 MiB output
+budget and documented failure behavior.
+
 ## Private directories
 
 ```ts